Gretoken Seedance 视频生成 API 调用指南

面向 Gretoken 平台调用方。本文档说明如何调用 seedance 系列视频生成模型。调用方使用 OpenAI 风格的视频协议。

基本信息

项	值
服务域名	`https://api.gretoken.com`
鉴权	`Authorization: Bearer <Gretoken 令牌 sk-xxx>`(在站点「令牌」页面创建)
协议风格	OpenAI 视频 API(异步任务:创建 → 轮询)
支持模型	`doubao-seedance-2-0-260128`

令牌 sk-xxx 是你在 Gretoken 站点创建的平台令牌。

调用流程

视频生成是异步任务:先创建任务拿到 task_id,再轮询查询直到 status 变为 completed。

POST /v1/video/generations      → 返回 task_id (status=queued)
        ↓ 轮询
GET  /v1/video/generations/{id} → status=in_progress ... → completed (metadata.url)

1. 创建视频任务

请求

bash

curl https://api.gretoken.com/v1/video/generations \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的Gretoken令牌" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "第一人称视角果茶宣传广告，seedance牌「苹苹安安」苹果果茶限定款；全程第一视角构图，背景音乐轻快卡点，女声口播「鲜切现摇」「来一口鲜爽」。",
    "seconds": "11",
    "metadata": {
      "ratio": "16:9",
      "generate_audio": true,
      "watermark": false,
      "content": [
        {
          "type": "image_url",
          "image_url": { "url": "https://你的图床/pic1.jpg" },
          "role": "reference_image"
        },
        {
          "type": "image_url",
          "image_url": { "url": "https://你的图床/pic2.jpg" },
          "role": "reference_image"
        },
        {
          "type": "video_url",
          "video_url": { "url": "https://你的图床/video1.mp4" },
          "role": "reference_video"
        },
        {
          "type": "audio_url",
          "audio_url": { "url": "https://你的图床/audio1.mp3" },
          "role": "reference_audio"
        }
      ]
    }
  }'

请求字段

字段	类型	必填	说明
`model`	string	是	模型名,见上方支持列表
`prompt`	string	是	主提示词,自动作为文本内容注入
`seconds`	string	否	视频时长(秒),对应上游 `duration`
`metadata`	object	否	上游特有参数入口,见下

metadata 字段

字段	类型	说明
`ratio`	string	宽高比:`16:9` / `9:16` / `1:1` / `4:3` / `3:4`
`generate_audio`	bool	是否生成音频(背景音 + 口播)
`watermark`	bool	是否加水印
`content`	array	参考素材数组,见下

content 数组元素(参考图 / 视频 / 音频)

字段	说明
`type`	`image_url` / `video_url` / `audio_url` / `text`
`image_url.url` / `video_url.url` / `audio_url.url`	素材公网地址(必须上游可访问,不能是本地文件)
`role`	`reference_image` / `reference_video` / `reference_audio`

⚠️ 必填项提醒:上游要求 ratio、generate_audio、watermark 必须传(放在 metadata 里)。若遗漏,会收到错误 调试执行失败: 插件缺少必要输入参数。即使不需要音频/水印,也要显式传 "generate_audio": false、"watermark": false。

响应

json

{
  "id": "task-xxxxxxxx",
  "task_id": "task-xxxxxxxx",
  "object": "video",
  "model": "doubao-seedance-2-0-260128",
  "status": "queued",
  "created_at": 1751180000
}

记下 task_id 用于轮询。

2. 轮询查询结果

请求

bash

curl https://api.gretoken.com/v1/video/generations/task-xxxxxxxx \
  -H "Authorization: Bearer sk-你的Gretoken令牌"

进行中

json

{
  "task_id": "task-xxxxxxxx",
  "status": "IN_PROGRESS",
  "progress": "50%"
}

已完成(实测样例,字段已省略部分)

json

{
  "task_id": "task-xxxxxxxx",
  "status": "SUCCESS",
  "progress": "100%",
  "result_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/....mp4?X-Tos-...",
  "finish_time": 1782789150
}

生成的视频地址在顶层 result_url 字段。它是火山对象存储的签名链接,有效期 24 小时,过期需重新查询任务获取新链接,或提前转存。
注意:返回 JSON 中 result_url 里的 & 是 & 的 JSON 转义,程序解析后会自动还原;若手动复制到浏览器,需把 & 替换成 &。

