Skip to content

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

HTTP
Authorization: Bearer sk-your-key
# or
x-api-key: sk-your-key

Send 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

ScopeAllows
readaccount, 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)
generatestart 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.