文档视频生成

视频生成

汇总生成视频的 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-H3MiniMax[ ]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(快速开始)。

bash
# 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"

1. 提交

向 POST /v1/videos 以 JSON 发送下面的项目。

参数必填说明
model必填模型 ID
promptMiniMax-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。

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状态(见下表)
progress0–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
分辨率resolution768P 或 2K。省略时为 768P
宽高比metadata.ratio16:9、9:16、1:1、4:3、3:4、21:9、adaptive(跟随输入的图片或视频)。省略时,传了图片或视频就是 adaptive,没传就是 16:9。图片和视频都没传时不能用 adaptive
首帧和尾帧images1–2 个图片 URL。第 1 个是首帧,第 2 个是尾帧。写在 input_reference 里的图片是首帧
参考图片metadata.content按下面示例的格式,最多 9 张
参考视频metadata.reference_videoURL 的数组。最多 3 个
  • 指定帧(images、input_reference)和参考(图片、视频)不能同时使用
  • 不能使用参考音频(HTTP 400)
  • 不写 prompt 会返回 HTTP 400

使用参考图片的示例。

JSON
{
  "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.resolution480p、720p、1080p、4k。省略时为 720p
宽高比metadata.ratio16:9、4:3、1:1、3:4、9:16、21:9、adaptive。省略时为 adaptive(由模型根据提示词或图片选择)
声音metadata.generate_audiotrue(有声)或 false(无声)。省略时为 true
首帧、首尾帧、参考metadata.content按下面示例的格式。用 role 决定用法
在提供方等待的时间上限metadata.execution_expires_after3600–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
  • 含有真人面孔的图片或视频不能用作参考(提供方的规格)

指定首帧和尾帧的示例。

JSON
{
  "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写在 secondsWrite 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写在 secondsThis model does not read frames. Write the video length in seconds, for example "seconds": 5
分辨率写在顶层的 resolutionSeedance 2.0写在 metadata.resolutionWrite the resolution in metadata.resolution, for example "metadata": {"resolution": "720p"}. This model does not read the top-level resolution
只写 size,没写 metadata.resolutionSeedance 2.0写在 metadata.resolutionWrite 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.resolutionWrite the video length in seconds and the resolution in metadata.resolution. This model does not accept --dur in the prompt
图片写在 input_reference、image、imagesSeedance 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.contentThis 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.03600–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 是提供方计算视频量的单位。单价列在模型一览的各模型页面。

任务的价格按下面的顺序确定。

  1. 提交时,从余额中扣除估算的价格。估算的价格按请求的时长和分辨率(MiniMax-H3 还包括参考图片的张数和参考视频)计算。余额或密钥的使用上限不够时,不能提交(HTTP 403)
  2. 生成结束后,按提供方报告的实际用量重新计算价格,退还差额或追加扣除
  3. 生成失败的任务、提交后 24 小时(Seedance 2.0 是 23 小时)仍未完成的任务,全额退款
模型重新计算时用的量
Seedance 2.0实际的 token 数。有没有参考视频,每 100 万 token 的单价不同
MiniMax-H3实际的时长、参考图片的张数、参考视频的秒数。参考视频在提交时按 15 秒计算
  • 在提交时就被拒绝的请求(取值错误、提供方不受理等)不收费
  • 追加扣除的部分,余额不够也会扣除。余额变成负数的部分,从下一次充值中扣除(价格与充值)
  • 控制台的「呼び出し履歴」(调用记录)里,显示每个任务的状态和金额(API 密钥与使用情况)

错误

错误正文的格式与其他 OpenAI 格式的端点相同(错误与处理)。视频生成特有的错误如下。

情况HTTP 状态码和 error.codemessage处理
时长、分辨率等取值在这个模型里不能用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_errorThe model service rejected the request, check the parameters and try again确认取值和图片等的 URL
任务 ID 不对,或是别的账号的任务400(获取文件时是 404),task_not_foundTask not found确认 ID
完成前就获取文件400,task_not_readyThe video is not ready yet变成 completed 后再获取
获取失败任务的文件400,task_failedThe video generation failed重新提交
超过了提供方保留文件的期限410,artifact_goneArtifact content is no longer available无法获取。请重新提交
余额不足403,insufficient_quotaInsufficient balance充值
密钥的使用上限不够403,insufficient_quotaThis API key has reached its spending limit提高使用上限(上限与速率限制)
模型 ID 不对503,model_not_foundThe 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 下的 metadataEcho 验证环境中的实测。使用与正式环境相同的中转设置,并用返回测试响应的服务器代替提供方的 API2026-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 设为 82800Echo 验证环境中的实测(同上)2026-10-02
Seedance 2.0 的 metadata.execution_expires_after 的范围(3600–259200 秒,省略时 172800 秒)、写在提示词后面的 --dur 等参数https://www.volcengine.com/docs/82379/15207572026-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-query2026-10-01
Seedance 2.0 的时长、分辨率、宽高比、声音、role 和文件条件,文件保留 24 小时,真人面孔不能用作参考https://www.volcengine.com/docs/82379/1520757 、https://www.volcengine.com/docs/82379/15213092026-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