Seedance 2.0 视频生成 | UniKeyX API Docs

1

Before request

调用前准备好 Key、模型名和视频规格

请求从服务端发起，不要把 API Key 放进浏览器前端。

用户侧只需要使用 UniKeyX API Key、选择模型、填写提示词和视频规格。视频生成是异步任务，创建后保存任务 ID 再轮询状态。

高质量模型 doubao-seedance-2-0-260128

适合正式生成，支持更完整的分辨率与多模态输入能力。

快速模型 doubao-seedance-2-0-fast-260128

适合预览和快速出片。通常建议时长控制在 4 到 15 秒。

2

Quick start

三步完成一次视频生成

在 UniKeyX 控制台创建 API Key，并确认它所在分组已启用 Seedance 2.0。
新项目建议调用 POST /v1/videos 创建任务；从豆包官方接口迁移时，也可以调用 POST /api/v3/contents/generations/tasks。
保存创建接口返回的 id，并使用同一套接口路径轮询状态，直到任务完成或失败。

这是异步接口

创建任务接口只返回任务 ID，不会直接返回最终视频文件。建议每 5 秒查询一次状态，避免过于频繁地轮询。

3

Create video

创建视频任务

文字生成视频

curl https://api2.unikeyx.com/v1/videos \
  -H "Authorization: Bearer YOUR_UNIKEYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "一只白色机器人在清晨的玻璃温室里浇花，电影感镜头，柔和自然光",
    "seconds": "5",
    "metadata": {
      "resolution": "720p",
      "ratio": "16:9",
      "generate_audio": true,
      "watermark": false
    }
  }'

图片生成视频

curl https://api2.unikeyx.com/v1/videos \
  -H "Authorization: Bearer YOUR_UNIKEYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-fast-260128",
    "prompt": "让画面中的产品缓慢旋转，背景保持干净，突出金属质感",
    "seconds": "5",
    "images": [
      "https://example.com/product-reference.png"
    ],
    "metadata": {
      "resolution": "720p",
      "ratio": "1:1",
      "watermark": false
    }
  }'

成功响应

{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video",
  "model": "doubao-seedance-2-0-260128",
  "status": "queued",
  "progress": 0,
  "created_at": 1784700000
}

需要保存

后续所有查询与下载都使用响应里的 id。不要使用上游供应商任务 ID，也不要把 API Key 放到浏览器前端。

4

Doubao native format

豆包原生视频接口格式

适合从豆包官方接口迁移的项目

原生接口使用 /api/v3/contents/generations/tasks，请求体字段与豆包视频生成格式保持一致：输入内容放在顶层 content 数组里，不需要再包进 metadata。如果你已经按豆包官方文档把比例和时长写在提示词里，可以直接迁移。

豆包原生：文字生成视频

curl https://api2.unikeyx.com/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer YOUR_UNIKEYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "一只白色机器人在清晨的玻璃温室里浇花，电影感镜头，柔和自然光 --ratio 16:9 --dur 5"
      }
    ]
  }'

豆包原生：图片生成视频

curl https://api2.unikeyx.com/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer YOUR_UNIKEYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-fast-260128",
    "content": [
      {
        "type": "text",
        "text": "让画面中的产品缓慢旋转，背景保持干净，突出金属质感 --ratio 1:1 --dur 5"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/product-reference.png"
        }
      }
    ]
  }'

豆包原生：查询任务

curl https://api2.unikeyx.com/api/v3/contents/generations/tasks/task_xxxxxxxxxxxxx \
  -H "Authorization: Bearer YOUR_UNIKEYX_API_KEY"

豆包原生：完成响应示例

{
  "id": "task_xxxxxxxxxxxxx",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": {
    "video_url": "https://..."
  }
}

注意：/v1/videos 与豆包原生路径都是异步任务接口。建议创建和查询使用同一套路径，避免把两种响应格式混用。

5

Fetch result

查询状态并下载视频

查询任务状态

curl https://api2.unikeyx.com/v1/videos/task_xxxxxxxxxxxxx \
  -H "Authorization: Bearer YOUR_UNIKEYX_API_KEY"

下载生成结果

