跳转到正文
阅读设置
快速上手

身份认证 ​

开放平台模型调用使用 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,联系支持处理原密钥任务的查询问题。

密钥安全 ​

  1. 仅通过 HTTPS 调用,将密钥保存在服务端环境变量或密钥管理系统中。
  2. 按应用或环境分别创建密钥,并配置必要的模型权限、额度和 IP 白名单。
  3. 不在浏览器代码、公开文档、截图或日志中展示真实密钥。
  4. 发现泄露后及时停用并更换密钥,同时检查调用记录。