快速开始

火山国内线已上线

这一页用最短的路径跑通第一次调用：创建任务、查询状态、下载视频。示例生成一段 4 秒、480p 的 Seedance 2.0 视频。

开始前请先按获取令牌与选择分组拿到 API 密钥，并在终端里设置好：

export API_KEY="sk-YOUR_API_KEY"

三种示例各自的前提：

cURL：解析 JSON 用到 jq，没有的话先安装。
Python：使用火山官方 SDK，先 pip install volcengine-ark-runtime。
Node.js：18 及以上版本，自带 fetch，不需要装任何依赖。

第 1 步:创建任务

向 POST https://api.boyueasi.com/api/v3/contents/generations/tasks 发请求，body 里写模型、提示词和规格：

#!/usr/bin/env bash
# 创建视频任务。API_KEY 是你的 API 密钥,只放在环境变量里,不要写进代码或提交到仓库
curl -sS https://api.boyueasi.com/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "一只橘猫在窗台上伸懒腰，阳光透过窗帘"}
    ],
    "resolution": "480p",
    "duration": 4,
    "ratio": "16:9"
  }'

import os

from volcenginesdkarkruntime import Ark

# 火山官方 SDK:base_url 指向本站即可。API_KEY 是你的 API 密钥,只放在环境变量里
client = Ark(base_url="https://api.boyueasi.com/api/v3", api_key=os.environ["API_KEY"])

task = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[{"type": "text", "text": "一只橘猫在窗台上伸懒腰，阳光透过窗帘"}],
    resolution="480p",
    duration=4,
    ratio="16:9",
)
print(task.id)  # 保存好任务号,下一步查询要用

// 创建视频任务。Node.js 18 及以上自带 fetch,无需安装依赖
// API_KEY 是你的 API 密钥,只放在环境变量里,不要写进代码或提交到仓库
const res = await fetch("https://api.boyueasi.com/api/v3/contents/generations/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "doubao-seedance-2-0-260128",
    content: [{ type: "text", text: "一只橘猫在窗台上伸懒腰，阳光透过窗帘" }],
    resolution: "480p",
    duration: 4,
    ratio: "16:9",
  }),
});
const task = await res.json();
if (!res.ok) throw new Error(`创建失败 ${res.status}: ${JSON.stringify(task)}`);
console.log(task.id); // 保存好任务号,下一步查询要用

请求成功后立刻返回任务号，此时视频还没生成：

{
  "content": {},
  "created_at": 1793358284,
  "id": "task_xxxxxxxx",
  "model": "doubao-seedance-2-0-260128",
  "status": "queued"
}

把 id 保存下来，下一步要用它查询。返回里还可能出现别的字段，不用处理，忽略即可。任务号丢了也不用慌，可以到控制台「常规 → 任务日志」里找回。

第 2 步:查询任务

用任务号轮询 GET /api/v3/contents/generations/tasks/{task_id}，直到 status 变成 succeeded（成功）或 failed（失败）。先把上一步的任务号放进环境变量：

export TASK_ID="task_xxxxxxxx"

#!/usr/bin/env bash
# 轮询任务直到结束。TASK_ID 取自上一步返回的 id;解析 JSON 需要安装 jq
while true; do
  RESP=$(curl -sS "https://api.boyueasi.com/api/v3/contents/generations/tasks/$TASK_ID" \
    -H "Authorization: Bearer $API_KEY")
  STATUS=$(echo "$RESP" | jq -r '.status')
  echo "状态: $STATUS"
  case "$STATUS" in
    succeeded)
      # 成功:content.video_url 就是视频直链,24 小时内有效
      echo "$RESP" | jq -r '.content.video_url'
      break ;;
    failed | expired | cancelled | null)
      # 失败、过期,或返回的不是任务(例如令牌错误):打印原文后退出
      echo "$RESP"
      break ;;
  esac
  sleep 15
done

import os
import time

from volcenginesdkarkruntime import Ark

client = Ark(base_url="https://api.boyueasi.com/api/v3", api_key=os.environ["API_KEY"])
task_id = os.environ["TASK_ID"]  # 上一步返回的 id

while True:
    task = client.content_generation.tasks.get(task_id=task_id)
    print("状态:", task.status)
    if task.status == "succeeded":
        # 成功:content.video_url 就是视频直链,24 小时内有效
        print(task.content.video_url)
        break
    if task.status in ("failed", "expired", "cancelled"):
        print(task.error)
        break
    time.sleep(15)

