@shellbot/openclaw-pixcli

OpenClaw tool plugin for pixcli — give any OpenClaw / ShellBot agent first-class, typed tools to generate and edit images, video, voiceover, music, sound effects, and full podcasts.

It's a thin, native client over the hosted pixcli API (https://pixcli.hilo.cx): each tool submits an async job, waits for it, and returns a shareable URL. No subprocess, no pixcli npm install at runtime. The plugin also contributes standing usage guidance to the agent (so it knows which tool to reach for) via each tool's rich description plus a memory prompt supplement.

Install

openclaw plugins install clawhub:shellbot/openclaw-pixcli

Configure

Set an API key via plugin config or the METERKEY_API_KEY environment variable.

// openclaw config
{
  plugins: {
    entries: {
      pixcli: {
        config: {
          apiKey: "mk-prod-...",          // or set METERKEY_API_KEY in the environment
          defaultPublish: "public",  // auto-publish results → shareable URLs (public | private)
          // baseUrl: "https://pixcli.hilo.cx",
          // pollTimeoutMs: 600000,
        },
      },
    },
  },
}

Get a key at https://shellbot.sh.

Tools

Sipcast multilanguage — two independent modes

A sipcast can carry languages two different ways. They are separate features — pick by intent:

One call can do both / many. pixcli_sipcast accepts learn_languages and/or voiceover_languages arrays, so a single tool call can produce, e.g., a Spanish episode + English & French re-narrations + an English reading overlay. To add either to an existing sipcast, use pixcli_sipcast_learn / pixcli_sipcast_voiceover with its id.

Discovery matters: the learning-overlay link is …/sip/<id>?learn=1&native=<lang> and cannot be guessed from page_url. Always read the overlay/variant links from result.podcast.learn[] and result.podcast.languages[] and surface those to the user — don't reconstruct them by hand. (The normal player page also shows a "Read & learn" button when an overlay exists.)

Opt-in tools must be allowlisted by the host before they're offered to the model:

{ tools: { allow: ["pixcli_voice_clone", "pixcli_dialogue", "pixcli_tryon", "pixcli_publish"] } }

Notes

• Image/audio/video inputs accept a local file path, a data: URI, or an http(s) URL — local files are read and uploaded automatically. Use them as references (logos, style/character, products) or as edit/img2img sources.
• Generation is async. Tools wait up to pollTimeoutMs (default 10 min); on timeout the job keeps running and the result includes a pixcli_job handle to recover it.
• Returned shape: { job_id, status, model, cost, elapsed_ms, share_url, assets[] }. Each asset has a short-lived signed url and (when published) a stable published_url.

Network access

This plugin contacts exactly one host: the pixcli API (default https://pixcli.hilo.cx, overridable via the baseUrl config or PIXCLI_API_URL). It sends the user-provided METERKEY_API_KEY as an Authorization: Bearer header and calls only these endpoints:

• POST /api/v1/generate, /api/v1/generate/advanced — images, virtual try-on
• POST /api/v1/edit, /api/v1/edit/advanced — image edits
• POST /api/v1/video, /api/v1/video/advanced, /api/v1/video/extend
• POST /api/v1/audio/{voice,voice-clone,music,sfx,dialogue,podcast}
• GET /api/v1/models — read-only model list
• GET /api/v1/jobs/:id, /api/v1/jobs/:id/result — job status + results
• POST /api/v1/publish — share-visibility control

No other hosts are contacted; there is no telemetry and no subprocess execution. The only filesystem access is reading a local media file the caller explicitly references (path or data: URI) in order to upload it to the pixcli API. (This is also shipped as clawscan-note.txt.)

Develop

npm install
npm run build          # tsc → dist/

Built artifact: dist/index.js (referenced by openclaw.extensions in package.json). Keep contracts.tools in openclaw.plugin.json in sync with the tools registered in index.ts.

Built by ShellBot. Part of the pixcli project.