curl -L https://api2.unikeyx.com/v1/videos/task_xxxxxxxxxxxxx/content \
  -H "Authorization: Bearer YOUR_UNIKEYX_API_KEY" \
  -o seedance-output.mp4

完成状态响应

{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video",
  "model": "doubao-seedance-2-0-260128",
  "status": "completed",
  "progress": 100,
  "created_at": 1784700000,
  "completed_at": 1784700060,
  "metadata": {
    "url": "https://..."
  }
}

结果 URL 可能有有效期

任务完成后建议立即下载或转存到自己的对象存储。对外展示时优先使用自己的文件地址，不要长期依赖临时结果地址。

6

Parameters

常用请求参数

model 必填。使用 doubao-seedance-2-0-260128 或 doubao-seedance-2-0-fast-260128。

prompt 必填。描述视频内容、镜头、主体、动作、风格和限制。仅传素材不写提示词时，生成效果不可控。

seconds 推荐填写字符串，如 "5"。常用范围 4 到 15 秒；部分后端也兼容整数 duration。

images 可选。图片 URL 数组，适合图生视频、首帧参考或风格参考。素材地址必须能被服务端访问。

metadata.resolution 可选。常用 480p、720p、1080p、4k。fast 模型不建议使用 1080p 或 4k。

metadata.ratio 可选。支持 16:9、4:3、1:1、3:4、9:16、21:9、adaptive。

metadata.generate_audio 可选。是否生成音频，布尔值。需要静音视频时设为 false。

metadata.watermark 可选。是否带水印，布尔值。默认建议显式设置为 false。

metadata.seed 可选。固定随机种子，便于复现实验结果。

豆包原生接口参数对照

content 必填。顶层数组。文字用 { "type": "text", "text": "..." }；图片用 { "type": "image_url", "image_url": { "url": "..." } }。

duration 可选。迁移官方写法时可在文本里写 --dur 5；api2 也兼容顶层整数 "duration": 5，对应兼容接口里的 seconds。

resolution / ratio 可选。迁移官方写法时可在文本里写 --ratio 16:9；api2 也兼容顶层字段，例如 "resolution": "720p"、"ratio": "16:9"。

generate_audio / watermark 可选。布尔值。需要显式控制时可放在请求体顶层，例如 "generate_audio": true、"watermark": false。

高级素材写法：首帧、尾帧、视频或音频参考

metadata.content

{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "根据首帧和尾帧生成自然过渡，镜头平滑推进",
  "seconds": "6",
  "metadata": {
    "resolution": "720p",
    "ratio": "16:9",
    "content": [
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": { "url": "https://example.com/first.png" }
      },
      {
        "type": "image_url",
        "role": "last_frame",
        "image_url": { "url": "https://example.com/last.png" }
      }
    ]
  }
}

高级能力支持参考图、首帧、尾帧、参考视频和参考音频。实际可用性以接口返回为准；建议先用短时长、720p 做一次端到端测试。

Troubleshooting

常见错误与处理

返回 401 或 Invalid token

检查请求头是否包含 Authorization: Bearer YOUR_UNIKEYX_API_KEY，并确认 Key 没有被禁用或复制时多了空格。

提示 model not found 或模型不可用

检查 model 是否填写正确、API Key 是否有该模型调用权限，以及账户额度是否充足。

提示 duration 或 seconds 不合法

先用 "seconds": "5" 测试。fast 模型建议使用 4 到 15 秒；超过当前模型限制会返回参数错误。

/v1/videos 和豆包原生接口怎么选？

新项目优先使用 /v1/videos，返回格式统一，也可以使用 /v1/videos/{id}/content 下载结果。从豆包官方接口迁移时，使用 /api/v3/contents/generations/tasks 可以减少请求体改造。

任务一直是 queued 或 in_progress

视频生成可能需要几十秒到数分钟。建议每 5 秒轮询一次；如果长时间没有变化，再记录任务 ID 给技术支持排查。

任务 failed

读取响应里的 error.message。常见原因包括提示词或素材不合规、图片 URL 无法访问、分辨率与模型不兼容、余额不足。

用 UniKeyX 生成 Seedance 2.0 视频