// 轮询任务直到结束。TASK_ID 取自上一步返回的 id
const url = `https://api.boyueasi.com/api/v3/contents/generations/tasks/${process.env.TASK_ID}`;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

while (true) {
  const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.API_KEY}` } });
  const task = await res.json();
  if (!res.ok) throw new Error(`查询失败 ${res.status}: ${JSON.stringify(task)}`);
  console.log("状态:", task.status);
  if (task.status === "succeeded") {
    // 成功:content.video_url 就是视频直链,24 小时内有效
    console.log(task.content.video_url);
    break;
  }
  if (["failed", "expired", "cancelled"].includes(task.status)) {
    console.log(JSON.stringify(task));
    break;
  }
  await sleep(15000);
}

状态按 queued（排队）→ running（生成中）→ succeeded / failed 流转，此外还可能出现 expired（任务超时）。建议每 10–15 秒查询一次，不要高频轮询。

我们实测的出片耗时：Seedance 2.0 / 480p / 4 秒约 2.5 到 4.5 分钟，Seedance 2.5 同规格约 3 分多钟。成功后的返回长这样（video_url 里的签名参数已省略）：

{
  "content": {
    "video_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/….mp4?…"
  },
  "created_at": 1793358297,
  "duration": 4,
  "id": "task_xxxxxxxx",
  "model": "doubao-seedance-2-0-260128",
  "ratio": "16:9",
  "resolution": "480p",
  "status": "succeeded",
  "updated_at": 1793358439,
  "usage": {
    "completion_tokens": 40594,
    "total_tokens": 40594
  }
}

各字段的含义、失败时的样子，见查询任务与获取视频。

第 3 步:下载视频

任务成功后，content.video_url 就是视频的下载直链。把它放进环境变量再下载：

export VIDEO_URL="https://…（上一步拿到的 video_url）"

#!/usr/bin/env bash
# 下载视频。VIDEO_URL 是上一步取到的 content.video_url,链接 24 小时内有效,请及时转存
# 这是带签名的直链,不需要也不要附带 API 密钥
curl -sS -L -o seedance.mp4 "$VIDEO_URL"
echo "已保存 seedance.mp4"

import os
import urllib.request

# VIDEO_URL 是上一步取到的 content.video_url,链接 24 小时内有效,请及时转存
# 这是带签名的直链,不需要也不要附带 API 密钥
urllib.request.urlretrieve(os.environ["VIDEO_URL"], "seedance.mp4")
print("已保存 seedance.mp4")

import { writeFile } from "node:fs/promises";

// VIDEO_URL 是上一步取到的 content.video_url,链接 24 小时内有效,请及时转存
// 这是带签名的直链,不需要也不要附带 API 密钥
const res = await fetch(process.env.VIDEO_URL);
if (!res.ok) throw new Error(`下载失败 ${res.status}`);
await writeFile("seedance.mp4", Buffer.from(await res.arrayBuffer()));
console.log("已保存 seedance.mp4");

费用说明

这个示例（Seedance 2.0 / 480p / 4 秒）大约花 ¥1.59。计费按视频的输出 token 数，创建任务时先按估算预扣，完成后按实际用量多退少补，任务失败会自动全额退款。我们用同样规格实测，预扣的 40594 token 与实际用量一致。

换成其他分辨率、时长或模型，费用怎么算见价格与计费。

路径前缀与官方 SDK

路径前缀：带前缀的 /doubao/api/v3/... 与上面的 /api/v3/... 等价，行为和返回完全一致，之前已经在用前缀地址的接入方可以继续使用。

官方 SDK：本站兼容火山方舟（Volcengine Ark）协议，火山官方 SDK 的基础用法可以直接用（个别参数与 SDK 方法的用法见错误与排错里的「使用提示」），只需要把 base_url 指向 https://api.boyueasi.com/api/v3，api_key 换成本站的 API 密钥。上面的 Python 示例就是这样写的。我们用火山官方 Python SDK（5.0.56）实测过：用关键字参数调用 tasks.create 创建、用 tasks.get(task_id=...) 轮询都能正常使用，Seedance 2.5 / 480p / 4 秒的任务 3 分 19 秒成功出片。