Jobs and polling
The lifecycle of a generation, and how to wait for one politely.
A job moves through five states, three of them terminal:
queued → running → completed
↘ failed
(cancel) ↘ cancelledCreating
POST /v1/jobs charges credits and starts the generation.
The charge and the job row are written in one transaction — there is no
state in which credits are gone and no job exists.
Idempotency-Key is required on every create. Retry the request with the
same key and you get the same job back rather than a second charge, even on
an unreliable connection. Quote
before you commit with POST /v1/jobs/quote: same body,
answers the price, moves nothing.
Polling
GET /v1/jobs/{id} reads our own database and never calls
a provider, which is what makes polling cheap enough to be the primary mode
rather than a fallback. The response carries an X-Poll-After header —
wait that many seconds between asks. Poll until status is terminal.
In a browser there is a push alternative:
GET /v1/jobs/{id}/events streams the same job object
over server-sent events, one per change. It exists for the web frontend;
other API clients should poll instead.
Failing and refunding
A generation that fails refunds itself. Every movement of credits — charges, purchases, refunds and grants alike — writes exactly one row to the ledger, so the account balance is always the sum of that list and never an independently maintained number that could drift.
Cancelling
POST /v1/jobs/{id}/cancel is accepted while a job is
queued or running. A job that already reached a terminal state answers
job_not_cancellable.
The files
A completed job carries its output as files, each with a role (which side
or frame it is), a url and a content_type. Files expire eventually —
files_expired on the job says when they have — but the job itself, its
input and its record in the ledger do not. The drawing you put in is kept
with the generation, so a second run at different settings never means
finding the file again.
Sprites
The sprite kind draws one character or object on a transparent background
and returns it as one file with the role sprite. Pick the model with
model; omitting it uses the kind's default, GPT Image 2.5.
model | Name | Seed |
|---|---|---|
sprite-v3 | GPT Image 2.5 (default) | none: a seed sent is dropped |
sprite-v1 | Qwen Image | seed: integer, echoed if omitted |
sprite-v2 | Nano Banana 2 | seed: integer, echoed if omitted |
GPT Image draws the alpha itself; the other two draw on a plain background
that is cut out afterwards. All three take prompt (up to 2000
characters), perspective (side, the default, three_quarter or
top_down) and style (hand-painted, anime, cartoon, realistic,
vector or outline). A seed is dropped rather than refused so that a
client sending one keeps working whichever model it asks for. Prices are in
GET /v1/models.
Raw images
The image kind is the raw mode: the prompt reaches the model exactly as
written — no sprite framing, no white background, no cut-out — and the
picture comes back as the model drew it, as one file with the role image.
Pick the model with model; omitting it uses the kind's default.
model | Name | Extra parameters |
|---|---|---|
gpt-image-2.5 | GPT Image 2.5 | background: auto (default), opaque, transparent |
nano-banana-2.1 | Nano Banana 2.1 | background: auto (default), transparent; seed: integer, echoed if omitted |
seedream-5.0-pro | Seedream 5.0 Pro | background: auto (default), transparent |
background: "transparent" returns a PNG with alpha from any of the three.
GPT Image draws the alpha itself at no extra cost. Nano Banana and Seedream
can't, so their image is cut out after drawing, which adds about 2 credits.
For those two, ask for a solid flat purple background in the prompt, not a
transparent one: a single colour absent from the subject cuts out cleanest.
More in Raw images.
Every model takes the same three common fields:
prompt— up to 4000 characters.aspect_ratio—1:1(default),3:2,2:3,4:3,3:4,16:9or9:16.image_urls— optional, up to four reference images fromPOST /v1/uploads. With references the model edits or draws from them instead of starting blank.
A parameter the chosen model does not have is refused rather than ignored,
so a seed sent to GPT Image is an error, not a promise quietly broken. The
price depends on the ratio, on how many references you send and on the
cut-out, so
GET /v1/models lists the most a model can cost —
quote the exact job first.
curl -X POST https://api.gensprite.ai/v1/jobs \
-H "authorization: Bearer $GENSPRITE_KEY" \
-H "content-type: application/json" \
-H "idempotency-key: $(uuidgen)" \
-d '{"kind":"image","model":"gpt-image-2.5","input":{"prompt":"title card that reads GIGA, transparent background","aspect_ratio":"16:9","background":"transparent"}}'Music and sound effects
The music and sfx kinds return the same audio three times, with the role
naming the format: wav (16-bit PCM, 44.1 kHz), ogg (Vorbis) and mp3
(192 kbps). Loop the ogg or the wav: MP3 adds encoder padding at both
ends, which is heard as a gap at every wrap.
kind | model | Name | Price |
|---|---|---|---|
music | music-v1 | Stable Audio 3 (default) | 4 credits a track |
music | music-v2 | ElevenLabs Music | 60 credits per started minute |
sfx | sfx-v1 | ElevenLabs Sound Effects | 1–4 credits, by length; 4 when it's auto |
Music takes:
prompt: up to 2000 characters.duration: whole seconds, 5 to 300. Defaults to 60.loop:truecuts the track where it flows back into its own start and crossfades the seam, so the whole file is the loop. Defaults tofalse.instrumental:music-v2only,trueby default.falselets it sing; put lyrics in the prompt or it writes its own.music-v1makes instrumentals only and refusesfalse.seed:music-v1only, an integer, echoed if omitted.
Sound effects take:
prompt: up to 1000 characters. Describe the sound, not the scene.duration: 0.5 to 22 seconds. Omit it and the model picks a length that suits the sound.loop:trueasks for a sound that wraps without a seam. Defaults tofalse.
curl -X POST https://api.gensprite.ai/v1/jobs \
-H "authorization: Bearer $GENSPRITE_KEY" \
-H "content-type: application/json" \
-H "idempotency-key: $(uuidgen)" \
-d '{"kind":"music","input":{"prompt":"calm 8-bit village theme, chiptune, warm square leads, 90 BPM","duration":60,"loop":true}}'Speech
The speech kind says a line out loud. It returns the same three audio files
as music, plus a file with the role words (application/json): each word's
start and end in seconds, as {"words": [{"word", "start", "end"}]}. The file
is left out on the rare take the model returns without timings.
kind | model | Name | Price |
|---|---|---|---|
speech | speech-v1 | ElevenLabs v4 (default) | 8 credits per 1000 characters |
speech | speech-v2 | ElevenLabs v4 Turbo | 4 credits per 1000 characters |
speech | speech-v3 | ElevenLabs v3 | 10 credits per 1000 characters |
Every job costs at least 1 credit. Speech takes:
prompt: exactly what is said, up to 5000 characters. Audio tags in square brackets steer the delivery without being spoken:[whispers],[shouting],[laughs],[sighs],[sarcastic].voice: one of Adam, Alice, Bill, Brian, Callum, Charlie, Chris, Daniel, Eric, George, Jessica, Laura, Liam, Lily, Matilda, River, Roger, Sarah, Will. Defaults to George. Voices says what each one suits.stability: 0 to 1. Lower is more expressive and varies more between takes; higher is steadier.language: a two-letter ISO 639-1 code such asenorja. Omit it and the language is read from the text.seed:speech-v1andspeech-v2only, an integer.speech-v3refuses it.
curl -X POST https://api.gensprite.ai/v1/jobs \
-H "authorization: Bearer $GENSPRITE_KEY" \
-H "content-type: application/json" \
-H "idempotency-key: $(uuidgen)" \
-d '{"kind":"speech","input":{"prompt":"[whispers] Keep your voice down. The guards change at midnight.","voice":"Lily"}}'