快速开始
本页使用 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,切勿泄露给第三方。
请在同一个终端会话中依次执行命令。
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
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 请求。
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,响应体如下:
{
"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。
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}"处理中的示例:
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"model": "seedance-2.0",
"status": "running",
"created_at": 1792800000,
"updated_at": 1792800005
}如果创建时选择 2.5,查询响应的 model 会对应 seedance-2.5,任务状态和产物字段的判断方式相同。
生成成功且产物就绪后的示例:
{
"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。

