SeedanceVideo

Generate AI videos with ByteDance Seedance (豆包/火山方舟) via Ark API. Supports text-to-video and image-to-video using model endpoint doubao-seedance-1-5-pro-2512...

视频生成：火山方舟 Seedance（豆包 Ark API）

概述

通过**火山引擎方舟（Ark）**的 REST API 调用豆包 Seedance 视频生成模型，支持：

• 文生视频：仅传入文本描述生成视频。
• 图生视频：传入一张图片 + 动作/场景描述，生成视频。
• 模型：使用推理接入点（Endpoint）ID，例如 doubao-seedance-1-5-pro-251215。提示词中可用参数控制时长、比例、镜头、水印等。

Base URL：https://ark.cn-beijing.volces.com。所有请求需在 Header 中携带：Authorization: Bearer $ARK_API_KEY。

准备

1. 在火山方舟创建 API Key，并创建/选用已部署 Seedance 视频生成 的推理接入点。
2. 设置环境变量（以下示例均依赖此变量）：

export ARK_API_KEY="your_ark_api_key_here"

核心流程

1. 创建任务：POST /api/v3/contents/generations/tasks，Body 中传 model（接入点 ID）和 content（见下）。响应返回任务 id。
2. 轮询状态：GET /api/v3/contents/generations/tasks/{id}，直到 status 为 succeeded 或 failed。建议每 8–15 秒轮询一次。
3. 获取视频：当 status 为 succeeded 时，从响应中的 content 里取 video_url（MP4，约 24 小时后清理，请及时下载）。

创建任务：请求体说明

• model（必填）：推理接入点 ID，需已部署视频生成模型。例如图生视频：doubao-seedance-1-5-pro-251215。
• content（必填）：数组，按顺序组合「文本」与「图片」：
  • 文生视频：一个元素即可，type: "text"，text 为视频描述，可在同一字符串内带参数，例如："描述内容 --duration 5 --ratio 16:9 --camerafixed false --watermark true"。
  • 图生视频：先一个 type: "text"（描述动作/场景，可带 --duration 等参数），再一个 type: "image_url"，image_url.url 为图片公网 URL。

文本中的常用参数（以空格分隔，写在描述后面）：

• --duration 5：时长（秒）。
• --ratio 1:1 或 16:9、9:16：画面比例。
• --camerafixed true/false：是否固定镜头（减少运动模糊）。
• --watermark true/false：是否加水印。
• --fps 24：帧率（视模型支持而定）。

快速开始：图生视频

# 1. 创建图生视频任务
resp=$(curl -s -X POST 'https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedance-1-5-pro-251215",
    "content": [
      {
        "type": "text",
        "text": "无人机以极快速度穿越复杂障碍或自然奇观，带来沉浸式飞行体验  --duration 5 --camerafixed false --watermark true"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://your-accessible-image-url.jpg"
        }
      }
    ]
  }')

task_id=$(echo "$resp" | grep -o '"id":"[^"]*"' | cut -d'"' -f4)
echo "Task ID: $task_id"

# 2. 轮询任务状态
curl -s "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/$task_id" \
  -H "Authorization: Bearer $ARK_API_KEY"

# 3. 当 status 为 succeeded 时，从响应的 content 中取 video_url

快速开始：文生视频

curl -s -X POST 'https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedance-1-5-pro-251215",
    "content": [
      {
        "type": "text",
        "text": "戴着帽子的老爷爷面带微笑往前走 --ratio 1:1 --fps 24 --duration 5"
      }
    ]
  }'

API 参考

POST /api/v3/contents/generations/tasks（创建任务）

Headers

• Content-Type: application/json
• Authorization: Bearer <ARK_API_KEY>

Body

字段	类型	必填	说明
model	string	是	推理接入点 ID（如 doubao-seedance-1-5-pro-251215）
content	array	是	内容列表，见下

content 元素：

• type: "text"，text: 视频描述 + 可选参数（如 --duration 5 --ratio 16:9 --camerafixed false --watermark true）。
• type: "image_url"，image_url: { "url": "https://..." }，图生视频时使用，图片需公网可访问。

响应（200）

{
  "id": "cgt-2024****-**"
}

使用返回的 id 作为任务 ID 查询状态。

GET /api/v3/contents/generations/tasks/{id}（查询任务）

Headers

• Authorization: Bearer <ARK_API_KEY>

响应中的 status

• queued：排队中
• running：生成中
• succeeded：成功，此时 content 中包含 video_url（MP4）
• failed：失败，可查看错误信息

成功时，视频地址在响应的 content.video_url 中（MP4）。视频链接约 24 小时后失效，请尽快下载。

示例

图生视频（你提供的写法）

curl -X POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedance-1-5-pro-251215",
    "content": [
      {
        "type": "text",
        "text": "无人机以极快速度穿越复杂障碍或自然奇观，带来沉浸式飞行体验  --duration 5 --camerafixed false --watermark true"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_i2v.png"
        }
      }
    ]
  }'

轮询并提取视频 URL

TASK_ID="cgt-2024****-**"   # 替换为创建任务返回的 id
while true; do
  result=$(curl -s "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/$TASK_ID" \
    -H "Authorization: Bearer $ARK_API_KEY")
  status=$(echo "$result" | grep -o '"status":"[^"]*"' | head -1 | cut -d'"' -f4)
  if [ "$status" = "succeeded" ]; then
    # 根据实际响应结构调整提取方式，例如：
    video_url=$(echo "$result" | grep -o '"video_url":"[^"]*"' | cut -d'"' -f4)
    echo "Video URL: $video_url"
    break
  fi
  if [ "$status" = "failed" ]; then
    echo "Generation failed. Check response for error details."
    break
  fi
  sleep 10
done

下载视频

拿到 video_url 后建议用 curl 下载到本地再播放（链接带签名参数，浏览器复制时容易漏掉 ? 后面的部分，会报 AuthorizationQueryParametersError）：

curl -o output.mp4 "这里粘贴完整 video_url，包含 ? 及后面全部参数"

故障排查

• 401：检查 ARK_API_KEY 是否正确且已导出。

• 404 / 模型不可用：确认该接入点已部署视频生成模型，且 model 填的是接入点 ID（如 doubao-seedance-1-5-pro-251215）。

• 图生视频失败：确保 image_url 为公网可访问的 HTTPS 地址，避免内网或 localhost。

• 等待时间长：视频生成通常需 1–3 分钟，建议轮询间隔 8–15 秒。

• 链接失效：video_url 约 24 小时后失效，请在成功后尽快下载。

• 打开链接显示 JSON 报错：若看到 AuthorizationQueryParametersError 或 “Query-string authentication version 4 requires the X-Tos-...” 说明访问时未带完整 URL（漏了 ? 及后面的鉴权参数）。请用 curl -o 视频.mp4 "完整URL" 下载到本地再播放。

• API、计费、接入点：火山方舟控制台与视频生成 API 文档

• 本技能文档/示例：GitHub Issues