身份认证
开放平台模型调用使用 API Key 认证。请在每次创建和查询请求中通过 HTTP 请求头传入密钥:
http
Authorization: Bearer <YOUR_API_KEY>将 <YOUR_API_KEY> 替换为实际密钥,不保留尖括号。 密钥由平台签发,当前格式为 LT- 加 32 位英文字母或数字;不要自行拼接密钥。 你可以登录控制台,在 API 密钥管理 中创建和管理密钥。
调用示例
将密钥和任务 ID 替换为实际值;查询任务需先取得创建接口返回的 ID。
bash
export PLATFORM_BASE_URL='https://openapi.yhsapi.com'
export PLATFORM_API_KEY='YOUR_API_KEY'
export VIDEO_TASK_ID='550e8400-e29b-41d4-a716-446655440000'
curl --silent --show-error --include \
--connect-timeout 10 --max-time 30 \
"${PLATFORM_BASE_URL}/api/v3/contents/generations/tasks/${VIDEO_TASK_ID}" \
--header "Authorization: Bearer ${PLATFORM_API_KEY}"示例环境变量的配置见快速开始。
创建与查询任务须使用同一个 API Key。同一账户下的其他 API Key 也不能查询该任务。 请保留任务与创建密钥之间的对应关系;停用或删除创建密钥后,该密钥将无法继续认证查询。
权限与限额
可用密钥仍须满足以下条件:
- API Key 未停用、删除或过期,所属账户状态正常。
- 启用 IP 白名单时,调用服务器的实际出口 IP 符合白名单规则。
- 创建任务时,API Key 有目标模型的访问权限,模型当前可用。
- 创建任务时,账户积分及 API Key 的总额度、日额度、月额度满足要求。
- 请求速率和任务并发未达到适用限制。
不要把 Web 登录 Token 当作 API Key 使用,也不要在 URL 参数或请求正文中提交 API Key。
认证失败
HTTP 401 表示密钥缺失、格式错误、无效、已停用或已过期。响应结构示例:
json
{
"error": {
"code": "InvalidApiKey",
"message": "The API key provided is invalid, disabled or has expired",
"type": "Unauthorized"
}
}error.code 为错误码,error.type 为错误类型,error.message 为可读说明。 HTTP 错误说明使用英文,响应头 Content-Language 为 en。
HTTP 403 表示当前身份未获准执行请求。常见原因包括账户不可用、来源 IP 不符、 没有模型权限或额度不足。HTTP 429 表示触发速率或并发限制, 不代表密钥无效。请结合 error.code 定位问题,不要依赖 message 的具体文本编写判断逻辑。
常见错误码及处理方式:
InvalidApiKey:检查密钥内容、启用状态和有效期。UserDisabled:检查所属账户状态。IpNotAllowed:将调用服务器的出口 IP 配置到白名单,或改用允许的服务器发起请求。ModelAccessDenied:为 API Key 授予目标模型的访问权限。AccountQuotaExceeded:检查账户可用积分。ApiKeyQuotaExceeded:检查 API Key 总额度。ApiKeyDailyQuotaExceeded、ApiKeyMonthlyQuotaExceeded:检查 API Key 日额度、月额度。
停用、过期或 IP 白名单不符也会阻止查询请求。 若需更换密钥,请先保存尚未完成的任务 ID,联系支持处理原密钥任务的查询问题。
密钥安全
- 仅通过 HTTPS 调用,将密钥保存在服务端环境变量或密钥管理系统中。
- 按应用或环境分别创建密钥,并配置必要的模型权限、额度和 IP 白名单。
- 不在浏览器代码、公开文档、截图或日志中展示真实密钥。
- 发现泄露后及时停用并更换密钥,同时检查调用记录。

