# 认证

创建、发送和保护 ViewMax API key。

## 创建 API key

登录后打开 [Settings → API Keys](https://viewmax.studio/settings/apikeys)，点击 **Create API Key**。key 的格式为 `sk-` 加 32 位字母和数字。请将 key 存放在密钥管理服务或环境变量（如 `VIEWMAX_API_KEY`）中。

## 发送 key

每个需要认证的请求都在 `Authorization` 请求头中发送 key：

```http
Authorization: Bearer sk-your-api-key
```

```bash
curl -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  https://viewmax.studio/api/v1/credits
```

建议带上 `Bearer` 前缀；直接发送 `sk-...` 也可以。

| 端点                                                                                 | 需要 key |
| ------------------------------------------------------------------------------------ | -------- |
| `GET /api/v1/models`、`GET /api/v1/voices`、`/openapi.json`、`/api/openapi.yaml`     | 否       |
| `POST /api/v1/videos`、`images`、`music`、`speech`、`sound-effects`、`shorts-studio` | 是       |
| `GET /api/v1/tasks/{taskId}`、`GET /api/v1/credits`、`GET /api/v1/shorts-studio`     | 是       |

## 缺少或无效的 key

没有有效 key 的请求返回 HTTP `401`：

```json
{
  "code": -1001,
  "message": "unauthorized",
  "error": {
    "type": "unauthorized",
    "hint": "Send Authorization: Bearer sk-... with a key from Settings → API Keys.",
    "docs": "https://viewmax.studio/docs/api/authentication"
  }
}
```

已登录的 viewmax.studio 浏览器会话也能认证同源请求，因此带有该会话 cookie 的请求即使没有 key 也会成功。脚本和服务端应始终发送 key。

## key 的权限

- 每个 key 代表整个账户：它消耗账户的积分余额，并能读取账户下的所有任务，包括在网页端或通过 MCP 创建的任务。
- key 没有 scope，也没有按 key 的速率限制。
- REST API 只接受 API key。OAuth 访问令牌和 scope（`models:read`、`tasks:read`、`tasks:write`、`credits:read`）仅用于 [MCP 服务](https://viewmax.studio/zh/docs/mcp)，不适用于 `/api/v1`。

## 从服务端调用

v1 API 不返回 CORS 头，因此其他来源的浏览器页面无法调用。请将 key 保存在你的服务端，并从服务端调用 ViewMax。不要把 key 放进浏览器代码、移动应用、公开仓库、截图，或发给不可信方的提示词中。

## 吊销或更换 key

没有轮换操作。要更换 key，请先创建新 key，将集成切换到新 key，再在 [Settings → API Keys](https://viewmax.studio/settings/apikeys) 删除旧 key。删除后 key 立即失效。**Edit** 只能重命名 key。

任何已经泄露的 key 都应视为已被盗用并立即删除。