API Key鉴权使用说明
更新时间：2026-03-13
简介
为了简化服务端调用的鉴权流程，开发者可以使用 API Key 代替复杂的 AccessKey (AK/SK) 签名方式。API Key 采用标准的 Bearer Token 模式，适用于需要快速集成的服务端请求场景。 暂时APIKey只支持视频生成v3相关接口，v2接口依旧只支持AKSK鉴权
使用流程
流程只要分为一下三步：
- 创建API Key并输入API key的名称完成创建
- 使用API Key调用服务接口
鉴权说明
API Key需要在HTTP请求头（Header）中通过Authorization字段传递 注意Bearer 前缀
开放APIKey权限接口
v3对应接口请求参数和v2接口对应请求参数相同，详情请参考
| 请求接口 | v2接口 | 接口描述 |
|---|---|---|
| PUT & POST /v3/aigc/subject/custom/{manu} | PUT & POST /v2/aigc/subject/custom/{manu} | 创建和修改主体库 |
| POST /v3/aigc/recommend/effect | POST /v2/aigc/recommend/effect | 特效推荐 |
| POST /v3/aigc/image_to_image | POST /v2/aigc/image_to_image | 图生图 |
| POST /v3/aigc/video_clone | POST /v2/aigc/video_clone | 视频克隆 |
| POST /v3/aigc/text_to_image | POST /v2/aigc/text_to_image | 文生图 |
| GET /v3/aigc/effect | GET /v2/aigc/effect | 查询所有的特效 |
| POST /v3/aigc/video_extend | POST /v2/aigc/video_extend | 视频延长 |
| POST /v3/aigc/text_to_video | POST /v2/aigc/text_to_video | 文生视频 |
| GET /v3/aigc/kl/general/advanced-presets-elements | GET /v2/aigc/kl/general/advanced-presets-elements | 查询主体库 |
| GET /v3/aigc/kl/general/advanced-custom-elements/{taskId} | GET /v2/aigc/kl/general/advanced-custom-elements/{taskId} | 查询自定义主体库 |
| POST /v3/aigc/kl/general/advanced-custom-elements | POST /v2/aigc/kl/general/advanced-custom-elements | 创建自定义主体库 |
| POST /v3/aigc/kl/general/custom-voices | POST /v2/aigc/kl/general/custom-voices | 创建自定义音色 |
| GET /v3/aigc/kl/general/custom-voices/{id} | GET /v2/aigc/kl/general/custom-voices/{id} | 查询自定义音色 |
| GET /v3/aigc/kl/general/presets-voices | GET /v2/aigc/kl/general/presets-voices | 查询音色 |
| POST /v3/aigc/lip_sync | POST /v2/aigc/lip_sync | 对口型 |
| POST /v3/aigc/create_effect_video | POST /v2/aigc/create_effect_video | 特效视频 |
| POST /v3/aigc/image_to_video | POST /v2/aigc/image_to_video | 图生视频 |
| POST /v3/aigc/image | POST /v2/aigc/image | 生图 |
| GET /v3/tasks/{taskId} | GET /v2/tasks/{taskId} | 查询任务 |
使用示例
Plain Text
1curl --location --request POST 'http://vod.bj.baidubce.com:8301/v3/aigc/text_to_video' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer bce-v3/ALTAK-*******/********************' \
4--d '{
5 "model": "P40",
6 "modelP40TaskInput": {
7 "duration": 5,
8 "prompt": "生成一个皮卡丘",
9 "seed": 10000001,
10 "style": "anime",
11 "resolution": "540p",
12 "aspectRatio": "16:9"
13 }
14}'错误码参考
| HTTP 状态码 | 错误代码 (Code) | 描述与常见触发场景 |
|---|---|---|
| 400 | InvalidSessionToken | 会话 Token 无效。 |
| 400 | SessionTokenExpired | 会话 Token 已过期。 |
| 400 | InvalidHTTPAuthHeader | 身份验证头错误。可能由于：1. 服务号签名错误；2. API Key 解析错误。 |
| 400 | MalformedJSON | JSON 格式非法，无法解析。 |
| 400 | RequestExpired | 请求已失效（请求时间与系统时间偏差过大）。 |
| 401 | Unauthorized | 未经授权。凭证无效或由于身份验证失败。 |
| 403 | AccessDenied | 拒绝访问。用户没有执行该操作的权限。 |
| 403 | SignatureDoesNotMatch | 签名不匹配，请检查签名算法实现。 |
| 403 | UserDisabled | 当前用户已被禁用。 |
| 404 | NotFound | 资源未找到。可能由于：1. 服务号签名对应的 AK 不存在；2. 用户 AK 不存在；3. API Key 不存在。 |
| 405 | MethodNotAllowed | 不支持的 HTTP 请求方法。 |
| 409 | ResourceConflict | 资源状态冲突（如重复创建或状态不匹配）。 |
| 413 | BodyOverLimit | 请求体大小超过系统限制。 |
| 500 | InternalError | 服务器内部错误。可能由于内部组件处理异常。 |
排查建议：
- 400/401 错误：请优先检查 Authorization Header 的拼写，确保 API Key 带有 Bearer bce-v3/ 前缀。
- 403 错误：如果身份识别成功但仍返回 403，通常是由于您的 IAM 子用户权限策略（Policy）未授予对应的 VOD 操作权限。
- 404 错误：若 API Key 字符串无误但返回 NotFound，请登录控制台确认该 Key 是否已被删除或所属用户是否存在。