失败

json

{
  "task_id": "task-xxxxxxxx",
  "status": "FAILURE",
  "fail_reason": "失败原因"
}

status 取值

status	含义
`QUEUED`	排队中
`IN_PROGRESS`	生成中
`SUCCESS`	完成,视频地址在 `result_url`
`FAILURE`	失败,原因在 `fail_reason`

建议轮询间隔 5~10 秒,直到 SUCCESS 或 FAILURE。

若改用 OpenAI 兼容入口 GET /v1/videos/{task_id}(见第 3 节),返回结构略有不同:status 为小写(completed/failed),视频地址在 metadata.url。两个入口取其一即可。

3. OpenAI 官方兼容入口(可选)

如果你的客户端基于 OpenAI 官方 videos API,可改用以下入口,请求/响应结构一致:

bash

# 创建
curl https://api.gretoken.com/v1/videos \
  -X POST -H "Authorization: Bearer sk-你的Gretoken令牌" \
  -H "Content-Type: application/json" \
  -d '{ "model": "doubao-seedance-2-0-260128", "prompt": "...", "seconds": "11" }'

# 查询
curl https://api.gretoken.com/v1/videos/task-xxxxxxxx \
  -H "Authorization: Bearer sk-你的Gretoken令牌"

4. 豆包(火山 Ark)原生入口(可选,推荐已有豆包代码的用户)

如果你已经有调用火山引擎 seedance 的代码或 SDK(火山官方 content 数组格式),不想改造成 Gretoken 的 prompt/seconds 风格,可以直接用这个入口——请求体与火山官方完全一致,只需把 base_url 指向 https://api.gretoken.com/doubao、把 key 换成 Gretoken 令牌即可。

端点路径与火山官方一致(/api/v3/contents/generations/tasks),仅多了 /doubao 前缀。仅支持 doubao-seedance-* 系列模型。

bash

# 创建(火山原生 content 数组格式)
curl https://api.gretoken.com/doubao/api/v3/contents/generations/tasks \
  -X POST -H "Authorization: Bearer sk-你的Gretoken令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      { "type": "text", "text": "一只猫在跳舞" },
      { "type": "image_url", "image_url": { "url": "https://你的图床/pic1.jpg" }, "role": "reference_image" }
    ],
    "ratio": "16:9",
    "duration": 11,
    "generate_audio": true,
    "watermark": false
  }'

# 查询(task_id 走 URL 路径,同火山官方)
curl https://api.gretoken.com/doubao/api/v3/contents/generations/tasks/task-xxxxxxxx \
  -H "Authorization: Bearer sk-你的Gretoken令牌"

请求体:与火山官方 content_generation.tasks.create 的 body 完全一致(model + content[] + ratio/duration/resolution/generate_audio/watermark/seed/camera_fixed 等扁平参数)。提示词放在 content 数组的 type:"text" 项里,时长用 duration(整数)。

⚠️ 与前两个入口不同点:响应仍是 Gretoken 的任务格式(不是火山原生响应)。创建返回 {id, task_id, status:"queued", ...};查询返回 {status, result_url, ...},视频地址在顶层 result_url。也就是说"请求体保持豆包原生、响应按 Gretoken 格式解析"。
generate_audio/watermark 未显式传时,网关会自动补 false(上游必填),但建议你显式传入。

5. 素材库(可复用的参考图/视频/音频)

如果你有会被反复使用的参考素材(同一张人物图、同一段参考视频/音频),可以先把它上传到 Gretoken 素材库,拿到一个稳定的 asset_id,之后在生视频时用 asset://{asset_id} 引用,免去每次都传完整 URL。

使用流程:创建素材组 → 上传素材 → 生视频时引用 → 不用了删除素材组。

5.1 创建素材组

bash

curl https://api.gretoken.com/doubao/api/saas/plugin-u/v1/exec/dance-asset-group-create \
  -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的Gretoken令牌" \
  -d '{ "groupType": "AIGC", "groupName": "我的素材组", "description": "组描述" }'
# → 返回 data.groupId,请记下,后续上传素材要用

字段	必填	说明
`groupType`	是	固定填 `AIGC`
`groupName`	是	组名,≤64 字符
`description`	否	描述,≤300 字符

5.2 上传素材

bash

