Quickstart

This walks the same path the front page shows: a character enters as a sentence and leaves as four transparent PNGs. You will need an API key — made in the workshop under Settings → API keys, shown once, and carried as a bearer token:

export GENSPRITE_KEY="gsk_..."

1. See what it costs

curl https://api.gensprite.ai/v1/models \
  -H "authorization: Bearer $GENSPRITE_KEY"

Every kind of generation is listed with its price in credits. If you only need the price of one specific job, quote it — same body as creation, nothing charged, nothing created:

curl -X POST https://api.gensprite.ai/v1/jobs/quote \
  -H "authorization: Bearer $GENSPRITE_KEY" \
  -H "content-type: application/json" \
  -d '{"kind":"sprite","input":{"prompt":"a knight in dented plate armour holding a torch"}}'

2. Make the character

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":"sprite","input":{"prompt":"a knight in dented plate armour holding a torch, standing, full body, front view"}}'

The Idempotency-Key header is required, not optional — a retried request never buys a second generation. The response is a job with an id and a status of queued.

3. Poll until it lands

curl https://api.gensprite.ai/v1/jobs/$JOB_ID \
  -H "authorization: Bearer $GENSPRITE_KEY"

Wait the number of seconds in the X-Poll-After response header between asks. This read never touches a provider — it is served from our own database, which is what makes polling the primary mode rather than a compromise. When status reaches completed, the job carries its files: each has a role, a url and a content_type.

4. Turn the character

The sprite's output URL goes straight back in as the rotation's input — a generation's output is accepted as the next job's input without being downloaded and re-uploaded:

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\":\"rotation_4\",\"input\":{\"image_url\":\"$SPRITE_URL\"}}"

Poll the same way. Four sides come back — front, left, back, right — each its own transparent PNG, and exactly the four an animation job takes as its input.

Starting from your own drawing

If the character already exists on paper, skip step 2: reserve an upload with POST /v1/uploads, PUT the image bytes to the returned upload_url, and pass the accompanying file_url as the rotation's image_url. Two steps rather than a multipart POST, because the generated GDScript client has to be able to do this too.