PicX Studio

Command Reference

Every picx-cli command, its flags, and example invocations.

View as Markdown

Every command supports a --json flag for structured output — use it for scripts and AI agents instead of the default human-readable table.

Generation

picx image <prompt>

Generate an image from a text prompt.

FlagValuesDescription
--modelmodel IDOmit for the account default.
--size1K | 2K | 4KOutput resolution.
--aspect-ratio1:1 | 16:9 | 9:16 | 4:3 | 3:2Omit for square.
--n1-10Number of images to generate.
picx image "a sunset over mountains, oil painting style"

picx image "neon cyberpunk city at night" \
  --model gemini-3.1-flash-image-preview \
  --size 2K --aspect-ratio 16:9

Response:

{
  "images": [
    {
      "url": "https://cdn.picxstudio.com/api/generated/image_8871aa96.png",
      "id": "img_537f439a4e58",
      "model": "gemini-3.1-flash-image-preview",
      "size": "2K",
      "aspect_ratio": "16:9"
    }
  ],
  "credits_used": 53,
  "total_images": 1
}

picx image edit <instruction> -i <path|url>

Edit one or more existing images with an AI instruction.

FlagValuesDescription
-i, --imagepath or HTTPS URLInput image, repeatable 1-5 times. A local path is uploaded for you; an HTTPS URL is used as-is.
-m, --modelmodel IDOmit for the account default.
-s, --size1K | 2K | 4KOmit to preserve the original.
# A local file is uploaded for you
picx image edit "remove background, add clean white studio backdrop" \
  -i ./photo.jpg -s 2K

# Or pass an HTTPS URL directly, repeat -i for multiple images
picx image edit "make it nighttime" \
  -i https://cdn.picxstudio.com/api/generated/img.png

picx video [prompt]

Generate a video in one of seven modes. Asynchronous — returns a job id immediately, then poll with picx job <id>. The prompt argument is required for every mode except lipsync, which is driven entirely by its audio track.

FlagValuesDescription
--modetext | image | reference | frames | extend | lipsync | editGeneration mode. Default text.
--durationsecondsVideo duration.
--resolution480p | 720p | 1080pOutput resolution.
--sound / --no-sound—Enable (default) or disable audio generation.
--imageURLSeed image (modes image, edit).
--referenceURL(s)Style reference image URL(s), repeatable (mode reference).
--start-frameURLStart frame (mode frames).
--end-frameURLEnd frame (mode frames, optional).
--source-videoURLSource video (modes extend, lipsync, edit).
--audioURLAudio track (mode lipsync).

Each mode requires a specific set of fields:

ModePromptAlso requires
textrequired—
imagerequired--image
referencerequired--reference (1 or more)
framesrequired--start-frame (--end-frame optional)
extendrequired--source-video
lipsyncnone--source-video and --audio
editrequired--source-video and --image
# text mode (default)
picx video "a drone shot flying over a coastline" --duration 8 --resolution 1080p
# -> { "id": "gen_abc123", "status": "pending" }

# lipsync — no prompt, drive a face to speak an audio track
picx video --mode lipsync \
  --source-video https://cdn.picxstudio.com/api/generated/clip.mp4 \
  --audio https://cdn.picxstudio.com/api/generated/voice.mp3

# frames — interpolate between a start and (optional) end frame
picx video "smooth morph between the two shots" --mode frames \
  --start-frame https://cdn.picxstudio.com/api/generated/a.png \
  --end-frame https://cdn.picxstudio.com/api/generated/b.png

picx job <id>

Poll a generation job's status and get the result URL when done.

picx job gen_abc123
# poll every 10-15s until status is "completed" or "failed"

Assets

picx upload <file>

Upload a local file to get an HTTPS URL for edit/video input.

picx upload ./photo.jpg

picx assets list

List uploaded and generated assets in your account.

picx assets rm <id>

Delete an asset by id.

picx assets rm asset_abc123

Discovery

picx models

List available models and their live credit costs. Always re-check this before a cost-sensitive script — costs change as PicX adds models.

picx templates search [query]

