# 认证

用 Bearer 方式在请求头发送 API 密钥。

每个请求都要在 `Authorization` 请求头带上 API 密钥。示例只引用环境变量 `CHENVOYA_API_KEY`，不写出密钥本身。

## 发送 API 密钥

在 `Authorization` 请求头写 `Bearer`、一个空格和 API 密钥：

```bash
Authorization: Bearer ${CHENVOYA_API_KEY}
```

密钥缺失或无效时返回 `401 authentication_failed`，响应头 `WWW-Authenticate` 给出 Bearer 认证要求。

## 创建和保管

- 在控制台的「[API 密钥](./integration.html)」页创建 API 密钥；同一个 API 密钥可以调用全部模型。
- 只在服务器端保存和使用 API 密钥，放在环境变量或密钥管理服务里；不要写进网页、App、代码仓库、文档或日志。
- 怀疑泄露时，在控制台停用它并新建一个，再替换服务器上的值。

## 权限和团队

API 密钥属于团队。任务和素材按团队隔离：团队里任何一把 API 密钥创建的任务，都能用本团队的其他 API 密钥查询；其他团队的任务和素材一律返回 `task_not_found` 或 `asset_not_found`。

登记素材和查询素材需要 API 密钥有 `service.use` 权限，否则返回 `403 permission_denied`。

## 认证相关的错误

| 状态码 | error.code | 怎么处理 |
| --- | --- | --- |
| 401 | `authentication_failed` | 检查 `Authorization: Bearer` 后面的 API 密钥。 |
| 403 | `permission_denied` | 换一把有 `service.use` 权限的 API 密钥。 |
| 409 | `key_provisioning_incomplete` | 这把 API 密钥的额度配置未完成：删除它，再新建一把。 |

## 下一步

- [请求约定](./api-docs-zh-conventions.md)：接入地址、JSON、请求标识、时间、金额和翻页的通用规则。
- [快速开始](./api-docs-zh-quickstart.md)：三步生成第一个视频：创建 API 密钥，提交任务，取回结果。
- [错误码](./api-docs-zh-api-errors.md)：每个 error.code 的含义、状态码和出现的接口。