The AutoSprite REST API lets you programmatically create characters, generate animations, and export spritesheets. Build custom pipelines, integrate with your game engine's asset workflow, or automate batch generation. The API is available on **Pro** and **Studio** plans. Get your API key from the [API Key page](/apikey). ## Base URL ``` https://autosprite.com/api/v1 ``` All endpoints are relative to this base URL. ## Authentication Every request requires an API key. Your key starts with `vspk_` and can be passed in two ways: ```bash # Option 1: x-api-key header (recommended) curl https://autosprite.com/api/v1/account \ -H "x-api-key: vspk_your_key_here" # Option 2: Bearer token curl https://autosprite.com/api/v1/account \ -H "Authorization: Bearer vspk_your_key_here" ``` Keep your API key secret. Do not commit it to version control or expose it in client-side code. ## Error Handling All errors return a consistent JSON structure: ```json { "error": { "code": "ERROR_CODE", "message": "Human-readable description" } } ``` ### Error Codes | Code | Status | Description | |------|--------|-------------| | `UNAUTHORIZED` | 401 | Missing or invalid API key | | `PLAN_REQUIRED` | 403 | Paid subscription required — generation endpoints are gated to paid plans | | `RATE_LIMIT_EXCEEDED` | 429 | Too many requests — check `Retry-After` header | | `INSUFFICIENT_CREDITS` | 402 | Not enough credits for this operation | | `DUPLICATE_CHARACTER` | 409 | A character with this name already exists | | `NOT_FOUND` | 404 | Resource not found or not owned by you | | `MISSING_ANIMATIONS` | 400 | No animations provided | | `TOO_MANY_ANIMATIONS` | 400 | Maximum 10 animations per request | | `MISSING_PROMPT` | 400 | Custom animations require a prompt | | `INTERNAL_ERROR` | 500 | Something went wrong on our end | ## Access & Plan Requirements All endpoints require a valid API key. **Generation and write endpoints** (POST/DELETE) additionally require an active paid subscription (Starter, Pro, or Studio). Read-only endpoints are available to all authenticated users. | Access Level | Endpoints | |-------------|-----------| | **Any authenticated user** | List characters, get character, list/get spritesheets, list/get jobs, list poses, check account balance | | **Paid plan required** | Create/delete characters, generate animations, generate poses, pad characters, regenerate spritesheets | Free-tier users calling a paid endpoint will receive a `403 PLAN_REQUIRED` error. ## Rate Limits API requests are rate limited per user. If you hit the limit, you'll receive a `429` response with a `Retry-After` header indicating when you can retry. ## Credits Most generation operations cost credits. Credits are reserved before processing starts and automatically refunded if an operation fails. | Operation | Credits | |-----------|---------| | Create character (from prompt) | 1 | | Create character (upload image) | Free | | Generate animation | 5 per animation | | Generate animation with sound | 10 per animation | | Generate pose | 5 | | Pad character | 1 (free if size = 100) | | Regenerate spritesheet | Free | Check your balance anytime: ```bash curl https://autosprite.com/api/v1/account \ -H "x-api-key: vspk_your_key_here" ``` ```json { "credits": 150 } ``` ## Pagination List endpoints use **cursor-based pagination**: ```bash # First page GET /api/v1/characters?limit=20 # Next page (use nextCursor from previous response) GET /api/v1/characters?limit=20&cursor=abc123 ``` - `limit` — Items per page (1–50, default 20) - `cursor` — Cursor from the previous response's `nextCursor` ## What's Next? Follow the [Quick Start](/docs/api-quickstart) for a full end-to-end walkthrough, or jump into the endpoint reference:

API Overview

API Overview