即梦

调用字节跳动即梦(火山引擎智能视觉)视频生成,支持文生视频、图生视频、首尾帧。可用统一格式提交,也可沿用即梦官方的 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 为即梦的错误信息

其它错误见 概述 · 错误。

相关文档