API keys, scopes and authentication
Send your key as a Bearer token on every request. Keys belong to the account (or team) that created them, and every generation bills that account's credits.
Sending the key
Authorization: Bearer sk-your-key
# or
x-api-key: sk-your-keySend keys in a header only — never in a query string or URL, which end up in logs.
Key format
Keys match ^sk-[A-Za-z0-9]{38}$. The last six characters are a checksum, so a mistyped or truncated key is refused before it is looked up. Add the pattern to your secret scanner.
Scopes
| Scope | Allows |
|---|---|
read | account, capabilities, workflow and batch status (GET /v1/me, /v1/capabilities, /v1/workflows/:id, /v1/batches, /v1/batches/:id; MCP list_models, estimate_cost, get_balance, get_job, list_job_files, search_library, list_batches, get_batch) |
generate | start or retry generations and batches that bill credits, and convert Library models (POST /v1/generate, /v1/batches, /v1/batches/:id/retry, /v1/tools/convert; MCP generate_3d, generate, start_batch, retry_batch, convert_model) |
A call outside the key's scopes answers 403 with data.code = "insufficient_scope".
Expiry and rotation
A key lives for 30 days, 90 days (default), 365 days or never expires, chosen at creation. An expired key answers 401 with data.code = "key_expired". Rotating mints a replacement while the old key keeps working until you revoke it, so you can deploy the new value first.
IP allow-list
A key can be pinned to up to 20 IPv4/IPv6 addresses or CIDR blocks. Requests from anywhere else answer 403 with data.code = "ip_not_allowed".
Monthly credit limit
A key can carry its own monthly credit limit, set when you create it and changed from its edit page. What a key's runs cost counts against it for the calendar month (UTC): a run that fails and is refunded gives its credits back, and a batch holds each picture's quote until it runs (then its real cost) or is cancelled or refused (then nothing). At the limit, POST /v1/generate answers 429 with data.code = "key_credit_limit_reached", the reset time in data.resetsAt and a Retry-After header, and the MCP generate_3d and generate tools return a tool error carrying the same code; nothing is charged, and the account's other keys keep working.
Which plans include API access
API access is included with every paid plan and credit pack. Without it, requests answer 403 with data.code = "plan_required"; the key is kept and works again once the plan is active. See rate limits for the plan table.
AI assistants
Assistants such as Claude and ChatGPT sign in with OAuth where this site runs it (its https://ai3d.studio/.well-known/oauth-protected-resource/mcp document then lists an authorization server), and otherwise connect with an API key sent as a Bearer header. See the MCP connector page.