> ## Documentation Index
> Fetch the complete documentation index at: https://testweb2-docs-openapi.test765.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Five API is a video generation REST API. Base URL: https://api.fiveapi.ai. Authenticate with the header Authorization: Bearer <API key>; read the key from the FIVEAPI_API_KEY environment variable and never hard-code it.
> Every generation is an asynchronous task: POST /v1/{brand}/{version}/{task} returns a queued task, then poll GET /v1/tasks/{task_id} or receive a signed webhook, and download output.video.url before expires_at (7 days).
> The OpenAPI spec is at https://docs.fiveapi.ai/api-reference/openapi.yaml. An installable agent skill: npx skills add https://docs.fiveapi.ai

# Authentication

> Create API keys, send them with every request, and limit what each key can do.

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

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

> [!WARNING]
>
> 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.

```bash cURL theme={null}
curl https://api.fiveapi.ai/v1/account \
  -H "Authorization: Bearer $FIVEAPI_API_KEY"
```

```python Python theme={null}
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"])
```

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

```bash x-api-key header theme={null}
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:

1. Create a new key with the same options.
2. Deploy it to your servers.
3. 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 |

```json theme={null}
{
  "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](https://testweb2-docs-openapi.test765.com/concepts/errors.md) for the full catalogue.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.