Follow a Generation Task from Submit to Finished Output

Long-running model execution follows:

submit -> task_id -> queued/running -> succeeded/failed

A successful submit response means the request was accepted. It does not mean generation has finished.

Use MCP poyo_submit_job and poyo_check_job, or the REST submit and status endpoints.

Read normalized statuses#

The REST generation API continues to expose its existing raw status values. MCP normalizes them without changing the stored task.

Resume safely after an interruption#

Keep the task_id in durable application state or working notes. If a process or agent session is interrupted, query the existing task rather than submitting and paying for a replacement.

Poll without overloading the API#

When a response includes poll_after_seconds, wait at least that long before the next status check. Otherwise, use bounded exponential backoff with jitter. Honor Retry-After after a 429 response.

Stop only on succeeded, failed, or your own timeout; a local timeout does not cancel the remote task.

2s -> 4s -> 8s -> 15s -> 30s

For production applications, prefer a signed webhook when the native generation API supports it. A webhook reduces status traffic, but the receiver should still fetch or validate the task before trusting output.

Handle the result#

On success:

1. Record the model ID, task ID, final status, and charged credits.
2. Validate the expected output fields.
3. Download generated files to storage you control before temporary URLs expire.
4. Treat repeated webhook deliveries and status reads as normal.

On failure, keep the task ID and normalized error. Retry only when the error is transient, and reuse the same idempotency key only with the identical request payload.

poyo_run_model waits for at most 30 seconds. If the work is still running, it returns the task ID and poll_after_seconds instead of failing the generation.

Back to Documentation Index · See also: Error Codes