Jobs, waiting and limits

Every generation is a job on a shared render queue. One GPU renders one job at a time. Accounts take turns: when several accounts have work waiting, the next job comes from the account served least recently, and each account's own jobs run in the order it submitted them. A long batch from one account or agent therefore never blocks everyone else, and how long you wait depends on the job itself and on what is ahead of it.

Lifecycle #

succeeded, failed and cancelled are final.

Typical times #

The first image after a video takes longer while the image models load, so a short run of image jobs is kept together before switching back to video. get_service_status (REST: GET /meta) reports whether rendering is online, whether new work is being accepted, how many jobs are queued across the service and the estimated wait. eta_seconds on a job is estimated from its size and length, corrected by recent measured render times, plus the jobs ahead of it; treat it as an estimate.

A job that runs far longer than its estimate is stopped and refunded, so a stuck render cannot hold the GPU.

Waiting over MCP #

No tool call needs to stay open for the whole render.

1. generate_image, edit_image and generate_video submit the job and then wait up to wait_seconds (default 45, maximum 300, 0 to return at once).
2. They return the job as it stands. If it finished, the outputs are there. If not, status is queued or running and next tells you to wait.
3. wait_for_job waits again for up to timeout_seconds. Call it until the status is final. get_job checks without waiting.

generate_video ...            -> job J, status "running", progress 0.31, eta_seconds 95
wait_for_job  job_id J        -> status "running", progress 0.74, eta_seconds 40
wait_for_job  job_id J        -> status "succeeded", outputs [...]

While a call is open, the server sends MCP progress notifications (to clients that pass a progress token) and keep-alive frames, so connections through proxies stay up.

Choosing a wait. The defaults stay under the 60-second tool timeout many clients enforce. If your client allows longer calls, use eta_seconds plus a margin, up to 300. See the timeout table in Connect your agent.

If a call times out on the client side, the job is unaffected: it keeps its place and its credits stay reserved. Do not submit it again. Find it with list_jobs (active_only: true) and resume with wait_for_job.

There is no automatic de-duplication. Submitting the same request twice makes, and charges for, two jobs.

Waiting over REST #

POST /jobs returns 202 with the job at once. Then either poll GET /jobs/:id every few seconds, or hold one GET /events connection (Server-Sent Events) and react to job events. See the REST API reference.

Cancelling #

cancel_job (REST: POST /jobs/:id/cancel) stops a queued or running job and refunds it. A running render stops within a few seconds.

Limits #

Over a limit you get 429; wait and retry. too_many_jobs clears as soon as one of your jobs finishes.

When the shared queue is full or rendering is offline, new jobs get 503 with queue_full or renderer_offline. Nothing is charged. Wait a few minutes before submitting again (check accepting_new_jobs in get_service_status); do not retry in a tight loop. Jobs that were already accepted stay queued and run when the renderer is back, or are refunded if it stays offline.

Errors #

Over MCP, a failed tool call returns isError: true with a JSON body {"error": {"code", "message", "hint"}}; the hint says what to do next. Over REST the same codes come back as {"error": {"code", "message"}} with the HTTP status shown.

A job that fails while rendering reports a general message (The render failed on our side. Your credits were refunded.). It is safe to submit it again; if failures repeat, check get_service_status.