即梦
调用字节跳动即梦(火山引擎智能视觉)视频生成,支持文生视频、图生视频、首尾帧。可用统一格式提交,也可沿用即梦官方的 Action 请求格式。
| 项 | 值 |
|---|---|
| 提交 | POST /v1/video/generations(或 POST /v1/videos) |
| 查询 | GET /v1/video/generations/{task_id}(或 GET /v1/videos/{task_id}) |
| 即梦官方格式 | POST /jimeng/?Action=CVSync2AsyncSubmitTask&Version=2022-08-31 等,见 即梦官方格式 |
| 鉴权 | Authorization: Bearer YOUR_API_KEY |
| Content-Type | application/json(POST /v1/videos 上传图片文件时用 multipart/form-data) |
异步流程、轮询与计费见 概述与通用流程。
支持的模型
模型名即即梦的 req_key。可用模型以 模型列表 返回为准(或控制台模型价格页)。不同即梦模型能力不同:
- 名称含
t2v的模型只做文生视频 - 即梦 3.0 系列模型按图片数量自动选择:0 张为文生视频,1 张为图生视频,2 张及以上为首尾帧
文生视频
BASH
curl https://www.nextai-code.com/v1/video/generations \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL",
"prompt": "清晨的江南水乡,小船缓缓划过石桥",
"duration": 5,
"metadata": { "aspect_ratio": "16:9" }
}'
提交响应:
JSON
{
"id": "7392616336519610409",
"task_id": "7392616336519610409",
"object": "video",
"model": "YOUR_MODEL",
"status": "",
"progress": 0,
"created_at": 1734567890
}
任务 ID 按 概述 · 读取任务 ID 的方法读取(先 id 后 task_id)。提交响应里的 status 为空字符串,以查询结果为准。
图生视频
首尾帧示例(即梦 3.0 系列模型传 2 张图):
BASH
curl https://www.nextai-code.com/v1/video/generations \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL",
"prompt": "镜头缓慢推进,人物回头",
"images": ["https://example.com/first.jpg", "https://example.com/last.jpg"]
}'
- 图片用
image(1 张)或images(多张)传。 - 同一请求内的图片要么全是 URL,要么全是 Base64:第一张以
http开头时全部按 URL 处理,否则全部按 Base64 处理。Base64 请传纯编码内容,不带data:前缀。
也可以用 POST /v1/videos 以 multipart 直接上传图片文件,字段名 input_reference,可传多个(2 个即首尾帧),单个文件不超过 4.7MB:
BASH
curl https://www.nextai-code.com/v1/videos \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-F "model=YOUR_MODEL" \
-F "prompt=镜头缓慢推进" \
-F "[email protected]"
查询
BASH
curl https://www.nextai-code.com/v1/video/generations/7392616336519610409 \
-H "Authorization: Bearer $NEXTAI_API_KEY"
data.status为SUCCESS时,成片地址在data.fail_reason(即梦 CDN 直链,直接GET下载,不要附带 API Key)。响应结构见 概述 · 查询响应。- 用
GET /v1/videos/{task_id}查询则返回 OpenAI Video 对象,成片地址在meta_data.url。 - 失败时
data.fail_reason为即梦返回的错误信息。
特有参数
统一字段在即梦的含义
| 参数 | 说明 |
|---|---|
model |
即梦 req_key |
duration |
10 为 10 秒,其它值或不传均为 5 秒 |
size |
不生效,宽高比请用 metadata.aspect_ratio |
metadata 字段
metadata 中的同名字段会覆盖上面的值。字段含义与取值以即梦文档为准:
| 字段 | 类型 | 说明 |
|---|---|---|
aspect_ratio |
string | 宽高比,如 16:9、9:16、1:1 |
seed |
integer | 随机种子 |
frames |
integer | 帧数,优先于 duration |
req_key |
string | 覆盖模型名 |
image_urls |
string[] | 图片 URL 列表 |
binary_data_base64 |
string[] | 图片 Base64 列表 |
prompt |
string | 覆盖 prompt |
上表以外的字段不会生效。字段类型必须与上表一致,否则返回 500 build_request_failed。
即梦官方格式
已按即梦官方 CVSync2AsyncSubmitTask / CVSync2AsyncGetResult 接入的,把地址换成平台的 /jimeng/:
BASH
# 提交
curl "https://www.nextai-code.com/jimeng/?Action=CVSync2AsyncSubmitTask&Version=2022-08-31" \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"req_key": "YOUR_MODEL",
"prompt": "清晨的江南水乡,小船缓缓划过石桥",
"aspect_ratio": "16:9",
"seed": -1
}'
# 查询
curl "https://www.nextai-code.com/jimeng/?Action=CVSync2AsyncGetResult&Version=2022-08-31" \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "req_key": "YOUR_MODEL", "task_id": "7392616336519610409" }'
与即梦官方的差异:
- 鉴权用平台 API Key,不需要火山引擎 AK/SK 签名。
- URL 参数
Action必填:CVSync2AsyncGetResult为查询,其它值都按提交处理。 - 提交时
req_key作为模型名,prompt必填;其余字段与类型同上面的 metadata 字段表。 - 查询时请求体必须带
task_id。 - 提交响应是上文的统一提交响应,查询响应是 统一格式,都不是即梦官方的
{code: 10000, data: ...}结构。
限制
| HTTP | code |
说明 |
|---|---|---|
| 400 | — | 官方格式缺少 Action 参数,或查询缺少 task_id(OpenAI 格式错误体 {"error": {...}}) |
| 500 | build_request_failed |
上传文件超过 4.7MB,或 metadata 字段类型不对 |
| 500 | 即梦错误码(如 50411) |
即梦拒绝提交,message 为即梦的错误信息 |
其它错误见 概述 · 错误。