视频生成
汇总生成视频的 API 的用法(提交、查询进度、获取文件)、各模型能指定的项目和取值、价格的计算方式、能获取文件的期限和错误。
生成视频需要时间,所以一次调用不会直接返回视频。视频按任务(提交后,等生成结束再取结果的处理)来用,分下面 3 步。
| 步骤 | 方法和路径 | 内容 |
|---|---|---|
| 1. 提交 | POST /v1/videos | 发送模型、提示词(对想要的视频的描述)、时长、分辨率。返回任务的 ID |
| 2. 查询进度 | GET /v1/videos/{任务 ID} | 隔一段时间查询一次,直到 status 变成 completed(完成)或 failed(失败) |
| 3. 获取文件 | GET /v1/videos/{任务 ID}/content | 以 MP4 文件获取生成好的视频 |
接入地址和发送密钥的方法,与其他 OpenAI 格式的端点相同(https://token.echohub.io/v1、Authorization: Bearer 密钥)。
正在提供的模型列在模型一览。
模型
| 模型 ID | 提供方 | 时长 | 分辨率 | 可用的输入 |
|---|---|---|---|---|
MiniMax-H3 | MiniMax | [ ] | 768P、2K | [ ] |
doubao-seedance-2-0-260128(Seedance 2.0) | ByteDance(火山引擎) | [ ] | 480p、720p、1080p、4k | [ ] |
- 价格(每秒或每 100 万 token 的单价)列在模型一览的各模型页面
- 处理地区写在模型一览的各模型页面。提示词,以及用作参考的图片、视频、音频,会传给在该地区处理的提供方 API(数据处理)
- 能指定的项目和取值因模型而异。见下面的「各模型的参数」
调用示例
用 MiniMax-H3 生成 6 秒、768P 的视频,保存为 video.mp4 的示例。密钥先放进环境变量 ECHO_API_KEY(快速开始)。
# 1. 提交。记下返回的 id
curl "https://token.echohub.io/v1/videos" \
-H "Authorization: Bearer $ECHO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-H3",
"prompt": "夕方の海辺を、柴犬がゆっくり歩いている",
"seconds": 6,
"resolution": "768P"
}'
# 2. 查询进度。VIDEO_ID 填第 1 步返回的 id
VIDEO_ID="task_..."
curl "https://token.echohub.io/v1/videos/$VIDEO_ID" \
-H "Authorization: Bearer $ECHO_API_KEY"
# 3. status 变成 completed 后,获取文件
curl -o video.mp4 "https://token.echohub.io/v1/videos/$VIDEO_ID/content" \
-H "Authorization: Bearer $ECHO_API_KEY"# 创建并启用虚拟环境
python3 -m venv .venv && source .venv/bin/activate
pip install requestsimport os
import time
import requests
BASE = "https://token.echohub.io/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['ECHO_API_KEY']}"}
def check(res):
# 出错时显示 HTTP 状态码和错误正文,然后结束
if not res.ok:
raise SystemExit(f"HTTP {res.status_code}: {res.text}")
return res
# 1. 提交
video = check(requests.post(f"{BASE}/videos", headers=HEADERS, json={
"model": "MiniMax-H3",
"prompt": "夕方の海辺を、柴犬がゆっくり歩いている",
"seconds": 6,
"resolution": "768P",
})).json()
print("已提交:", video["id"])
# 2. 每 15 秒查询一次进度,直到完成或失败
while video["status"] in ("queued", "in_progress"):
time.sleep(15)
video = check(requests.get(f"{BASE}/videos/{video['id']}", headers=HEADERS)).json()
print(video["status"], video["progress"])
if video["status"] != "completed":
raise SystemExit(f"生成失败: {video.get('error')}")
# 3. 获取文件
res = check(requests.get(f"{BASE}/videos/{video['id']}/content", headers=HEADERS))
with open("video.mp4", "wb") as f:
f.write(res.content)
print("已保存到 video.mp4")保存为 video.py,用 python video.py 运行。
import { writeFile } from "node:fs/promises";
const BASE = "https://token.echohub.io/v1";
const auth = { Authorization: `Bearer ${process.env.ECHO_API_KEY}` };
// 出错时显示 HTTP 状态码和错误正文,然后结束
async function check(res) {
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
return res;
}
// 1. 提交
const submitted = await check(
await fetch(`${BASE}/videos`, {
method: "POST",
headers: { ...auth, "Content-Type": "application/json" },
body: JSON.stringify({
model: "MiniMax-H3",
prompt: "夕方の海辺を、柴犬がゆっくり歩いている",
seconds: 6,
resolution: "768P",
}),
}),
);
let video = await submitted.json();
console.log("已提交:", video.id);
// 2. 每 15 秒查询一次进度,直到完成或失败
while (video.status === "queued" || video.status === "in_progress") {
await new Promise((resolve) => setTimeout(resolve, 15_000));
const res = await check(await fetch(`${BASE}/videos/${video.id}`, { headers: auth }));
video = await res.json();
console.log(video.status, video.progress);
}
if (video.status !== "completed") throw new Error(`生成失败: ${JSON.stringify(video.error)}`);
// 3. 获取文件
const res = await check(await fetch(`${BASE}/videos/${video.id}/content`, { headers: auth }));
await writeFile("video.mp4", Buffer.from(await res.arrayBuffer()));
console.log("已保存到 video.mp4");需要 Node.js 18 以上,不用另外安装包。保存为 video.mjs,用 node video.mjs 运行。
1. 提交
向 POST /v1/videos 以 JSON 发送下面的项目。
| 参数 | 必填 | 说明 |
|---|---|---|
model | 必填 | 模型 ID |
prompt | MiniMax-H3 必填 | 对想要的视频的描述 |
seconds | 视频时长(秒)。整数 | |
resolution | 分辨率(MiniMax-H3)。Seedance 2.0 写在 metadata.resolution 里 | |
images | 图片 URL 的数组。用作首帧和尾帧(视频的第一帧和最后一帧画面)(MiniMax-H3) | |
input_reference | 用作首帧的图片 URL(MiniMax-H3) | |
metadata | 各模型的附加设置(Seedance 2.0 的分辨率、宽高比、有无声音、参考素材等)。JSON 对象 |
- 图片、视频、音频用提供方的服务器能访问到的公开 URL 传入
- 每个参数写在哪里由模型决定。写在「各模型的参数」以外位置的值,可能不会被使用。像时长、分辨率、图片写在 Seedance 2.0 不读的位置这样,会让视频和指定的不一样、或和价格对不上的写法,Echo 不接受(HTTP 400,「会被拒绝的写法」)
- 请不要用 OpenAI 格式的
size(1280x720等)。它不能用来指定宽高比,有的模型会把它当作分辨率,有的模型会报错 - MiniMax-H3 也可以把图片文件直接放进请求里发送:用表单格式(
multipart/form-data),在input_reference里只放 1 张(最大 20 MB)。表单格式下,metadata要写成 JSON 字符串。Seedance 2.0 不接受文件(HTTP 400),图片请用 URL 传入
受理提交后,以 HTTP 200 返回下面这样的 JSON。
{"id":"task_3H0YkK1PMgAiKglDcHbxqtL8WC7C247u","object":"video","model":"MiniMax-H3","status":"queued","progress":0,"created_at":1790796502}提交时会从余额中扣除估算的价格(见下面的「价格」)。
2. 查询进度
GET /v1/videos/{任务 ID} 返回任务的状态。
| 项目 | 内容 |
|---|---|
id | 任务 ID(以 task_ 开头的字符串) |
object | 总是 video |
model | 模型 ID |
status | 状态(见下表) |
progress | 0–100 的数。按状态定好的参考值(刚提交时是 0,排队中 10(Seedance 2.0)或 30(MiniMax-H3),生成中 50,结束后 100),不表示实际进度 |
created_at | 提交时间(从 1970-01-01 起的秒数) |
completed_at | 完成时间。只在完成时出现 |
error | 失败的原因(code 和 message)。只在提供方返回了原因时出现(Seedance 2.0)。MiniMax-H3 不会出现 |
status | 含义 |
|---|---|
queued | 在提供方排队 |
in_progress | 正在生成 |
completed | 已完成。可以获取文件 |
failed | 已失败。价格全额退还 |
- Echo 的服务器每 15–30 秒向提供方查询一次进度。所以提供方生成结束后,可能要 30 秒左右才变成
completed。间隔有时也会超过 30 秒 - 请隔 10–15 秒左右查询一次进度。Echo 没有主动通知完成的机制
- 提交后 24 小时仍未完成的任务,会被设为
failed并全额退款。Seedance 2.0 提交后 23 小时仍未完成的任务会被提供方取消,这时变为failed并全额退款
3. 获取文件
GET /v1/videos/{任务 ID}/content 以 MP4 文件(Content-Type: video/mp4)返回生成好的视频。也可以用 HEAD 只确认文件大小,或用 Range 请求头只获取一部分。
- Echo 不保存生成的视频。每次调用这个路径,都会从提供方取来文件,原样传给你
- 只有在提供方保留文件期间才能获取。超过期限会返回 HTTP 410。完成后请尽快获取并保存
| 模型 | 提供方保留文件的期限 |
|---|---|
| Seedance 2.0 | [ ] |
| MiniMax-H3 | [ ] |
各模型的参数
MiniMax-H3
| 项目 | 写在哪里 | 取值 |
|---|---|---|
| 时长 | seconds | [ ] 的整数。省略时为 5 |
| 分辨率 | resolution | 768P 或 2K。省略时为 768P |
| 宽高比 | metadata.ratio | 16:9、9:16、1:1、4:3、3:4、21:9、adaptive(跟随输入的图片或视频)。省略时,传了图片或视频就是 adaptive,没传就是 16:9。图片和视频都没传时不能用 adaptive |
| 首帧和尾帧 | images | 1–2 个图片 URL。第 1 个是首帧,第 2 个是尾帧。写在 input_reference 里的图片是首帧 |
| 参考图片 | metadata.content | 按下面示例的格式,最多 9 张 |
| 参考视频 | metadata.reference_video | URL 的数组。最多 3 个 |
- 指定帧(
images、input_reference)和参考(图片、视频)不能同时使用 - 不能使用参考音频(HTTP 400)
- 不写
prompt会返回 HTTP 400
使用参考图片的示例。
{
"model": "MiniMax-H3",
"prompt": "画像のマグカップが、木のテーブルの上でゆっくり回っている",
"seconds": 5,
"resolution": "768P",
"metadata": {
"content": [
{"type": "image_url", "image_url": {"url": "https://example.com/mug.png"}, "role": "reference_image"}
]
}
}| 种类 | 能用的文件(提供方的规格) |
|---|---|
| 图片 | JPG、PNG、WEBP、HEIC、HEIF。每张最大 30 MB。宽和高 256–5760 像素,宽÷高 0.4–2.5 |
| 视频 | MP4、MOV。每个最大 50 MB。每个 2–15 秒,合计最多 15 秒 |
| 整个请求 | 最大 64 MB。大文件请用 URL 传入 |
Seedance 2.0(doubao-seedance-2-0-260128)
| 项目 | 写在哪里 | 取值 |
|---|---|---|
| 时长 | seconds | [ ] 的整数 |
| 分辨率 | metadata.resolution | 480p、720p、1080p、4k。省略时为 720p |
| 宽高比 | metadata.ratio | 16:9、4:3、1:1、3:4、9:16、21:9、adaptive。省略时为 adaptive(由模型根据提示词或图片选择) |
| 声音 | metadata.generate_audio | true(有声)或 false(无声)。省略时为 true |
| 首帧、首尾帧、参考 | metadata.content | 按下面示例的格式。用 role 决定用法 |
| 在提供方等待的时间上限 | metadata.execution_expires_after | 3600–82800 的整数(秒)。省略时 Echo 填 82800(23 小时)。在这个时间内没完成的任务由提供方取消,全额退款 |
- 时长写在
seconds,分辨率写在metadata.resolution。顶层的resolution、duration、input_reference,以及写在提示词后面的--dur 5这类参数,在 Seedance 2.0 里不能用(HTTP 400,「会被拒绝的写法」) seconds和metadata.resolution请不要省略。省略时,估算的价格按 15 秒、1080p 计算,可能因余额不足而提交不了(生成后按实际用量重新计算)- 首帧、首尾帧、参考(图片、视频、音频)这 3 种不能同时使用(提供方的规格)
- 图片、视频、音频用 URL 传入。用表单格式附带文件时返回 HTTP 400
- 含有真人面孔的图片或视频不能用作参考(提供方的规格)
指定首帧和尾帧的示例。
{
"model": "doubao-seedance-2-0-260128",
"prompt": "つぼみがゆっくり開いて花が咲く",
"seconds": 5,
"metadata": {
"resolution": "720p",
"content": [
{"type": "image_url", "image_url": {"url": "https://example.com/first.png"}, "role": "first_frame"},
{"type": "image_url", "image_url": {"url": "https://example.com/last.png"}, "role": "last_frame"}
]
}
}role | 用法 | 数量 |
|---|---|---|
first_frame | 首帧(type 是 image_url)。只用这 1 张时,生成以这张图片开头的视频 | 1 张 |
last_frame | 尾帧(type 是 image_url)。与 first_frame 一起使用 | 1 张 |
reference_image | 参考图片(type 是 image_url) | 1–9 张 |
reference_video | 参考视频(type 是 video_url,URL 写在 video_url.url) | 最多 3 个 |
reference_audio | 参考音频(type 是 audio_url,URL 写在 audio_url.url)。要与图片或视频一起使用 | 最多 3 个 |
| 种类 | 能用的文件(提供方的规格) |
|---|---|
| 图片 | JPEG、PNG、WEBP、BMP、TIFF、GIF、HEIC、HEIF。每张小于 30 MB。宽和高 300–6000 像素,宽÷高 0.4–2.5 |
| 视频 | MP4、MOV。每个最大 200 MB。每个 2–15 秒,合计最多 15 秒 |
| 音频 | WAV、MP3。每个最大 15 MB。每个 2–15 秒,合计最多 15 秒 |
| 整个请求 | 最大 64 MB |
会被拒绝的写法
下面这些写法会让生成的视频和指定的不一样,或者和价格的计算对不上,Echo 在提交时就拒绝:HTTP 400,error.code 是 invalid_request,message 里写着正确的写法。不收费。
| 写法 | 模型 | 应改为 | message |
|---|---|---|---|
时长写在 duration 或 metadata.duration(没写 seconds,或和 seconds 的值不同) | Seedance 2.0 | 写在 seconds | Write the video length in seconds, for example "seconds": 5. This model does not read duration。和 seconds 的值不同时是 duration does not match seconds. Write the video length only in seconds |
seconds 写了不是整数的值(5.5 等) | Seedance 2.0 | 整数(5 或 "5") | seconds must be a whole number of seconds, for example "seconds": 5 |
时长用 frames 或 metadata.frames(帧数)指定 | Seedance 2.0 | 写在 seconds | This model does not read frames. Write the video length in seconds, for example "seconds": 5 |
分辨率写在顶层的 resolution | Seedance 2.0 | 写在 metadata.resolution | Write the resolution in metadata.resolution, for example "metadata": {"resolution": "720p"}. This model does not read the top-level resolution |
只写 size,没写 metadata.resolution | Seedance 2.0 | 写在 metadata.resolution | Write the resolution in metadata.resolution, for example "metadata": {"resolution": "720p"}. This model does not read size |
metadata.resolution 写了 480p、720p、1080p、4k 以外的值(720P 等) | Seedance 2.0 | 这 4 个之一 | metadata.resolution must be one of 480p, 720p, 1080p, 4k |
在提示词后面写时长、分辨率的参数(--dur 5、--rs 720p 等) | Seedance 2.0 | 写在 seconds 和 metadata.resolution | Write the video length in seconds and the resolution in metadata.resolution. This model does not accept --dur in the prompt |
图片写在 input_reference、image、images | Seedance 2.0 | 写在 metadata.content(首帧的 role 写 first_frame) | This model does not read input_reference. Put images in metadata.content; for the first frame use {"type": "image_url", "image_url": {"url": "<image URL>"}, "role": "first_frame"} |
| 用表单格式附带文件 | Seedance 2.0 | 图片的 URL 写在 metadata.content | This model does not accept uploaded files. Pass images as URLs in metadata.content; for the first frame use {"type": "image_url", "image_url": {"url": "<image URL>"}, "role": "first_frame"} |
metadata.execution_expires_after 写了 3600–82800 以外的值 | Seedance 2.0 | 3600–82800 的整数(不写时 Echo 填 82800) | metadata.execution_expires_after must be a whole number of seconds from 3600 to 82800 (1 to 23 hours) |
附带参考音频(metadata.reference_audio、metadata.content 里的 audio_url) | MiniMax-H3 | 不能使用 | Reference audio is not supported for this model. Remove audio_url and reference_audio from the request |
用 POST /v1/responses 或 POST /v1/tasks/… 调用视频模型 | 两者 | 用 POST /v1/videos 提交 | Video generation requests must be sent to POST /v1/videos |
message中duration、frames、input_reference、--dur的部分,会换成实际写的项目名(metadata.duration、image、--rs等)- 写法正确的请求,Echo 只给 Seedance 2.0 补上
metadata.execution_expires_after(在提供方等待的时间上限),其余项目按写的原样传到提供方
价格
视频的价格按每秒(MiniMax-H3)或每 100 万 token(Seedance 2.0)的单价计算。token 是提供方计算视频量的单位。单价列在模型一览的各模型页面。
任务的价格按下面的顺序确定。
- 提交时,从余额中扣除估算的价格。估算的价格按请求的时长和分辨率(MiniMax-H3 还包括参考图片的张数和参考视频)计算。余额或密钥的使用上限不够时,不能提交(HTTP 403)
- 生成结束后,按提供方报告的实际用量重新计算价格,退还差额或追加扣除
- 生成失败的任务、提交后 24 小时(Seedance 2.0 是 23 小时)仍未完成的任务,全额退款
| 模型 | 重新计算时用的量 |
|---|---|
| Seedance 2.0 | 实际的 token 数。有没有参考视频,每 100 万 token 的单价不同 |
| MiniMax-H3 | 实际的时长、参考图片的张数、参考视频的秒数。参考视频在提交时按 15 秒计算 |
- 在提交时就被拒绝的请求(取值错误、提供方不受理等)不收费
- 追加扣除的部分,余额不够也会扣除。余额变成负数的部分,从下一次充值中扣除(价格与充值)
- 控制台的「呼び出し履歴」(调用记录)里,显示每个任务的状态和金额(API 密钥与使用情况)
错误
错误正文的格式与其他 OpenAI 格式的端点相同(错误与处理)。视频生成特有的错误如下。
| 情况 | HTTP 状态码和 error.code | message | 处理 |
|---|---|---|---|
| 时长、分辨率等取值在这个模型里不能用 | 400,invalid_request 或空字符串 | 写明原因的英文(例:MiniMax-H3 duration must be an integer between 4 and 15 seconds) | 看「各模型的参数」修改 |
用了会被拒绝的写法(Seedance 2.0 的时长写在 duration、用表单格式附带文件、用 POST /v1/responses 调用视频模型等) | 400,invalid_request | 写着正确写法的英文(例:Write the video length in seconds, for example "seconds": 5. This model does not read duration) | 按「会被拒绝的写法」修改 |
| 提供方不受理请求 | 400,upstream_error | The model service rejected the request, check the parameters and try again | 确认取值和图片等的 URL |
| 任务 ID 不对,或是别的账号的任务 | 400(获取文件时是 404),task_not_found | Task not found | 确认 ID |
| 完成前就获取文件 | 400,task_not_ready | The video is not ready yet | 变成 completed 后再获取 |
| 获取失败任务的文件 | 400,task_failed | The video generation failed | 重新提交 |
| 超过了提供方保留文件的期限 | 410,artifact_gone | Artifact content is no longer available | 无法获取。请重新提交 |
| 余额不足 | 403,insufficient_quota | Insufficient balance | 充值 |
| 密钥的使用上限不够 | 403,insufficient_quota | This API key has reached its spending limit | 提高使用上限(上限与速率限制) |
| 模型 ID 不对 | 503,model_not_found | The model {模型 ID} does not exist or is not available | 确认模型 ID |
在提交时返回的错误不收费。
使用 OpenAI SDK 时
- OpenAI 的 SDK(Python、Node.js)也有视频的函数(
videos.create等),但 SDK 里这些函数带有「Sora 的 API 计划于 2026-09-24 停止」的弃用标记。本页的示例不用 SDK,直接用 HTTP 调用 - SDK 的
videos.create以表单格式(multipart/form-data)发送请求。在这种格式下,metadata不写成 JSON 字符串就不会传到提供方(Python 的例子:extra_body={"metadata": json.dumps({"resolution": "720p"})})
信息来源
| 内容 | 来源 | 确认日期 |
|---|---|---|
3 个步骤和响应、状态和 progress、获取文件(含 HEAD、Range)、错误正文、价格的扣除、重新计算和退款、Seedance 2.0 的 metadata.resolution 和 metadata.content(role)传到提供方、Seedance 2.0 不接受表单格式的文件、表单格式下的 metadata、SDK 的 videos.create 下的 metadata | Echo 验证环境中的实测。使用与正式环境相同的中转设置,并用返回测试响应的服务器代替提供方的 API | 2026-10-02 |
| 查询进度的间隔(从提交到第一次查询 19–36 秒,之后每 30 秒) | Echo 验证环境中的实测(同上) | 2026-10-01 |
| 24 小时仍未完成的任务设为失败并退款 | Echo 中转服务器的设置(2026-10-01 时) | 2026-10-01 |
会被拒绝的写法和报错,Echo 把 Seedance 2.0 的 metadata.execution_expires_after 设为 82800 | Echo 验证环境中的实测(同上) | 2026-10-02 |
Seedance 2.0 的 metadata.execution_expires_after 的范围(3600–259200 秒,省略时 172800 秒)、写在提示词后面的 --dur 等参数 | https://www.volcengine.com/docs/82379/1520757 | 2026-10-02 |
| MiniMax-H3 的时长、分辨率、宽高比、输入的组合和文件条件,文件 URL 有期限 | https://platform.minimax.io/docs/api-reference/video-generation-v2-create 、https://platform.minimax.io/docs/api-reference/video-generation-v2-query | 2026-10-01 |
Seedance 2.0 的时长、分辨率、宽高比、声音、role 和文件条件,文件保留 24 小时,真人面孔不能用作参考 | https://www.volcengine.com/docs/82379/1520757 、https://www.volcengine.com/docs/82379/1521309 | 2026-10-01 |
| OpenAI SDK 的视频函数已弃用 | https://github.com/openai/openai-python (3.23.0)、https://github.com/openai/openai-node (7.27.0) | 2026-10-02 |