status_url, reports progress and the result.
The request object
The submit response, a status read, and a cancel response all return this shape.
Use the URLs the API returns rather than building them yourself.
Statuses
Output that Mage’s content policy forbids reports as
failed with the code content_blocked and no URL, so you never have to inspect moderation flags to learn that a request produced nothing.
Polling
Pollstatus_url until the status is final. Start with a short interval, back off, and add a little jitter so a batch of requests does not poll in step.
- Images usually complete within seconds; video within minutes. Start at 2 seconds for an image and 5 seconds for video, multiply by 1.5 after each read, and cap the interval at 15 seconds.
- Set a deadline of your own for each request, generous for video, and treat a request that passes it as something to investigate rather than to resubmit.
- A status read is safe to retry on a network error or a
5xx. A401or404will not change on retry; stop and check the key and the id.
Retrying a submit safely
A submit charges Gems, so a client that times out while waiting for the response must not simply send it again. Send anIdempotency-Key header instead: a string of 1 to 255 characters of your choosing, scoped to your API key. A retried submit with the same key returns the original request with 200 and charges nothing.
The key identifies the first submission made with it, whatever body a later retry carries; the body is not compared. Derive the key from the request it protects, such as a hash of the payload or a job id that maps to exactly one payload, and never reuse it for a different request.
A key is consumed by the first submission Mage records under it, including one it then refuses: an error envelope that carries request_id means the same key will replay that failed request rather than submit a new one. Keep the key for transport retries, when you got no response at all, and use a new key for a new attempt after a refusal.
Cancelling
POST to cancel_url to stop a live request. The run is marked cancelled and the generation backend is asked to stop; the response is the request’s state afterwards. Gems are not returned for a cancelled request, as in the app.
Cancelling a request that already completed or failed is refused with 409 request_finished. Cancelling a request that is already cancelled does nothing and returns its state.
The result
Download what you want to keep. A completed request stays
completed after its media expires; only the URL stops working.
