Skip to main content
Every pixa command supports a --json flag that wraps the response in a consistent envelope. This makes it straightforward for agents and scripts to parse results without brittle text matching.

​
Success envelope

{
  "ok": true,
  "data": { ... },
  "meta": {
    "total": 12,
    "has_more": false
  }
}
  • ok — Always true for successful responses.
  • data — The result payload. For single-item commands this is an object; for list commands this is an array.
  • meta — Pagination metadata. Present on list responses.

​
Error envelope

{
  "ok": false,
  "error": {
    "code": "not_found",
    "message": "Asset not found",
    "hint": "Check the asset ID and try again"
  }
}
  • ok — Always false for errors.
  • error.code — A machine-readable error code.
  • error.message — A human-readable description.
  • error.hint — An optional recovery suggestion.

​
List responses

When a command returns multiple items, data is an array and meta includes pagination info: 
{
  "ok": true,
  "data": [
    { "id": "asset_001", "name": "photo.png" },
    { "id": "asset_002", "name": "banner.jpg" }
  ],
  "meta": {
    "total": 48,
    "has_more": true
  }
}
Use --limit and --after flags to paginate through results.

​
JSON input shapes for pixa run

​
Prompt mode

{
  "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>"
  }
}

​
Pipeline run

{
  "inputs": {
    "photo": "./product.png",
    "prompt": "white background"
  },
  "collection_id": "<collection-id>"
}

​
Direct tool

{
  "input": "<file path, URL, or asset ID>",
  "scale": "4",
  "attachments": { "name": "<file, url, or asset-id>" }
}
All shapes can be passed via the --json-input flag or piped through stdin: 
# Via flag
pixa run prompt --json-input '{"message":"remove bg","attachments":[{"url":"photo.png"}]}' --json

# Via stdin
echo '{"inputs":{"photo":"./img.png"}}' | pixa run pipeline pl_abc --json

​
Parsing output in shell scripts

Use jq to extract fields from JSON output: 
# Check if a command succeeded
pixa assets search "hero" --json | jq '.ok'

# Extract asset IDs from a search result
pixa assets search "product" --json | jq -r '.data[].id'

# Get the error hint on failure
pixa run remove-bg --json 2>&1 | jq -r '.error.hint // empty'

# Count results
pixa jobs list --json | jq '.meta.total'

​
Common error codes and recovery

CodeMeaningRecovery
not_foundThe requested resource does not existVerify the ID and try again
unauthorizedSession expired or not logged inRun pixa auth login or check PIXA_API_KEY
validation_errorInvalid input (missing flag, bad format)Check the error hint and fix the request
rate_limitedToo many requestsWait and retry after a short delay
conflictResource already exists or is in useUse a different name or resolve the conflict
timeoutThe operation timed outRetry, or use --timeout to increase the limit

​
Next steps

Running Tasks

Learn the full set of flags and patterns for pixa run.

CLI Reference

Explore every command, flag, and input format.