Gensprite

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) ↘ cancelled

Creating

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.

modelNameSeed
sprite-v3GPT Image 2.5 (default)none: a seed sent is dropped
sprite-v1Qwen Imageseed: integer, echoed if omitted
sprite-v2Nano Banana 2seed: 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.

modelNameExtra parameters
gpt-image-2.5GPT Image 2.5background: auto (default), opaque, transparent
nano-banana-2.1Nano Banana 2.1background: auto (default), transparent; seed: integer, echoed if omitted
seedream-5.0-proSeedream 5.0 Probackground: 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:9 or 9:16.
  • image_urls — optional, up to four reference images from POST /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.

kindmodelNamePrice
musicmusic-v1Stable Audio 3 (default)4 credits a track
musicmusic-v2ElevenLabs Music60 credits per started minute
sfxsfx-v1ElevenLabs Sound Effects1–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: true cuts the track where it flows back into its own start and crossfades the seam, so the whole file is the loop. Defaults to false.
  • instrumental: music-v2 only, true by default. false lets it sing; put lyrics in the prompt or it writes its own. music-v1 makes instrumentals only and refuses false.
  • seed: music-v1 only, 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: true asks for a sound that wraps without a seam. Defaults to false.
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.

kindmodelNamePrice
speechspeech-v1ElevenLabs v4 (default)8 credits per 1000 characters
speechspeech-v2ElevenLabs v4 Turbo4 credits per 1000 characters
speechspeech-v3ElevenLabs v310 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 as en or ja. Omit it and the language is read from the text.
  • seed: speech-v1 and speech-v2 only, an integer. speech-v3 refuses 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"}}'

On this page