Videos API 视频生成

功能概览

本页用于说明 Videos API 视频生成 的核心能力、调用入口和接入要点，帮助开发者快速判断适用场景并完成集成。

适用场景

• 产品原型验证：快速接入模型能力，验证内容生成、理解或编辑流程。
• 生产业务接入：用于批量任务、自动化工作流和多模型组合调用。
• 能力迁移适配：适合从原有模型或 SDK 平滑切换到亿速API统一接口。

接入建议

• 优先确认模型名称、请求路径和响应字段，再接入具体业务流程。
• 对异步任务、媒体生成和长耗时请求，建议在业务侧加入重试与状态轮询。
• 上线前建议准备日志追踪、错误兜底和内容安全校验，便于稳定运行。

接口总览

POST /v1/videos
GET  /v1/videos/{video_id}
GET  /v1/videos/{video_id}/content

当前支持文生视频、图生视频、异步状态查询和视频下载。

POST /v1/videos

创建异步视频生成任务。创建成功后返回视频任务对象，客户端需要轮询状态，完成后再下载内容。

文生视频

curl "/v1/videos" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "一只橘猫在舞台上弹钢琴，电影感镜头",
    "size": "720x1280",
    "seconds": 6,
    "n": 1
  }'

创建响应示例：

{
  "id": "video_req_xxx",
  "object": "video",
  "created_at": 1710000000,
  "status": "queued",
  "model": "grok-imagine-video"
}

图生视频

推荐使用 input_reference.image_url 传参考图。

curl "/v1/videos" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "让参考图中的主体缓慢转身，背景有轻微风吹动",
    "input_reference": {
      "image_url": "https://example.com/input.png"
    },
    "size": "720x1280",
    "seconds": 6
  }'

data URL 图生视频

curl "/v1/videos" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "让参考图中的角色向镜头挥手，电影感光影",
    "input_reference": {
      "image_url": "data:image/png;base64,..."
    },
    "size": "1280x720",
    "seconds": 6
  }'

多图图生视频

推荐使用 input_reference.image_url 数组传多张参考图，最多 6 张。

多图会按数组顺序传入。通常建议把最重要的主体图、首帧图或主参考图放在第 1 张，后续图片用于补充角色、场景、风格、动作或构图参考。

curl "/v1/videos" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "参考第1张图的人物主体、第2张图的背景风格，生成自然连贯的电影感镜头。人物从画面左侧走向镜头，背景轻微运动，保持主体一致。",
    "input_reference": {
      "image_url": [
        "https://example.com/person.png",
        "https://example.com/background.png"
      ]
    },
    "size": "1280x720",
    "seconds": 6,
    "n": 1
  }'

创建成功后返回视频任务对象：

{
  "id": "video_req_xxx",
  "object": "video",
  "created_at": 1710000000,
  "status": "queued",
  "model": "grok-imagine-video"
}

之后轮询任务状态：

curl "/v1/videos/video_req_xxx" \
  -H "Authorization: Bearer <API_TOKEN>"

任务完成后下载视频：

curl "/v1/videos/video_req_xxx/content" \
  -H "Authorization: Bearer <API_TOKEN>" \
  --output output.mp4

URL 和 data URL 混用

数组里可以同时使用公网图片 URL 和 data:image/...;base64,...。

curl "/v1/videos" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "参考多张图片生成视频，保持第1张图主体一致，融合第2张图场景氛围，镜头缓慢推进。",
    "input_reference": {
      "image_url": [
        "https://example.com/input-1.png",
        "data:image/png;base64,..."
      ]
    },
    "size": "720x1280",
    "seconds": 10
  }'

顶层兼容写法

推荐新接入优先使用 input_reference.image_url。如果已有客户端更方便传顶层字段，也可以使用 image_urls：

curl "/v1/videos" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "根据多张参考图生成一段产品展示视频，镜头缓慢推进，突出主体细节。",
    "image_urls": [
      "https://example.com/product-front.png",
      "https://example.com/product-side.png",
      "https://example.com/product-scene.png"
    ],
    "size": "1280x720",
    "seconds": 6
  }'

多图字段说明

多图注意事项

• 多图最多 6 张，超过会返回 invalid_video_image。
• 图片必须是 http(s) URL 或 data:image/...;base64,...。
• 当前不支持 file_id。
• 多图顺序有意义，建议把最重要的主体图或首帧图放在第 1 张。
• 如果使用公网图片 URL，图片必须能被服务正常访问。
• 视频是异步任务，POST /v1/videos 只创建任务，不直接返回视频文件。
• 任务完成后使用 GET /v1/videos/{video_id}/content 下载视频。
• 后台视频测试页如果只提供单图输入，则只会发单张图；多图请优先通过 API 请求测试。

兼容图片字段

除 input_reference.image_url 外，当前也兼容以下顶层图片字段：

image_url
input_image
image
input_image_url
first_frame_image
reference_image
reference_image_url
images
image_urls
input_images

推荐新接入只使用 input_reference.image_url。多图也兼容 images、image_urls、input_images。

参数支持状态

支持尺寸

当前支持尺寸由后台视频生成设置控制，代码内置可选值如下：

854x480
480x854
480x480
720x480
480x720
1280x720
720x1280
720x720
1080x720
720x1080

默认尺寸当前为：

1280x720

支持时长

当前支持：

6
10

默认时长当前为：

6

查询视频任务

curl "/v1/videos/video_req_xxx" \
  -H "Authorization: Bearer <API_TOKEN>"

响应示例：

{
  "id": "video_req_xxx",
  "object": "video",
  "created_at": 1710000000,
  "status": "completed",
  "model": "grok-imagine-video"
}

失败响应中的任务对象会包含 error：

{
  "id": "video_req_xxx",
  "object": "video",
  "created_at": 1710000000,
  "status": "failed",
  "model": "grok-imagine-video",
  "error": {
    "code": "service_error",
    "message": "The service failed to process the request. Please try again."
  }
}

如果任务超时，error.code 会是 request_timeout。如果请求可能违反内容规范，error.code 会是 content_policy_violation。如果任务没有产出可用视频，error.code 会是 content_not_returned。

状态值：

queued
in_progress
completed
failed
expired

下载视频内容

curl "/v1/videos/video_req_xxx/content" \
  -H "Authorization: Bearer <API_TOKEN>" \
  --output output.mp4

如果任务未完成，会返回 video_not_completed。如果文件不存在，会返回 video_content_not_found。

图生视频图片输入格式

支持：

https://example.com/image.png
http://example.com/image.jpg

多图支持数组形式，最多 6 张：

{
  "input_reference": {
    "image_url": [
      "https://example.com/image-1.png",
      "data:image/png;base64,..."
    ]
  }
}

也兼容对象形式：

{
  "input_reference": {
    "image_url": {
      "url": "https://example.com/image.png"
    }
  }
}

也兼容 base64 对象：

{
  "input_reference": {
    "b64_json": "...",
    "mime_type": "image/png"
  }
}

缓存和 late final

相同视频请求可能命中结果缓存，命中后会直接创建已完成任务。worker 超时后如果稍后返回 final，网关也会尝试补完成原视频任务。

常见错误