Skip to main content
pixa run is the primary entrypoint for all image and video tasks. It has subcommands for prompts, direct tools, and pipelines.

​
Three modes

Prompt-driven tasks — Describe what you want and the AI agent picks the right tools: 
pixa run prompt "remove the background" \
  --attachment product.png --json
Direct tool execution — Run a specific tool by name: 
pixa run remove-bg product.png --json
pixa run upscale photo.png --scale 4 --json
pixa run expand banner.png --right 200 --json
pixa run model "product photo on marble" --model nano-banana-2 --json
Pipeline execution — Run a saved multi-step workflow by ID: 
pixa run pipeline pl_abc123 \
  --input photo=./product.png --json

​
Prompt mode

Submit a natural-language prompt and the agent selects appropriate tools: 
pixa run prompt "remove the background and upscale 4x" \
  --attachment product.png --json

​
Flags

FlagDescriptionDefault
--attachmentFile path, URL, or asset ID (repeatable)—
--modelModel ID for generation—
--aspect-ratioAspect ratio (e.g., 16:9, 1:1, 4:3)—
--output-formatOutput format: png, jpg, or webp—
--num-variationsNumber of variations to generate—
--brand-libraryBrand library ID for brand-consistent generation—
--asyncReturn immediately with job IDfalse
--dry-runValidate and print the request without executingfalse
--skip-saveDon’t save results to the workspacefalse
--collection-idSave results to a specific collection—
--outputDownload result to this file path—
--jsonOutput in JSON formatfalse

​
JSON input

For complex requests, pass a JSON body instead of individual flags: Via --json-input flag: 
pixa run prompt --json-input '{
  "message": "remove the background",
  "attachments": [{"url": "https://example.com/photo.png"}]
}' --json
Via stdin pipe: 
echo '{
  "message": "remove the background and upscale 4x",
  "attachments": [{"url": "https://example.com/photo.png"}]
}' | pixa run prompt --json
JSON input schema: 
{
  "message": "remove the background",
  "attachments": [
    { "url": "https://example.com/photo.png" }
  ],
  "generation_settings": {
    "model_id": "nano-banana-2",
    "aspect_ratio": "16:9",
    "output_format": "png",
    "num_variations": 2,
    "brand_library_id": "<library-id>"
  }
}

​
Direct tools

Run a specific tool without going through the AI agent:
ToolUsage
remove-bgpixa run remove-bg <file, url, or asset-id>
upscalepixa run upscale <file> --scale 4
expandpixa run expand <file> --right 200 --bottom 100
modelpixa run model "prompt" --model <model-id>
Direct tools accept --async, --dry-run, --skip-save, --collection-id, --output, --set key=value, and --attachment name=value.

​
Pipeline mode

Run a saved pipeline by ID with inputs mapped to node names: 
pixa run pipeline pl_abc123 \
  --input photo=./product.png \
  --input prompt="white background" \
  --json
FlagDescription
--inputNode input as name=value (repeatable; value is file path, URL, asset ID, or text)
--asyncReturn immediately with job ID
--dry-runValidate without executing
--collection-idSave results to a specific collection
Local file paths in --input values are auto-uploaded.

​
Examples

​
Remove a background

pixa run prompt "remove the background" \
  --attachment product.png --json
Or directly: 
pixa run remove-bg product.png --json

​
Image generation with settings

pixa run prompt "a minimalist product photo on a marble surface" \
  --model nano-banana-2 \
  --aspect-ratio 16:9 \
  --output-format png \
  --num-variations 3 --json
Or with the model tool directly: 
pixa run model "a minimalist product photo on a marble surface" \
  --model nano-banana-2 --aspect-ratio 16:9 --num-variations 3 --json

​
Brand-consistent generation

pixa run prompt "social media banner for summer sale" \
  --brand-library lib_brand456 \
  --aspect-ratio 16:9 --json

​
Pipeline with inputs

pixa run pipeline pl_abc123 \
  --input photo=./product.png \
  --input prompt="lifestyle scene" \
  --collection-id col_xyz789 --json

​
Result handling

​
Success response

With --json, a successful run returns: 
{
  "ok": true,
  "data": {
    "job_id": "job_abc123",
    "status": "completed",
    "assets": [
      {
        "id": "ast_def456",
        "url": "https://assets.pixa.dev/ast_def456.png",
        "content_type": "image/png"
      }
    ]
  },
  "meta": {
    "duration_ms": 3200
  }
}

​
Error response

{
  "ok": false,
  "error": {
    "code": "invalid_attachment",
    "message": "attachment not found: product.png",
    "hint": "Check the file path or use a URL with --attachment"
  }
}
The hint field provides actionable recovery steps when available. Agents should surface this to the user.

​
Tips

  • Use --json for machine-readable output. Agents should always set this flag.
  • Without --async, prompt and pipeline commands wait for the job to complete before returning.
  • Use --dry-run to validate a request without executing it.
  • Use --output to download results directly to a local file.
  • Without --async, the command waits for completion. With --async, use pixa jobs follow to stream status updates.