API & MCP quickstart

Create a character

curl https://spritefuse.com/api/v1/jobs   -H 'Authorization: Bearer YOUR_API_KEY'   -H 'Content-Type: application/json'   -H 'Idempotency-Key: character-001'   -d '{"operation":"character.generate","prompt":"A tiny forest knight with a blue scarf","max_credits":10}'

The response returns job_id immediately. Read GET /api/v1/jobs/JOB_ID every five seconds until succeeded, failed or canceled. Planning, provider delivery and Credit settlement advance in the background. A result includes asset_job_id and project_id.

Animate, revise and export

Submit animation.generate with project_id, prompt, max_credits and an optional frame_count from 1 to 25. Submit sprite.revise with project_id and the source_job_id from a completed public task or asset_job_id. Use a new idempotency key for a new creative request.

List projects at GET /api/v1/projects and sprites at GET /api/v1/assets?project_id=PROJECT_ID. PATCH /api/v1/assets/ASSET_JOB_ID/timing with revision and frame_duration_ms changes playback without generating a new image. Durations are 16–10000 ms. POST /api/v1/assets/ASSET_JOB_ID/export returns a ZIP link valid for ten minutes. Timing and export use no generation Credits.

Character assets provide image/frame URLs. ZIP export requires an accepted animation version. Processing or pending Credit settlement returns export_not_ready.

Private reference images

POST /api/v1/uploads with content_type and size to get a reference_image_id and upload_url. PUT the actual image bytes to that URL using the declared Content-Type. Supply reference_image_id when creating a task after the upload returns ready. PNG, JPEG and WebP are supported up to 3 MB, 4096 pixels per side and 16 million pixels. Animated files and arbitrary image URL fetches are rejected.

Connect an AI agent

Remote MCP URL: https://spritefuse.com/api/mcp. Use Streamable HTTP and OAuth in a compatible coding client. Sign in with Google and review the requested permissions. Each client connects to your SpriteFuse account and uses its existing Credits.

• Claude: open Customize → Connectors → Add custom connector, enter the remote MCP URL and connect with OAuth. Team and Enterprise setup may require your workspace owner. See the Claude setup guide.
• ChatGPT: open Plugins → plus → Add custom MCP server, enter the remote MCP URL, select OAuth and create the plugin. Review the discovered tools and enable it in your conversation. Account and workspace policies apply. See the ChatGPT setup guide.

Ask the agent to read capabilities and your balance, then create a sprite with an explicit maximum Credit amount. The create tool returns a task; the agent can read it and export the accepted sprite. Disconnect a client in Developers to revoke its access and refresh tokens.

Example request: “Create one tiny forest knight character in SpriteFuse. Spend at most 10 Credits, use idempotency key knight-001 and report the completed image link.”

Permissions and recovery

• account:read reads balance and limits; assets:read reads tasks, projects and sprites.
• jobs:write creates tasks, uploads references and edits timing; jobs:cancel cancels tasks; exports:write issues export links.
• Each account allows one unfinished developer generation and 30 accepted tasks per UTC day, including failed tasks. The default daily limit is 100 Credits, with separate key limits. Reservations count immediately, including across UTC midnight.
• A conflicting Idempotency-Key returns 409. An identical replay returns the original task. Never create a new paid request to recover an uncertain provider submission.
• If the free delivery queue reaches its limit, tasks stay queued in durable storage and resume when delivery returns. Queued tasks can be canceled. Retrying or polling does not create another provider call.
• Errors include code, message and request_id. A 429 includes Retry-After. Keep the same key when a submit response is interrupted.

Full OpenAPI specification