# GameTorch v2 API GameTorch generates game-ready sprites, sounds and animations. This file is a concise index for agents; the full reference is in `llms-full.txt`. Base URL: `/api` (development: `http://localhost:8300/api`) Auth: `Authorization: Bearer ` — a Clerk session token (browser) or a `gt2_...` API key (server-to-server). Errors: JSON `{"error": ""}` with an HTTP 4xx/5xx status. Credits: 100 credits = $1. Each job reserves credits up front and settles to the actual cost, releasing the unused hold. ## For agents: use an API key, not MCP There is no MCP server, on purpose. An MCP shim adds a slow, stateful layer of indirection between your agent and a plain HTTP API — more moving parts, more latency, no extra capability. Skip it. - Create an API key: `POST /keys` (see below), or from the dashboard. - Set a per-key spend limit (daily/weekly/monthly) if you want a hard cap. - Point your agent at this file (`/llms.txt`), the full reference (`/llms-full.txt`), or the OpenAPI spec (`/api/openapi.json`) and call the API directly with `Authorization: Bearer `. That's it. A key, an optional limit, and the docs. No framework required. ## Which tool to reach for - **Human + agent working together** (a person watches, inspects output and steers each step): use the official **`gametorch` CLI**. Every API operation is a command with `--json` output, so a human can read and adjust each step. - **Programmatic, repeated, hands-off automation** (no human in the loop — a pipeline, CI job or long-running service): use an **SDK** for Python, TypeScript, Go or Rust. Typed models, retries, rate limiting and pagination are built in. ## Key scopes A key is created with one of three scopes (fixed for its lifetime): - `admin` (default): full access to the account/org, like an admin session. - `project_write`: bound to one project; read and write its sprites, sounds, animations, labels, names and metadata. No account/admin access, no other projects. - `project_read`: bound to one project; read-only, same boundaries. Project-scoped keys get `403` on account/admin routes (usage, billing, org members, key management, project create/rename/delete) and `404` when they name another project or a resource id that belongs to one. `GET /projects` returns only the bound project; the model catalogs stay readable. Pass `key_scope` and `project_id` to `POST /keys`. ## Rate limits (per account) Every limit is enforced per account and exceeding one returns HTTP `429`. - **1 request/second per route:** creation of generations, sounds and animations, and animation exports. - **Reads — one token bucket per account** (10,000-request burst, refilled at 1,000 requests/second): every GET read, including single-item and list reads, usage and usage histogram, and asset/audio/animation content. - **Writes — one token bucket shared across writes per account** (100-request burst, refilled at 5 requests/second): project/label/API-key/art-style/ saved-animation creation, archive/unarchive, and metadata. - **Concurrency caps:** at most 25 outstanding holds and 5 concurrent animation-frame generations per account. ## Model warm-up A run can briefly wait (usually a few seconds) while one of GameTorch's own models starts up after a period of inactivity; once warm, that model responds in about 0.2 seconds per run. The generated object reports a `warming` flag while this is happening. ## Official CLI and SDKs The **`gametorch` CLI** is the recommended tool when a human is in the loop: every public API operation is a command, with `--json` output and `--output` downloads, so you can inspect and steer each step. Install it from crates.io: ``` cargo install gametorch-cli ``` You can also install from GitHub source: `cargo install --git https://github.com/gametorch/gametorch-rs gametorch-cli` (or clone the repo and `cargo install --path cli`). For programmatic, repeated, hands-off automation, use an SDK. All are first-party, MIT-licensed, cover the whole public API with typed models, polite rate limiting and retries, cursor pagination, exact decimal money and project key-scope constructors, and read `GAMETORCH_API_KEY` / `GAMETORCH_BASE_URL` from the environment: - Python 3.11+ — `pip install gametorch` — https://github.com/gametorch/pygametorch - TypeScript / JavaScript (Node 20+) — `npm install gametorch` — https://github.com/gametorch/gametorch-ts - Go 1.27+ — `go get github.com/gametorch/gogametorch` — https://github.com/gametorch/gogametorch - Rust — `gametorch = "0.1"` (async `reqwest`/`tokio`) — https://github.com/gametorch/gametorch-rs Developer hub and examples: https://github.com/gametorch ## Documentation - Full agent reference: /llms-full.txt - OpenAPI 3 spec: /api/openapi.json - Interactive API reference: /api/docs ## Support Questions, bugs or billing issues: support@gametorch.app. ## Endpoint index - Catalogs: GET /sprite-models, GET /sound-models, GET /animation-models - Projects: GET /projects, POST /projects, PATCH /projects/{slug}, DELETE /projects/{slug} - Sprites: POST /projects/{project_id}/generations, GET /projects/{project_id}/generations, GET /generations/{id}, GET /projects/{project_id}/sprite-assets, GET /assets/{id}, GET /assets/{id}/content, PATCH /assets/{id}, PUT /assets/{id}/metadata, POST /assets/{id}/archive, POST /assets/{id}/unarchive, DELETE /assets/{id} - Sounds: POST /projects/{project_id}/sound-generations, GET /projects/{project_id}/sound-generations, GET /sound-generations/{id}, GET /sound-assets/{id}/content, DELETE /sound-assets/{id} - Animations: POST /projects/{project_id}/animation-runs, POST /projects/{project_id}/animation-runs/estimate, GET /projects/{project_id}/animation-runs, GET /animation-runs/{id}, GET /animation-runs/{id}/content, POST /animation-runs/{id}/archive, DELETE /animation-runs/{id} - Animation exports: POST /animation-runs/{id}/export-plan and POST /animation-runs/{id}/export/{texturepacker,texturepacker.zip,aseprite,godot,godot.zip,grid,gamemaker,sequence.zip} - Animation frames: POST /projects/{project_id}/animation-runs/{id}/frames, GET /animation-run-frames/{id}/content, GET /animation-runs/{id}/frames/{number}/content - Saved animations: GET/POST /projects/{project_id}/saved-animations, GET/PATCH/DELETE /saved-animations/{id}, PUT /saved-animations/{id}/metadata, POST /saved-animations/{id}/archive, POST /saved-animations/{id}/unarchive - Labels: GET /projects/{project_id}/labels, POST /projects/{project_id}/labels, PATCH /labels/{label_id}, DELETE /labels/{label_id}, GET /labels/{label_id}/items, POST /labels/{label_id}/thumbnail, POST/DELETE /assets/{asset_id}/labels, POST/DELETE /sound-assets/{asset_id}/labels, POST/DELETE /saved-animations/{id}/labels, DELETE /assets/{asset_id}/label-suggestions, DELETE /sound-assets/{asset_id}/label-suggestions (a project may have at most 10,000 labels) - Art styles: GET /projects/{project_id}/art-styles, POST /projects/{project_id}/art-styles, DELETE /art-styles/{art_style_id}, POST /projects/{project_id}/art-styles/generate - Usage: GET /usage, GET /usage/histogram - API keys: GET /keys, POST /keys, PATCH /keys/{id}, DELETE /keys/{id} ## Notes - Every generation and result records who created it: `user_id`, `source` (`UI`/`API key`), and `api_key_id`/`key_name` for API-key runs. - Sprites are delivered as transparent PNGs regardless of the generating model. - Animation models are addressed by the public names `ash`, `birch` and `cedar`.