📖Command Reference

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.

Flag	Values	Description
--model	model ID	Omit for the account default.
--size	1K | 2K | 4K	Output resolution.
--aspect-ratio	1:1 | 16:9 | 9:16 | 4:3 | 3:2	Omit for square.
--n	1-10	Number 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.

Flag	Values	Description
-i, --image	path or HTTPS URL	Input image, repeatable 1-5 times. A local path is uploaded for you; an HTTPS URL is used as-is.
-m, --model	model ID	Omit for the account default.
-s, --size	1K | 2K | 4K	Omit 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.

Flag	Values	Description
--mode	text | image | reference | frames | extend | lipsync | edit	Generation mode. Default text.
--duration	seconds	Video duration.
--resolution	480p | 720p | 1080p	Output resolution.
--sound / --no-sound	—	Enable (default) or disable audio generation.
--image	URL	Seed image (modes image, edit).
--reference	URL(s)	Style reference image URL(s), repeatable (mode reference).
--start-frame	URL	Start frame (mode frames).
--end-frame	URL	End frame (mode frames, optional).
--source-video	URL	Source video (modes extend, lipsync, edit).
--audio	URL	Audio track (mode lipsync).

Each mode requires a specific set of fields:

Mode	Prompt	Also requires
text	required	—
image	required	--image
reference	required	--reference (1 or more)
frames	required	--start-frame (--end-frame optional)
extend	required	--source-video
lipsync	none	--source-video and --audio
edit	required	--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.

Flag	Values	Description
--media-type	image | video	Filter by media type.
--topic	topic string	Filter by topic bucket (see caveat below).
--model	model ID	Only templates built for that target model.
--featured	—	Only editor-picked templates.
--trending	—	Only currently trending templates.
--tags	tag(s)	Filter by tags, matched as a set.
--limit	1-100	Page size, default 30.
--offset	≥0	Rows 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.

Flag	Values	Description
--type	image | video	Filter by generation type.
--status	pending | completed | failed	Filter by status.
--limit	1-50	Max 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.

Flag	Values	Description
--period	7d | 30d | 90d	Time 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.