generate
Generate AI media by running a job with params from get_model_params. Enforces spend guardrails and accepts URLs for media inputs.
Instructions
Run a media generation job on Pixio, with spend guardrails.
This is the final step of the 3-call discovery contract:
list_models -> get_model_params -> generate. Build params
from the live get_model_params(model_id) response — this server
embeds no model schemas. On a first attempt send EVERY param the schema
lists, at its default value (some params marked optional are actually
required by the gateway), and send select-option values as STRINGS
(e.g. "5", not 5).
URLs-only contract: every media input inside params must be an
http(s) or data: URL. Any value that looks like a local filesystem path
(~, ./, ../, file://, X:\, UNC \\, or an
existing file) is rejected with a VALIDATION error naming the offending
field(s) — before any credits are spent. Call upload_media first and
pass the permanent URL it returns.
Spend guardrails: the job cost is estimated up front and refused with
BUDGET_EXCEEDED if it exceeds the per-job cap or would exceed the
session budget — no credits are spent on a refusal. Pass confirm=true
to explicitly override both caps for this one job.
Waiting: with wait=true (default) this call polls until the job is
terminal or timeout_s elapses (default: PIXIO_DEFAULT_TIMEOUT_S,
180s). On timeout you get a TIMEOUT_PENDING error whose details carry
the generation_id — the job KEEPS RUNNING server-side; resume with
wait_for_generation(generation_id). With wait=false the call
returns immediately (status "processing", plus estimated_credits);
check later with get_generation or wait_for_generation.
Output URLs may be signed and expire after roughly an hour — call
download_output(generation_id) promptly.
Args:
model_id: Pixio model id, e.g. "pixio/flux-1/schnell".
params: Generation inputs built from get_model_params (URLs only
for media fields).
wait: Poll to completion (True, default) or return immediately.
timeout_s: Max seconds to wait when wait=true; None uses the
server default.
confirm: Set True to override the per-job and session credit caps.
Returns:
On success: {"generation_id", "status", "output_urls", "outputs",
"model_id", "credits_spent", "remaining_balance", "elapsed_s",
"error"}. With wait=false: the same shape with status
"processing", credits_spent None, and estimated_credits
added. On failure: {"error": {"code", "message", "details"}} with
code VALIDATION, BUDGET_EXCEEDED, INSUFFICIENT_CREDITS, CONCURRENCY,
GENERATION_FAILED, TIMEOUT_PENDING, NOT_FOUND, AUTH, or
UPSTREAM_ERROR. NOTE: success results also contain an "error" key
(the provider reason, null on success) — a call failed only when
result["error"] is a dict carrying a "code".
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | ||
| params | Yes | ||
| confirm | No | ||
| model_id | Yes | ||
| timeout_s | No |