Animate Endpoint

Generate an animated sprite sheet.

POST /api/v1/pixel-art/animate

Authentication and usage

Send X-API-Key: sk_live_example. The legacy apiKey query parameter is also accepted, but a header avoids putting the key in a URL. With app tokens (the default), the price depends on quality: low 1.2, medium 1.8, high 2 tokens. With credentialSource: "user_provider", the connected OpenAI account is billed instead and no app tokens are consumed. One provider attempt is made; app tokens are refunded on failure when the refund succeeds.

Rate limit: the API key's configured requests-per-minute limit, 60 by default. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A 429 response includes Retry-After.

Request body

Provide a preset and optionally a text prompt, imageUrl, or base64 image. An image is used as a reference when supplied; image takes precedence over imageUrl.

{
  "prompt": "blue slime monster",
  "preset": "enemy-slime-bounce",
  "quality": "medium"
}

Fields

prompt (string), text description for text-to-animation or description of the reference subject.
imageUrl (string), absolute http or https URL for an existing sprite reference. The server downloads it, so the host must resolve only to public addresses and the port must be 80 or 443. URLs with credentials are refused, redirects are not followed (send the final address), the response must be an image/* file, and it can be at most 10 MB. A download that fails returns 500 with tokenRefunded as for any generation failure. To avoid the download, send the bytes in image instead.
image (string), base64 image data URL for an existing sprite reference.
preset (string, required), preset ID from the preset library. presetId is an alias.
direction (string, optional), movement direction such as down, up-right, or N. Directional presets default to a right-facing side view; non-directional presets ignore it.
customPrompt (string, optional), describes the motion and replaces the preset's frame-by-frame poses. The preset still controls frame count, grid layout, and FPS.
quality (string, optional), low, medium (default) or high. Low is rough and not recommended; medium is good; high is best.
postProcess (boolean, optional), set to false to return only the raw version.
crisp (object, optional), crisp settings: height ("sprite", the default when an input image is sent: the subject is rebuilt at the input image's subject height in pixels; "auto" for the model's native pixel size; or 16, 24, 32, 48, 64, 96, 128), colours ("sprite", the default when an input image is sent: every pixel snaps to the input image's colours, reduced to 64 when it has more; or 4, 8, 16, 24, 32, 64; without an input image the defaults are auto and 24), removeStray (boolean, default true). Unknown values use the default.
credentialSource (optional), application (default) or user_provider. Connect and test an OpenAI account before selecting user_provider.
model (optional), an available GPT Image 2.6 model on the connected account. If omitted, the service selects an available 2.6 model.

Response

{
  "ok": true,
  "animationId": 123,
  "spriteSheetUrl": "https://cdn.example/animation.png",
  "frames": [
    { "index": 0, "url": "https://cdn.example/frame-000.png" }
  ],
  "metadata": {
    "frameCount": 6,
    "frameWidth": 32,
    "frameHeight": 32,
    "columns": 3,
    "rows": 2,
    "fps": 10
  },
  "raw": { "spriteSheetUrl": "https://cdn.example/raw.png", "frames": [], "metadata": {} },
  "crisp": { "spriteSheetUrl": "https://cdn.example/animation.png", "frames": [], "metadata": {} },
  "usage": {
    "tokensUsed": 1.8,
    "tokensRemaining": 48.2,
    "credentialSource": "application",
    "model": "gpt-image-2.6-flare",
    "quality": "medium"
  }
}

spriteSheetUrl, frames and metadata describe the crisp version, or the raw version when postProcess is false. raw and crisp hold both versions; each has spriteSheetUrl, ordered frames, and metadata, and crisp is null when postProcess is false. The raw version is the model's drawing with the background removed and one shared crop. The crisp version rebuilds it as native pixel art, one colour per pixel; crisp.metadata.crisp reports the settings, detected blockSize (source pixels per art pixel), and paletteSize. Both versions come from one model call. metadata also includes presetId, presetName, category, direction, and generation (model, quality, OpenAI token usage, costUsd). A successful response is returned only after all frames are saved.

Example request:

curl -X POST "https://crateyard.com/api/v1/pixel-art/animate" \
  -H "X-API-Key: sk_live_example" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"blue slime monster","preset":"enemy-slime-bounce"}'

Error response

{
  "error": "Insufficient tokens",
  "balance": 0
}