Authentication

Every request to https://api.fiveapi.ai needs an API key. Keys belong to your account: every key of an account sees the same tasks, balance and limits.

Create a key

Sign in to the developer console and open API Keys.
Click Create key and give it a name that says where it runs, for example prod-backend or staging-worker.
Optionally narrow it down with scopes, an expiry date and an IP allowlist (see Key options).
Copy the key. It starts with sk_live_ and is shown only once: Five API stores a hash, not the key.

Treat API keys like passwords. Load them from an environment variable or a secret manager, call Five API from your server only, and never ship a key in a web page, a mobile app or a public repository.

Send the key

Send the key in the Authorization header with the Bearer scheme. The x-api-key header is accepted as an alternative; use one or the other.

curl https://api.fiveapi.ai/v1/account \
  -H "Authorization: Bearer $FIVEAPI_API_KEY"

import os
import requests

response = requests.get(
    "https://api.fiveapi.ai/v1/account",
    headers={"Authorization": f"Bearer {os.environ['FIVEAPI_API_KEY']}"},
    timeout=15,
)
print(response.json()["balance"])

const response = await fetch("https://api.fiveapi.ai/v1/account", {
  headers: { Authorization: `Bearer ${process.env.FIVEAPI_API_KEY}` },
});
console.log((await response.json()).balance);

curl https://api.fiveapi.ai/v1/account \
  -H "x-api-key: $FIVEAPI_API_KEY"

Scopes

Each key carries one or more scopes. New keys get all three unless you narrow them down.

Scope	Allows
`video:write`	Create tasks (`POST /v1/{brand}/{version}/{task}`) and cancel them (`POST /v1/tasks/{task_id}/cancel`)
`video:read`	Read and list tasks (`GET /v1/tasks/{task_id}`, `GET /v1/tasks`)
`account:read`	Read the balance, the plan and the usage (`GET /v1/account`, `GET /v1/account/usage`)
any key	List and read models (`GET /v1/models`, `GET /v1/models/{brand}/{version}/{task}`)

A request that needs a scope the key lacks answers 403 insufficient_scope. For example, give a dashboard that only shows task status a video:read key.

Key options

Option	What it does
Scopes	Limits the endpoints the key can call (see above).
Expiry date	After it, the key answers `401 api_key_expired`.
IP allowlist	IPv4 and IPv6 addresses or CIDR ranges. Requests from any other address answer `403 ip_not_allowed`. Use it when your servers have fixed egress addresses.

An account can hold up to 20 active keys. Use separate keys for production, staging and CI so you can revoke one without touching the others. More keys never raise a limit: rate limits, the concurrency cap, the balance and idempotency keys are shared by the whole account.

Rotate or revoke a key

To rotate a key without downtime:

Create a new key with the same options.
Deploy it to your servers.
Revoke the old key in API Keys.

Revocation takes effect within 60 seconds. After that the old key answers 401 api_key_revoked.

Team members

Invite teammates to your account from the console. Each member has a role:

Role	Can
`viewer`	Read everything: tasks, usage, credits, keys (prefix only) and webhook deliveries
`admin`	Everything a viewer can, plus create and revoke keys, manage webhooks, invite admins and viewers, and buy credits
`owner`	Everything, including account settings, member roles and inviting owners

Members sign in to the console; only API keys call the API.

Authentication errors

HTTP	`code`	Meaning
`401`	`invalid_api_key`	No key was sent, or no key has this value
`401`	`api_key_revoked`	The key was revoked in the console
`401`	`api_key_expired`	The key is past its expiry date
`403`	`insufficient_scope`	The key lacks the scope for this endpoint
`403`	`ip_not_allowed`	The caller’s IP address is not on the key’s allowlist
`403`	`account_not_active`	The account has not been approved yet
`403`	`account_suspended`	The account was suspended

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "missing API key: send Authorization: Bearer sk_live_… (or x-api-key)",
    "request_id": "req_01M5KN14MXD6SJ01ZQ2FPS6Y8X"
  }
}

See Errors for the full catalogue.

Get started

Core concepts

Guides

Build with AI

Resources

Create a key

Send the key

Scopes

Key options

Rotate or revoke a key

Team members

Authentication errors

​Create a key

​Send the key

​Scopes

​Key options

​Rotate or revoke a key

​Team members

​Authentication errors

Create a key

Send the key

Scopes

Key options

Rotate or revoke a key

Team members

Authentication errors