curl https://api.gretoken.com/doubao/api/saas/plugin-u/v1/exec/dance-asset-create \
  -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的Gretoken令牌" \
  -d '{
    "groupId": "上一步拿到的 groupId",
    "assetName": "素材名称",
    "assetUrl": "https://你的图床/pic1.jpg",
    "assetType": "Image"
  }'
# → 返回 data 即为 asset_id,请记下

字段	必填	说明
`groupId`	是	所属素材组 ID
`assetUrl`	是	素材的公网可下载 URL(不支持 base64)
`assetType`	是	`Image` / `Video` / `Audio`
`assetName`	否	素材名,≤64 字符,仅用于检索

素材规格限制:

类型	格式	尺寸/时长	大小
Image	jpeg/png/webp/bmp/tiff/gif/heic	宽高比 [0.4, 2.5],宽高 [300, 6000]px	≤ 30 MB
Video	mp4/mov	480p 或 720p;时长 [2, 15]s;FPS [24, 60]	≤ 50 MB
Audio	wav/mp3	时长 [2, 15]s	≤ 15 MB

5.3 查询素材 / 素材组

上传素材后会异步处理,状态从 Processing 变为 ACTIVE 后才能用于生视频。可按 assetId 查询素材详情确认状态:

bash

curl https://api.gretoken.com/doubao/api/saas/plugin-u/v1/exec/dance-asset-getAsset \
  -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的Gretoken令牌" \
  -d '{ "assetId": "asset-xxxx" }'

返回素材详情,关键字段:

字段	说明
`status`	素材状态:`ACTIVE` 可用 / `Processing` 处理中
`assetUrl`	素材的存储访问 URL
`assetType` / `assetName` / `groupId`	素材基本信息

按 groupId 查询素材组详情:

bash

curl https://api.gretoken.com/doubao/api/saas/plugin-u/v1/exec/dance-asset-group-getAssetGroup \
  -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的Gretoken令牌" \
  -d '{ "groupId": "group-xxxx" }'

说明:查询为按 ID 精确查询,没有"列出全部素材/素材组"的列表接口,请自行保存创建时返回的 groupId 和 assetId。

5.4 生视频时引用素材

在第 4 节的豆包原生入口(或第 1 节的 metadata.content)里,把素材的 URL 写成 asset://{asset_id}:

bash

curl https://api.gretoken.com/doubao/api/v3/contents/generations/tasks \
  -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的Gretoken令牌" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      { "type": "text", "text": "让图片1中的人在草原上奔跑" },
      { "type": "image_url", "image_url": { "url": "asset://asset-xxxx" }, "role": "reference_image" }
    ],
    "ratio": "16:9", "duration": 11, "generate_audio": true, "watermark": false
  }'

⚠️ prompt 里必须用"图片1 / 视频1 / 音频1"这种序号指代素材,不能直接写 asset_id。 序号 = 该素材在 content 数组中按类型的出现顺序(第 1 张参考图 = 图片1,第 2 张 = 图片2,以此类推)。
❌ 错误写法:"text": "asset-xxxx 这个人物站在书房" —— asset_id 写进 prompt 会被当作普通文本,无法识别。

5.5 删除素材组

不再使用时删除,释放素材:

bash

curl https://api.gretoken.com/doubao/api/saas/plugin-u/v1/exec/dance-asset-group-deleteAssetGroup \
  -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的Gretoken令牌" \
  -d '{ "groupId": "你的 groupId" }'

6. 完整轮询示例

Python

python

import time
import requests

