{ "openapi": "3.1.0", "info": { "title": "AI Sprite Maker API", "version": "1.0.0", "summary": "Generate pixel-art sprites, animated sprite sheets, turnarounds and tilesets.", "description": "Asynchronous jobs: create one with POST /jobs, poll GET /jobs/{id} until `status` is `succeeded`, `failed` or `canceled`, then download `outputs`. Every plan includes API access and uses the same credit balance as the website.\n\nCredit costs: `sprite`: 2, `edit`: 2, `animation`: 10, `directions4`: 8, `directions8`: 14, `tileset`: 6, `customMotion`: 30, `videoToSpritePerSec`: 5. An animation is 10 credits per direction.\n\nLimits: 120 requests/min per key, 20 job creations/min. free: 1 concurrent, max size 128px; starter: 2 concurrent, max size 256px; pro: 4 concurrent, max size 512px; studio: 10 concurrent, max size 512px.\n\nHuman-readable docs: https://aispritemaker.com/docs/api", "contact": { "name": "AI Sprite Maker", "email": "hello@aispritemaker.com", "url": "https://aispritemaker.com/docs/api" }, "termsOfService": "https://aispritemaker.com/legal/terms" }, "externalDocs": { "description": "API reference", "url": "https://aispritemaker.com/docs/api" }, "servers": [ { "url": "https://aispritemaker.com/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account" }, { "name": "Motions" }, { "name": "Jobs" }, { "name": "Uploads" }, { "name": "Assets" }, { "name": "Keys" } ], "paths": { "/me": { "get": { "tags": [ "Account" ], "operationId": "getMe", "summary": "Current user, plan, credit balance and limits", "responses": { "200": { "description": "Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Missing, invalid or revoked API key (`unauthorized`, `invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) reached. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error (`internal_error`). Retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/motions": { "get": { "tags": [ "Motions" ], "operationId": "listMotions", "summary": "The motion library", "security": [], "responses": { "200": { "description": "Motions", "content": { "application/json": { "schema": { "type": "object", "required": [ "motions" ], "properties": { "motions": { "type": "array", "items": { "$ref": "#/components/schemas/Motion" } } } } } } } } } }, "/jobs": { "post": { "tags": [ "Jobs" ], "operationId": "createJob", "summary": "Create a job (reserves credits)", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 64 }, "description": "Retrying with the same key returns the original job instead of creating a new one." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobInput" } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "type": "object", "required": [ "job" ], "properties": { "job": { "$ref": "#/components/schemas/Job" } } } } } }, "400": { "description": "Invalid request (`invalid_json`, `invalid_request`, `unknown_motion`, `invalid_upload`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked API key (`unauthorized`, `invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits (`insufficient_credits`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Frame size above your plan's maximum (`plan_limit`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Referenced upload not received yet (`upload_incomplete`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) reached. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error (`internal_error`). Retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Feature not enabled yet (`feature_unavailable`), e.g. custom motions or MP4 conversion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Jobs" ], "operationId": "listJobs", "summary": "List jobs, newest first", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "`next_cursor` from the previous page." } ], "responses": { "200": { "description": "Jobs", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobs", "next_cursor" ], "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Missing, invalid or revoked API key (`unauthorized`, `invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) reached. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error (`internal_error`). Retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/jobs/{id}": { "get": { "tags": [ "Jobs" ], "operationId": "getJob", "summary": "Get a job and its outputs", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id (ULID)." } ], "responses": { "200": { "description": "Job", "content": { "application/json": { "schema": { "type": "object", "required": [ "job" ], "properties": { "job": { "$ref": "#/components/schemas/Job" } } } } } }, "401": { "description": "Missing, invalid or revoked API key (`unauthorized`, `invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`job_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) reached. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error (`internal_error`). Retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/jobs/{id}/cancel": { "post": { "tags": [ "Jobs" ], "operationId": "cancelJob", "summary": "Cancel a queued or running job (releases unused credits)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id." } ], "responses": { "200": { "description": "Job", "content": { "application/json": { "schema": { "type": "object", "required": [ "job" ], "properties": { "job": { "$ref": "#/components/schemas/Job" } } } } } }, "401": { "description": "Missing, invalid or revoked API key (`unauthorized`, `invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`job_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) reached. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error (`internal_error`). Retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/uploads": { "post": { "tags": [ "Uploads" ], "operationId": "createUpload", "summary": "Get a URL to upload a reference image, GIF or video", "description": "Then PUT the file bytes to `put_url` with the same Content-Type. PNG/JPEG/WebP up to 10 MB, GIF up to 20 MB, MP4/WebM/MOV up to 50 MB.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content_type", "bytes" ], "properties": { "content_type": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp", "image/gif", "video/mp4", "video/webm", "video/quicktime" ] }, "bytes": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "201": { "description": "Upload slot", "content": { "application/json": { "schema": { "type": "object", "required": [ "upload_id", "put_url" ], "properties": { "upload_id": { "type": "string" }, "put_url": { "type": "string", "format": "uri" } } } } } }, "400": { "description": "`unsupported_type`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked API key (`unauthorized`, `invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`too_large`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) reached. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error (`internal_error`). Retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets": { "get": { "tags": [ "Assets" ], "operationId": "listAssets", "summary": "List output files, newest first", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "`next_cursor` from the previous page." }, { "name": "kind", "in": "query", "schema": { "$ref": "#/components/schemas/AssetKind" } } ], "responses": { "200": { "description": "Assets", "content": { "application/json": { "schema": { "type": "object", "required": [ "assets", "next_cursor" ], "properties": { "assets": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Missing, invalid or revoked API key (`unauthorized`, `invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) reached. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error (`internal_error`). Retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets/{id}/file/{name}": { "get": { "tags": [ "Assets" ], "operationId": "downloadAsset", "summary": "Download an output file", "description": "The `url` on each asset is already signed. Without a valid `sig`, the owner's key is required.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Asset id." }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "File name, e.g. sheet.png." }, { "name": "sig", "in": "query", "schema": { "type": "string" } }, { "name": "exp", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "File bytes", "content": { "image/png": {}, "image/gif": {}, "application/json": {}, "application/zip": {} } }, "302": { "description": "Redirect to a short-lived storage URL" }, "403": { "description": "Signature expired (`forbidden`). Fetch the job again for a fresh URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/keys": { "get": { "tags": [ "Keys" ], "operationId": "listKeys", "summary": "List API keys (prefixes only)", "responses": { "200": { "description": "Keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "api_enabled": { "type": "boolean" } } } } } }, "401": { "description": "Missing, invalid or revoked API key (`unauthorized`, `invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) reached. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error (`internal_error`). Retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Keys" ], "operationId": "createKey", "summary": "Create an API key (signed-in dashboard session only)", "description": "Requires a browser session cookie; calls made with an API key get 403 `session_required`. At most 20 active keys.", "security": [ { "sessionCookie": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60 } } } } } }, "responses": { "201": { "description": "Key created; `key.key` is shown only once", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ApiKey" }, "note": { "type": "string" } } } } } }, "400": { "description": "`too_many_keys`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked API key (`unauthorized`, `invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`session_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) reached. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error (`internal_error`). Retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/keys/{id}": { "delete": { "tags": [ "Keys" ], "operationId": "revokeKey", "summary": "Revoke an API key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Key id." } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing, invalid or revoked API key (`unauthorized`, `invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) reached. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error (`internal_error`). Retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from the dashboard, `asm_live_…`." }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "better-auth.session_token" } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "examples": [ "insufficient_credits" ] }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "JobType": { "type": "string", "enum": [ "sprite", "animation", "directions", "tileset", "edit", "custom_motion", "video_to_sprite" ] }, "AssetKind": { "type": "string", "enum": [ "sprite", "sheet", "frames_zip", "gif", "json", "preview" ] }, "JobInput": { "type": "object", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/JobType" }, "prompt": { "type": "string", "maxLength": 1000, "description": "What to draw. Required for sprite (unless a reference is given), tileset, edit, and animation/directions/custom_motion without a reference." }, "style": { "type": "string", "enum": [ "16-bit", "8-bit", "gba", "snes", "game-boy", "hd-pixel", "chibi", "isometric", "1-bit", "pico-8", "16bit", "8bit", "nes", "gameboy", "1bit", "pico8" ], "default": "16-bit", "description": "Style preset. Aliases map to the canonical ids." }, "view": { "type": "string", "enum": [ "side", "topdown", "isometric" ] }, "size": { "type": "integer", "enum": [ 32, 48, 64, 96, 128, 256, 512 ], "description": "Frame size in px (capped by plan). Default 64, 32 for tilesets." }, "palette": { "type": "integer", "minimum": 2, "maximum": 256, "description": "Maximum colours. Ignored by fixed-palette styles (game-boy, 1-bit, pico-8)." }, "count": { "type": "integer", "enum": [ 1, 4 ], "description": "Variations, for still sprites." }, "motion_id": { "type": "string", "description": "Required for `animation`. See GET /motions." }, "directions": { "type": "integer", "enum": [ 1, 4, 8 ], "description": "Animation or turnaround directions. Row order for 4: down, left, right, up; for 8: down, down-left, left, up-left, up, up-right, right, down-right." }, "character_asset_id": { "type": "string", "description": "Reuse a character from an earlier job's sprite asset." }, "reference_upload_id": { "type": "string", "description": "Upload id of a PNG/JPEG/WebP reference." }, "motion_prompt": { "type": "string", "maxLength": 600, "description": "Required for `custom_motion`." }, "video_upload_id": { "type": "string", "description": "Required for `video_to_sprite`." } } }, "Job": { "type": "object", "required": [ "id", "type", "status", "step", "progress", "credits_reserved", "credits_charged", "created_at", "outputs" ], "properties": { "id": { "type": "string" }, "type": { "$ref": "#/components/schemas/JobType" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "canceled" ] }, "step": { "type": "string" }, "progress": { "type": "number", "minimum": 0, "maximum": 1 }, "credits_reserved": { "type": "integer" }, "credits_charged": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } } }, "Asset": { "type": "object", "required": [ "id", "kind", "url", "width", "height" ], "properties": { "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/AssetKind" }, "url": { "type": "string", "format": "uri", "description": "Signed, short-lived." }, "width": { "type": "integer" }, "height": { "type": "integer" }, "meta": { "type": "object", "properties": { "frames": { "type": "integer" }, "columns": { "type": "integer" }, "rows": { "type": "integer" }, "fps": { "type": "number" }, "frame_w": { "type": "integer" }, "frame_h": { "type": "integer" }, "directions": { "type": "array", "items": { "type": "string" } } } } } }, "Motion": { "type": "object", "required": [ "id", "name", "category", "loop", "frames", "fps", "views", "preview_url" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "loop": { "type": "boolean" }, "frames": { "type": "integer" }, "fps": { "type": "number" }, "views": { "type": "array", "items": { "type": "string" } }, "preview_url": { "type": "string", "format": "uri" } } }, "Me": { "type": "object", "required": [ "user", "plan", "credits", "concurrency" ], "properties": { "user": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "image": { "type": [ "string", "null" ] } } }, "plan": { "type": "string", "enum": [ "free", "starter", "pro", "studio" ] }, "credits": { "type": "object", "properties": { "total": { "type": "integer" }, "daily": { "type": "integer" }, "subscription": { "type": "integer" }, "packs": { "type": "integer" } } }, "concurrency": { "type": "integer" }, "limits": { "type": "object", "properties": { "max_size": { "type": "integer" }, "api": { "type": "boolean" }, "hd": { "type": "boolean" } } } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "key": { "type": "string", "description": "Full key; only present in the create response." }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }