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

快速开始 ​

本页使用 cURL 完成一次 Seedance 文本生成视频调用:提交任务、保存任务 ID、查询进度并获取视频地址。 提供 2.0 和 2.5 两个版本的创建示例,选择其中一个执行即可,后续查询方式相同。 命令适用于 Bash 或 Zsh,需已安装 curl。

一、概述 ​

请确认已取得 API Key,账户积分充足,且 API Key 具有所选模型 seedance-2.0 或 seedance-2.5 的访问权限。

基础信息 ​

项目说明
网关地址https://openapi.yhsapi.com
接口基础路径/api/v3/contents/generations/tasks
请求协议HTTP
数据格式JSON
认证方式Bearer Token(API Key)

二、认证方式 ​

所有接口均需在请求头中携带 API Key 进行认证:

Authorization: Bearer {您的API Key}
Content-Type: application/json

注意:API Key 可在平台控制台的密钥管理页面获取。请妥善保管您的 API Key,切勿泄露给第三方。

请在同一个终端会话中依次执行命令。

bash
export PLATFORM_BASE_URL='https://openapi.yhsapi.com'
export PLATFORM_API_KEY='YOUR_API_KEY'

PLATFORM_BASE_URL 只填写协议和服务域名,不包含 /api/v1 或 /api/v3,末尾不加 /。 YOUR_API_KEY 替换为控制台签发的完整密钥。真实密钥应由服务端安全配置注入,避免保存在共享脚本中。

三. 创建视频任务 ​

提交一次生成请求,保存接口返回的任务 ID。

1. 使用 Seedance 2.0 ​

bash
curl --silent --show-error --include \
  --connect-timeout 10 --max-time 120 \
  --request POST \
  "${PLATFORM_BASE_URL}/api/v3/contents/generations/tasks" \
  --header "Authorization: Bearer ${PLATFORM_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "一只橘猫在海边慢慢奔跑,夕阳暖光,镜头平稳跟随"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'

2. 使用 Seedance 2.5 ​

如果选择 2.5,请执行本段命令,无需再执行前面的 2.0 命令。 2.5 普通生成可显式提交 draft: false;该字段不要带入 2.0 请求。

bash
curl --silent --show-error --include \
  --connect-timeout 10 --max-time 120 \
  --request POST \
  "${PLATFORM_BASE_URL}/api/v3/contents/generations/tasks" \
  --header "Authorization: Bearer ${PLATFORM_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2.5",
    "content": [
      {
        "type": "text",
        "text": "一只橘猫在海边慢慢奔跑,夕阳暖光,镜头平稳跟随"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true,
    "draft": false
  }'

受理响应 ​

两个版本受理成功均返回 HTTP 200,响应体如下:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

保存实际返回的 id。它是平台任务 UUID,用于后续查询。 此响应表示任务已受理,视频将在后台生成。 两个版本均不提交 service_tier、frames、seed 和 camera_fixed。 2.0 还应省略 draft、draft_task、output_format 和 omni_reference_task_type。 其他输入模式及 2.5 专属参数见创建视频任务。 创建请求超时或响应丢失时,请先在控制台调用记录中核实任务是否已受理,避免重复创建。

3. 查询任务 ​

使用创建任务时的同一个 API Key,并将 VIDEO_TASK_ID 替换为实际返回的 ID。

bash
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}"

处理中的示例:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "seedance-2.0",
  "status": "running",
  "created_at": 1792800000,
  "updated_at": 1792800005
}

如果创建时选择 2.5,查询响应的 model 会对应 seedance-2.5,任务状态和产物字段的判断方式相同。

生成成功且产物就绪后的示例:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "seedance-2.0",
  "status": "succeeded",
  "created_at": 1792800000,
  "updated_at": 1792800060,
  "content": {
    "video_url": "https://media.example.com/generated/video.mp4"
  }
}

建议客户端从每隔 3~5 秒查询一次开始,并在遇到 HTTP 429 时增加间隔。 这是客户端接入建议,不代表服务端保证的任务完成时间。 达到客户端等待上限时,保留任务 ID,稍后继续查询。 命令中的 --max-time 仅限制单次 HTTP 请求的等待时间,不会取消已受理的视频任务。

4. 获取结果 ​

status 为 succeeded 且存在 content.video_url 时,可通过该地址访问或下载视频。 默认存储链接有效期为签发后 24 小时,重复查询不会自动延长有效期,请及时保存视频。 若使用自定义存储且地址尚未返回,请同时检查 custom_storage_status。 若状态为 failed、cancelled 或 expired,停止常规轮询并按任务结果处理。

完整字段及错误说明见创建视频任务和查询视频任务。

常见接入问题 ​

  • 返回 HTTP 401:检查密钥是否完整、有效,Authorization 是否使用 Bearer 格式。
  • 返回 HTTP 403:检查模型权限、账户积分、API Key 额度及来源 IP 白名单。
  • 返回 HTTP 400:按 error.param 检查字段,确认使用 JSON 原生数值和布尔值。
  • 返回 HTTP 429:降低请求频率;如达到任务并发上限,等待已有任务完成后再提交。
  • 创建请求超时:先核实调用记录;已取得任务 ID 时继续查询,受理情况不明时联系支持排查。
  • 查询返回 HTTP 404:检查任务 ID 是否来自实际创建响应,并确认使用创建任务时的同一个 API Key。