Skip to main content

​
What this lets you do

Submit an image request, preserve its identity, follow events, and recover its output without submitting replacement work. The Python and JavaScript examples use standard libraries and make the same HTTP requests.

​
What you need

Capabilities, balance, and existing execution reads do not start paid generation. Submitting an image or sprite request can spend credits. The local journal contains request data and execution identifiers; keep it private and out of source control.

​
Steps

​
1. Save a request

Create request.json for a first image:
For a reference edit, upload the image once and save the returned input asset ID:
For a sprite, first confirm sprite_sheet and sprite_pricing in capabilities. Set max_credits to a quote you approve:

​
2. Submit and follow

The example creates job.json with a random idempotency key and the serialized request before sending the request. It asks for a JSON acknowledgement, saves the execution ID, then reads the event stream. It persists the cursor after parsing each event and checks canonical state after every connection closes.

​
3. Recover after interruption

If an execution ID is present, recovery makes only reads. If the acknowledgement was lost, it replays the stored request bytes with the same key. The example never generates a replacement key during recovery. Do not run two processes with the same journal.

​
4. Download the existing result

Choose .zip for a sprite. Downloading does not regenerate the output. The examples authenticate only to the API origin, strip credentials from redirected storage requests, and refuse to overwrite an existing destination.

​
Confirm it worked

The final JSON reports completed, the journal retains the execution ID, and the download writes the existing PNG or ZIP. A local waiting deadline or network error leaves the journal intact for a later resume.

​
Common errors

  • needs_input: read question, answer through the conversation API, and track the answer’s new execution ID.
  • failed or cancelled: inspect the public error; do not automatically submit a replacement.
  • 429: back off according to limits. The examples stop on HTTP errors so your caller can apply its own bounded retry policy.
  • An existing journal with a different request is refused. Use a new journal only for intentionally new work.

​
Troubleshooting

A stream closing is not proof of completion. Only canonical state tells you whether the job is still running. These examples wait for at most 20 connections per invocation, with a pause between reads; resume later if the execution remains active. Local mock tests verify recovery, not live generation quality.

​
Next steps