Docs

The API

Make animations from your own pipeline: keys, pictures, price checks, making, waiting, previews and exports, with curl or a one-file Node client.

Everything the app does goes through the same API, so your build server, pipeline or coding agent can make animations without opening the app. The address is https://greatsprites.com, and every answer is JSON unless it is a file.

1. Make a key

Sign in to the app and open API keys. Name the key after where it is used, such as "build server", copy it (it is shown once) and put it in your pipeline's secrets, never in a game or a repository. Send it with every call as Authorization: Bearer gs_…. A key spends this account's credits.

Keys are made and revoked in the app only: a key cannot make more keys or revoke others. Revoke one in the app and anything still using it is turned away at once.

2. The calls

3. What an animation is made of

• picture: the picture's id.
• element: "object" for a symbol or an item, "character" for a character beside the reels.
• brief: the motion in your own words, as you would tell an animator.
• loop: true for a loop that keeps going while it is on screen; leave it out for a one-shot that lands back on your picture.
• name: what your code calls it: 1 to 30 lowercase letters, digits, - or _, starting with a letter.
• quality: "standard" (the default), "hd" or "premium", as your plan allows.
• project: a folder's id, if you use folders.

4. With curl

KEY=gs_...   # from your secrets
curl -s -H "Authorization: Bearer $KEY" --data-binary @wild.png https://greatsprites.com/v1/pictures

curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: wild-win-1" \
  -d '{"picture":"pic_...","element":"object","name":"win","brief":"the lightning bolt flashes and the letters shine"}' \
  https://greatsprites.com/v1/animations

curl -s -H "Authorization: Bearer $KEY" "https://greatsprites.com/v1/jobs/job_...?wait=50"

curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"jobs":["job_..."]}' -o animations.zip https://greatsprites.com/v1/exports

5. With Node: one file, no dependencies

Put greatsprites.mjs in your tools (Node 18 or newer). It sends an Idempotency-Key with every make and tries a busy (429) or failed (5xx) call again, so a retry never makes or charges twice.

import fs from 'node:fs';
import { greatsprites } from './greatsprites.mjs';

const gs = greatsprites({ key: process.env.GREATSPRITES_KEY });
const pic = await gs.upload(fs.readFileSync('wild.png'));
const spec = { picture: pic.id, element: 'object', name: 'win', brief: 'the lightning bolt flashes and the letters shine' };

console.log((await gs.plan(spec)).plan);          // the price, nothing charged
const { job } = await gs.make(spec);
const done = await gs.wait(job.id);               // about half a minute
if (done.state !== 'succeeded') throw new Error(done.error);
fs.writeFileSync('animations.zip', await gs.exportZip({ jobs: [done.id] }));

6. Errors and limits

A call that does not work answers with a status and { "error": "…" } in plain words:

• 400 the request is not right, and the message says what.
• 401 no key, or a key that is not valid or was revoked.
• 402 not enough credits, or the free tests are used.
• 403 not on your plan (a quality), or a key that may not do this.
• 404 not found, or not yours.
• 409 a clash: a name already in use, or it is being made right now.
• 413 too large.
• 429 too many requests: a key may make 120 a minute.

An animation that fails our checks is made again once before you see it, and one that still fails is never charged.

← Instructions for coding agentsPlaying clips →