Search the PicX template catalogue (~50K curated prompts). The query argument is optional; filter with the flags below.

FlagValuesDescription
--media-typeimage | videoFilter by media type.
--topictopic stringFilter by topic bucket (see caveat below).
--modelmodel IDOnly templates built for that target model.
--featured—Only editor-picked templates.
--trending—Only currently trending templates.
--tagstag(s)Filter by tags, matched as a set.
--limit1-100Page size, default 30.
--offset≥0Rows to skip, default 0.
picx templates search "product photography"
picx templates search --media-type video --model gemini-3.1-flash-image-preview --limit 5
picx templates search --tags cinematic portrait --featured

Three behaviours to know when reading results back:

  • total is an estimate, not a count. The catalogue is too large to count on every query, so the server returns offset + page length + 1 when more rows exist. To exhaust results, keep increasing --offset by --limit until a page comes back with fewer rows than --limit — that's the last page.
  • The topic filter works, but the topic field is always null. Topic is a query-time keyword bucket, not a stored per-row column. Filter by it; don't expect to read it back off a result.
  • A null prompt means a premium/gated template, not missing data. Such a row still carries its title, preview, and tags, but its prompt is redacted for public API keys and can't be fed into a generation.

picx templates get <id>

Get a single template by id. A null prompt in the response means the template is premium/gated (redacted for public keys), not that data is missing.

picx templates get 38599 --json

Account

picx history

List your recent generations.

FlagValuesDescription
--typeimage | videoFilter by generation type.
--statuspending | completed | failedFilter by status.
--limit1-50Max results, default 20.
picx history --type video --status completed --limit 10

picx whoami

Check API key authentication status and account identity. There is no separate picx auth command — this is the equivalent.

picx balance

Show current credit balance.

picx usage

Show credit usage for a period.

FlagValuesDescription
--period7d | 30d | 90dTime window, default 30d.
picx usage --period 90d

picx tier

Show your account's current plan/tier.

Webhooks

These inspect and replay webhook deliveries — the API-key-authorized subset of the webhook surface. Creating, editing, and deleting webhook endpoints is a session-authenticated dashboard operation and is not available to an API key.

picx webhook deliveries <webhook_id>

List the delivery attempts for one registered webhook endpoint. Use it to find the delivery_id you need for a redelivery.

picx webhook deliveries wh_abc123

picx webhook redeliver <delivery_id>

Replay a stored webhook delivery. This re-fires the same signed payload to the endpoint — a real outbound POST to the customer's URL. It does not regenerate anything and does not cost credits.

picx webhook redeliver del_abc123

picx generation deliveries <generation_id>

List the webhook delivery attempts for a single generation — answers "did the webhook for this render fire, and with what response?"

picx generation deliveries gen_abc123

MCP

picx mcp install --client <claude|cursor>

Install and configure the PicX MCP server for a client. See Connect Claude Desktop or Connect Cursor for what this does manually.

picx mcp install --client claude

picx mcp serve

Start the PicX MCP stdio server locally — the server a client launches to talk MCP over stdio.

picx mcp serve

picx mcp doctor

Health-check the MCP connection and credentials — verifies the endpoint is reachable and the configured API key authenticates before you rely on it.

picx mcp doctor

FAQ

Which commands are free vs. which cost credits?

picx image, picx image edit, and picx video deduct credits per the live costs shown by picx models. Every other command — whoami, balance, usage, tier, history, assets list, assets rm, upload, templates search, templates get, webhook deliveries, webhook redeliver, generation deliveries, mcp install, mcp doctor — is free. Note that webhook redeliver triggers a real outbound POST to the endpoint even though it costs no credits.

Is there a way to see every command's help text from the terminal?

Yes — picx --help lists top-level commands, and picx <command> --help shows that command's flags. This page mirrors that but with runnable examples.

Why is there no picx auth command?

Auth status is reported by picx whoami instead — it confirms the key works and returns account identity in one step, rather than a separate bare "is this key valid" check.

Build with PicX

One API key and one credit balance across the REST API, MCP server, CLI and SDKs.