Image generation API

Prepare your key and budget using the quickstart. The standalone client below checks the catalog, requests a quote, sets an exact cost ceiling, creates a task, replays the identical request, polls, downloads, and checks the charge:

python3 uniroute-media.py --key-file ~/.config/uniroute/api-key \
  --budget-usd 0.05 --kind image --verify-idempotency \
  --state ./image-run.json --output ./image-output

The example uses z-image, mediaKind: "image", and the 16:9 option, with no external image input. Its example quote is 0.0056 USD; use the current quote for the actual amount. Read the catalog from data.models in GET /v1/media/catalog. modelId and param.options[].value determine the request values.

Quote with POST /v1/media/quote:

{
  "model": "z-image",
  "option": "16:9"
}

Create with POST /v1/media/tasks and a unique Idempotency-Key. The amount below is only an example; replace it with the quoted_usd you just received:

{
  "media_type": "image",
  "model": "z-image",
  "option": "16:9",
  "prompt": "A quiet mountain lake at sunrise, watercolor illustration.",
  "max_cost_usd": "0.0056"
}

After HTTP 202, save data.task_id and query GET /v1/media/tasks/{task_id}. Download from urls[].url only when both status: "success" and billing.state: "charged" are satisfied. Do not send your key with downloads. The client saves files in the selected output directory and reports the actual charged_usd.

To change the prompt or options, check the catalog and request a new quote, then use a new idempotency key for an intentional new task. To verify replay, keep the original request body unchanged. Recover an interrupted run using the original state file; recreating a task is not recovery.