Seedance 视频生成接入指南​

Seedance 视频生成采用异步任务模式：先创建任务取得 id，再查询任务状态，成功后读取 content.video_url。

开始前请准备：

  1. 在 控制台 创建 API Key。
  2. 在控制台确认当前账号可用的 Model ID 或 Endpoint ID。
  3. 所有客户请求都发送到当前平台地址：https://art-api.yuyuflow.com。
操作方法与地址鉴权
创建任务POST https://art-api.yuyuflow.com/api/v3/contents/generations/tasksAPI Key
查询任务GET https://art-api.yuyuflow.com/api/v3/contents/generations/tasks/{id}API Key

两套凭证不要混用

本页的视频生成与查询接口使用 Authorization: Bearer <API_KEY>。素材库管理使用 AK/SK 签名，详见素材库 Python SDK。

1. 创建视频任务​

先用最简单的文生视频请求确认域名、鉴权、模型和任务流程都可用。请将 YOUR_API_KEY 和 YOUR_MODEL_ID 替换为控制台中的实际值。

bash
curl -X POST "https://art-api.yuyuflow.com/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "content": [
      {
        "type": "text",
        "text": "一只橘猫坐在窗边打哈欠，清晨自然光，镜头缓慢推进"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "watermark": false
  }'

创建成功后会返回任务 ID：

json
{
  "id": "cgt-xxxxxxxx"
}

请保存这个 id。创建成功只代表任务已提交，不代表视频已经生成完成。

2. 查询任务状态​

bash
curl "https://art-api.yuyuflow.com/api/v3/contents/generations/tasks/cgt-xxxxxxxx" \
  -H "Authorization: Bearer YOUR_API_KEY"

任务状态通常按以下流程变化：

text
queued → running → succeeded
                 ↘ failed / cancelled / expired
状态客户端处理
queued / running继续等待并查询
succeeded读取 content.video_url
failed记录 error.code 与 error.message，停止轮询
cancelled / expired任务已终止，停止轮询

建议前 30 秒每 2～3 秒查询一次，之后每 5～10 秒查询一次。生产环境也可以在创建任务时设置 callback_url，由平台推送状态变化。

3. 保存视频结果​

成功响应示例：

json
{
  "id": "cgt-xxxxxxxx",
  "status": "succeeded",
  "content": {
    "video_url": "https://example.com/generated-video.mp4",
    "last_frame_url": "https://example.com/last-frame.png"
  },
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "usage": {
    "completion_tokens": 123456,
    "total_tokens": 123456
  }
}

结果地址不是永久存储

任务记录仅保留最近 7 天，video_url 通常只在 24 小时内有效。请先使用标准 JSON 解析器读取完整 URL，再及时下载或转存到自己的对象存储。不要从原始响应文本中直接截取带转义的 URL。

选择生成场景​

四种生成场景互斥。先确定场景，再组织 content 数组。

场景输入role
文生视频文本无
首帧图生视频1 张图片，可加文本first_frame 或不填
首尾帧图生视频2 张图片，可加文本first_frame + last_frame
多模态参考生视频图片、视频、音频与可选文本reference_image / reference_video / reference_audio

场景不可混用

首帧、首尾帧和多模态参考是三种不同的图生视频方式。同一个请求中不要同时使用 first_frame 和 reference_image。参考音频不能单独输入，至少还需要一张参考图片或一个参考视频。

首帧与首尾帧示例

首帧图生视频：

