The API
One resource, a job. Create one, then poll it.
Everything a generation can be — a sprite from a description, a turnaround, an
animation — is one resource: a job. You create one, and then you poll it.
Polling is a first-class mode here, not a fallback: the Godot editor cannot
receive a webhook, so job reads are served from our own database and are cheap
by construction. The API tells you how often to ask with the X-Poll-After
header, so nobody has to guess an interval.
https://api.gensprite.aiThe shape of every generation
- Quote it —
POST /v1/jobs/quotetakes the same body as job creation and answers what it would charge. Nothing is created and no credits move. - Create it —
POST /v1/jobscharges credits and starts the generation in one transaction: there is no state in which credits are gone and no job exists. - Poll it —
GET /v1/jobs/{id}untilstatusis terminal, waitingX-Poll-Afterseconds between asks. - Take the files — a finished job carries its output as a list of files,
each with a
role, aurland acontent_type. Transparent PNG, one file per side.
A job's status is one of queued, running, completed, failed or
cancelled — the last three are terminal. A job that fails refunds itself,
and you can watch the refund land in the ledger.
What a job can be
kind | What comes back |
|---|---|
sprite | One character, from a text description |
rotation_1 | One side of a drawing |
rotation_4 | Four sides — front, left, back, right |
rotation_8 | Eight sides, the diagonals included |
animation | A cycle, one PNG per frame per direction |
What each kind costs comes from GET /v1/models and is
never compiled into a client: prices shown anywhere must be read from there.
A document without a single oneOf
The OpenAPI document this reference is generated from deliberately contains no
oneOf, anyOf or allOf — the generated GDScript client cannot compile
them. Fields that would otherwise be nullable are absent instead, and a job's
input is an open object validated server-side against its kind. If you are
generating your own client, this document is unusually easy to feed to a
generator, because it was written to survive the pickiest one we ship.