BASE_URL = "https://api.gretoken.com"
API_KEY = "sk-你的Gretoken令牌"

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def create_video_task() -> str:
    """创建视频任务,返回 task_id。"""
    payload = {
        "model": "doubao-seedance-2-0-260128",
        "prompt": "第一人称视角果茶宣传广告，seedance牌「苹苹安安」苹果果茶限定款。",
        "seconds": "11",
        "metadata": {
            "ratio": "16:9",
            "generate_audio": True,
            "watermark": False,
            "content": [
                {"type": "image_url", "image_url": {"url": "https://你的图床/pic1.jpg"}, "role": "reference_image"},
                {"type": "video_url", "video_url": {"url": "https://你的图床/video1.mp4"}, "role": "reference_video"},
            ],
        },
    }
    resp = requests.post(f"{BASE_URL}/v1/video/generations", headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["task_id"]


def poll_video_task(task_id: str, interval: int = 8, max_wait: int = 600) -> dict:
    """轮询任务直到完成或失败。interval 秒/次,max_wait 秒超时。"""
    deadline = time.time() + max_wait
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/v1/video/generations/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        print(f"status={status} progress={data.get('progress', '0%')}")
        if status == "SUCCESS":
            return data
        if status == "FAILURE":
            raise RuntimeError(f"任务失败: {data.get('fail_reason', '未知原因')}")
        time.sleep(interval)
    raise TimeoutError(f"任务 {task_id} 超过 {max_wait}s 未完成")


if __name__ == "__main__":
    task_id = create_video_task()
    print(f"任务已创建: {task_id}")
    result = poll_video_task(task_id)
    print("视频地址:", result.get("result_url"))

Node.js

javascript

const BASE_URL = 'https://api.gretoken.com'
const API_KEY = 'sk-你的Gretoken令牌'

const HEADERS = {
  Authorization: `Bearer ${API_KEY}`,
  'Content-Type': 'application/json',
}

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

async function createVideoTask() {
  const payload = {
    model: 'doubao-seedance-2-0-260128',
    prompt: '第一人称视角果茶宣传广告，seedance牌「苹苹安安」苹果果茶限定款。',
    seconds: '11',
    metadata: {
      ratio: '16:9',
      generate_audio: true,
      watermark: false,
      content: [
        { type: 'image_url', image_url: { url: 'https://你的图床/pic1.jpg' }, role: 'reference_image' },
        { type: 'video_url', video_url: { url: 'https://你的图床/video1.mp4' }, role: 'reference_video' },
      ],
    },
  }
  const resp = await fetch(`${BASE_URL}/v1/video/generations`, {
    method: 'POST',
    headers: HEADERS,
    body: JSON.stringify(payload),
  })
  if (!resp.ok) throw new Error(`创建失败: ${resp.status} ${await resp.text()}`)
  return (await resp.json()).task_id
}

async function pollVideoTask(taskId, { interval = 8000, maxWait = 600000 } = {}) {
  const deadline = Date.now() + maxWait
  while (Date.now() < deadline) {
    const resp = await fetch(`${BASE_URL}/v1/video/generations/${taskId}`, { headers: HEADERS })
    if (!resp.ok) throw new Error(`查询失败: ${resp.status} ${await resp.text()}`)
    const data = await resp.json()
    console.log(`status=${data.status} progress=${data.progress ?? '0%'}`)
    if (data.status === 'SUCCESS') return data
    if (data.status === 'FAILURE') throw new Error(`任务失败: ${data.fail_reason ?? '未知原因'}`)
    await sleep(interval)
  }
  throw new Error(`任务 ${taskId} 超过 ${maxWait}ms 未完成`)
}

;(async () => {
  const taskId = await createVideoTask()
  console.log(`任务已创建: ${taskId}`)
  const result = await pollVideoTask(taskId)
  console.log('视频地址:', result.result_url)
})()

常见问题

Q: 参考素材能传本地文件吗? 不能。url 必须是上游可公网访问的地址(如对象存储 / 图床)。

Q: 计费怎么算? 按生成视频的 token 量计费(分辨率 × 帧率 × 时长相关)。

Gretoken Seedance 视频生成 API 调用指南 ​

基本信息 ​

调用流程 ​

1. 创建视频任务 ​

2. 轮询查询结果 ​

3. OpenAI 官方兼容入口(可选) ​

4. 豆包(火山 Ark)原生入口(可选,推荐已有豆包代码的用户) ​

5. 素材库(可复用的参考图/视频/音频) ​

5.1 创建素材组 ​

5.2 上传素材 ​

5.3 查询素材 / 素材组 ​

5.4 生视频时引用素材 ​

5.5 删除素材组 ​

6. 完整轮询示例 ​

Python ​

Node.js ​

常见问题 ​

Gretoken Seedance 视频生成 API 调用指南

基本信息

调用流程

1. 创建视频任务

2. 轮询查询结果

3. OpenAI 官方兼容入口(可选)

4. 豆包(火山 Ark)原生入口(可选,推荐已有豆包代码的用户)

5. 素材库(可复用的参考图/视频/音频)

5.1 创建素材组

5.2 上传素材

5.3 查询素材 / 素材组

5.4 生视频时引用素材

5.5 删除素材组

6. 完整轮询示例

Python

Node.js

常见问题