json
{
  "model": "YOUR_MODEL_ID",
  "content": [
    { "type": "text", "text": "人物回头微笑，镜头缓慢推进" },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": { "url": "https://example.com/start.png" }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

首尾帧图生视频需要两个 role 都填写：

json
{
  "model": "YOUR_MODEL_ID",
  "content": [
    { "type": "text", "text": "镜头缓慢推进，人物自然转身" },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": { "url": "https://example.com/start.png" }
    },
    {
      "type": "image_url",
      "role": "last_frame",
      "image_url": { "url": "https://example.com/end.png" }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "return_last_frame": true
}
多模态参考示例

多模态参考能力取决于当前使用的模型。图片、视频和音频必须使用对应的 reference_* 角色：

json
{
  "model": "YOUR_MODEL_ID",
  "content": [
    { "type": "text", "text": "保持人物神态，将背景切换到海边" },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://mas_xxxxxxxxx" }
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": { "url": "https://example.com/reference.mp4" }
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": { "url": "https://example.com/reference.wav" }
    }
  ],
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": 5
}

使用素材库资源​

已入库并处于 Active 状态的素材可以通过 asset://<ASSET_ID> 引用：

json
{
  "type": "image_url",
  "role": "reference_image",
  "image_url": {
    "url": "asset://mas_xxxxxxxxx"
  }
}

不要只传裸的 mas_xxxxxxxxx。缺少 asset:// 前缀时，请求可能被判定为无效素材地址。

如果还没有素材 ID，可以使用素材库 Python SDK创建素材组、上传素材并等待状态变为 Active。

真人素材限制​

未经授权的真人人脸参考图或视频可能触发安全限制。客户应使用以下合规来源之一：

  1. 当前账号近期由支持模型生成的可复用人脸产物。
  2. 平台提供的虚拟人像素材。
  3. 完成真人认证和授权流程后进入私域素材库的真人素材。

对应文档：

状态、回调与超时参数
  • callback_url：任务状态变化时向该地址发送 POST 请求，响应结构与查询任务相同；推送失败时平台会进行有限次数重试。
  • execution_expires_after：任务执行超时阈值，默认 172800 秒，可配置范围为 3600～259200 秒。
  • return_last_frame：成功时返回无水印尾帧，可作为下一段视频的 first_frame。
  • safety_identifier：终端用户稳定标识，建议传不可逆哈希值，避免传递姓名、手机号等直接个人信息。
样片模式

部分模型支持样片模式，用较低成本先验证场景、动作和镜头调度：

json
{
  "model": "YOUR_MODEL_ID",
  "content": [
    { "type": "text", "text": "镜头从远景推进到人物特写" }
  ],
  "draft": true
}

基于样片生成正式视频时，使用样片任务 ID：

json
{
  "model": "YOUR_MODEL_ID",
  "content": [
    {
      "type": "draft_task",
      "draft_task": { "id": "YOUR_DRAFT_TASK_ID" }
    }
  ],
  "resolution": "720p"
}

样片能力、强制分辨率和可用参数依模型而异，请以控制台当前开放能力为准。

输入格式与素材规格速查
类型公网 URLBase64asset://
图片支持支持支持
视频支持不支持支持
音频支持支持支持
  • Base64 前缀中的格式名使用小写，例如 data:image/png;base64,...。
  • 大文件优先使用稳定、无需 Cookie、无需登录的公网 URL。
  • 图片常用格式包括 jpeg、png、webp、bmp、tiff、gif；单张通常应小于 30 MB。
  • 视频通常使用 mp4 或 mov；参考视频数量、总时长和大小受模型限制。
  • 音频通常使用 wav 或 mp3；参考音频不能作为唯一的非文本输入。

常见问题​

  • 创建接口收到顶层 prompt 后失败：官方任务路径应提交 content 数组，纯文本也要写成 { "type": "text", "text": "..." }。
  • 首尾帧参数无效：确认两个图片对象分别填写 first_frame 和 last_frame。
  • 素材 ID 无效：确认使用 asset://mas_xxx，素材真实存在且状态为 Active。
  • 素材下载失败：确认 URL 无防盗链、无需 Cookie、响应类型正确，并在处理期间保持可访问。
  • 结果 URL 下载失败：先解析 JSON，再读取 content.video_url；签名 URL 应在有效期内使用。
  • 4K 播放异常：部分高分辨率视频编码需要兼容相应格式的播放器。

继续阅读​