> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wengaocloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 创建 Grok Imagine 视频任务
> 创建 Grok Imagine 异步图生视频任务。受理后立即返回任务 ID，视频生成结果通过查询接口获取。
当前模型配置通常要求传入参考图，建议在 `image_urls` 中传入 1 个公网可访问的 HTTPS 图片直链。
提交 Grok Imagine 异步图生视频任务。平台受理后立即返回任务 ID，视频生成结果通过 [查询 Grok Imagine 视频任务](/api/videos/grok-imagine-query-task) 接口获取。
该接口当前需要传入参考图。建议始终显式传入 `image_urls`，并优先使用 1 张公网可访问的 HTTPS 图片直链。
```
POST /v1/grok-imagine/videos/generations
Authorization: Bearer
Content-Type: application/json
```
***
## 请求参数
| 参数 | 类型 | 必填 | 说明 |
| -------------- | -------------- | ----- | ----------------------------------------------------------------- |
| `model` | string | **是** | 固定使用 `grok-imagine-video-1.5-preview`，或使用平台返回的可用模型名称。 |
| `prompt` | string | **是** | 视频提示词，描述主体、动作、环境、镜头、风格等。 |
| `image_urls` | string\[] | **是** | 参考图 URL 数组。建议传 1 个公网可访问的 HTTPS 图片直链；如账号开通的模型配置支持多参考图，可按实际配置传入。 |
| `duration` | integer/string | 否 | 视频时长（秒）。建议显式传入；常见范围为 `5` 到 `15`，部分模型配置要求 `6` 秒起。 |
| `aspect_ratio` | string | 否 | 画面比例，通用值为 `16:9`、`9:16`、`2:3`；部分模型配置还支持 `3:2`、`1:1`。未传按模型配置默认值处理。 |
| `resolution` | string | 否 | 分辨率档位，部分模型配置支持 `480p`、`720p`；未传按模型配置默认值处理。 |
| `size` | string | 否 | `resolution` 的兼容别名。若同时传入 `resolution` 与 `size`，两者应保持一致。 |
`image_urls` 必须是模型服务可下载的公网图片地址。不要传本地文件路径、`data:image/...;base64`、`asset://...`、需要登录或会过期的临时 URL。若图片无法下载，任务会失败并退款。
***
## 示例
```bash curl theme={null}
curl -X POST "https://{your-domain}/v1/grok-imagine/videos/generations" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video-1.5-preview",
"prompt": "一只哥斯拉在深圳湾海岸线与城市天际线之间缓慢行走，低机位电影镜头，雨后湿润地面反光，巨物感，帅气、震撼、写实，高细节",
"duration": 6,
"aspect_ratio": "16:9",
"image_urls": [
"https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=1280&h=720&fit=crop"
]
}'
```
```python Python theme={null}
import requests
resp = requests.post(
"https://{your-domain}/v1/grok-imagine/videos/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={
"model": "grok-imagine-video-1.5-preview",
"prompt": "一只哥斯拉在深圳湾海岸线与城市天际线之间缓慢行走，低机位电影镜头，电影感，写实，高细节",
"duration": 6,
"aspect_ratio": "16:9",
"image_urls": [
"https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=1280&h=720&fit=crop"
],
},
)
print(resp.json())
```
```javascript JavaScript theme={null}
const response = await fetch("https://{your-domain}/v1/grok-imagine/videos/generations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "grok-imagine-video-1.5-preview",
prompt: "一只哥斯拉在深圳湾海岸线与城市天际线之间缓慢行走，低机位电影镜头，电影感，写实，高细节",
duration: 6,
aspect_ratio: "16:9",
image_urls: [
"https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=1280&h=720&fit=crop",
],
}),
});
console.log(await response.json());
```
***
## 响应示例
```json theme={null}
{
"id": "vidtask_87485721c5b54dc9a97467f8a1812b09",
"object": "video.generation.task",
"created": 1779782400,
"model": "grok-imagine-video-1.5-preview",
"status": "queued",
"expires_at": 1779955200
}
```
保存响应中的 `id`，然后调用查询接口轮询任务状态。
***
## 计费说明
Grok Imagine 视频使用 `video_second` 作为公开用量单位。对于输入图 + 输出视频秒数的价格配置，控制台账单会拆分输入图费用和输出视频费用。
| 字段 | 说明 |
| ------------------------- | ---------------------- |
| `billing_unit` | `video_second` |
| `requested_units` | 请求的 `duration` 秒数 |
| `billable_units` | 任务成功后实际结算秒数，通常等于输出视频秒数 |
| `billable_input_images` | 存在时表示本次计费的输入图张数 |
| `billable_output_seconds` | 存在时表示本次计费的输出视频秒数 |
| `input_charge_amount` | 存在时表示输入图费用 |
| `output_charge_amount` | 存在时表示输出视频费用 |
| `charge_amount` | 存在时表示本次任务总费用 |
任务失败、取消或超时后，平台会退款到对应 API Key 余额。
更多说明见 [Grok Imagine Video 001](/guides/grok-imagine-video-001)。
***
## 常见错误
| 场景 | 可能错误 | 处理方式 |
| -------------------------- | ---------------------------------------------- | ---------------------- |
| 未传参考图或传空数组 | `model requires an input image` | 传入至少一个公网可访问图片 URL。 |
| 图片 URL 需要登录、过期或被防盗链 | `image_download_error` / HTTP 403 | 换成可匿名下载的图片直链。 |
| 传入 `data:image/...;base64` | 模型服务返回错误或 500 | 先将图片上传到公网对象存储，再传 URL。 |
| 模型服务额度不足 | `permission-denied` / credits / spending limit | 联系平台处理额度。 |
| 模型未授权 | `model_not_allowed` / `model_not_visible` | 检查 API Key 可用模型和域名可见性。 |
## OpenAPI
````yaml POST /v1/grok-imagine/videos/generations
openapi: 3.1.0
info:
title: WengaoCloud AI Gateway API
version: 0.1.0
description: WengaoCloud AI 聚合平台公开 API 契约草案，覆盖 OpenAI 兼容接口、Anthropic 原生接口和平台扩展接口。
servers:
- url: https://xxx.wengaocloud.com
description: 问高云 API 网关根域名。OpenAI SDK 的 base_url 使用 https://xxx.wengaocloud.com/v1。
- url: https://{tenant}.wengaocloud.com
description: 控制台展示的租户或 OEM API 网关根域名。
variables:
tenant:
default: xxx
security:
- bearerAuth: []
tags:
- name: models
x-group: 模型
- name: openai-compatible
x-group: OpenAI 兼容接口
- name: anthropic-native
x-group: Anthropic 原生接口
- name: images-v3
x-group: 图片（V3 同步）
- name: volcengine-images
x-group: 图片（火山直连）
- name: images
x-group: 图片（V1 兼容）
- name: async-images
x-group: 图片异步任务
- name: aliwan-images
x-group: 图片（百炼万相）
- name: videos
x-group: 视频
paths:
/v1/grok-imagine/videos/generations:
post:
tags:
- videos
summary: 创建 Grok Imagine 视频任务
description: |
创建 Grok Imagine 异步图生视频任务。受理后立即返回任务 ID，视频生成结果通过查询接口获取。
当前模型配置通常要求传入参考图，建议在 `image_urls` 中传入 1 个公网可访问的 HTTPS 图片直链。
operationId: createGrokImagineVideoGeneration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GrokImagineVideoGenerationRequest'
examples:
imageToVideo:
summary: 图生视频
value:
model: grok-imagine-video-1.5-preview
prompt: 一只哥斯拉在深圳湾海岸线与城市天际线之间缓慢行走，低机位电影镜头，电影感，写实，高细节
duration: 6
aspect_ratio: '16:9'
resolution: 720p
image_urls:
- >-
https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=1280&h=720&fit=crop
responses:
'202':
description: 任务已受理并进入队列。
content:
application/json:
schema:
$ref: '#/components/schemas/VideoGenerationCreateResponse'
examples:
queued:
value:
id: vidtask_87485721c5b54dc9a97467f8a1812b09
object: video.generation.task
created: 1779782400
model: grok-imagine-video-1.5-preview
status: queued
expires_at: 1779955200
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/InsufficientQuota'
'403':
$ref: '#/components/responses/Forbidden'
components:
schemas:
GrokImagineVideoGenerationRequest:
type: object
required:
- model
- prompt
- image_urls
properties:
model:
type: string
description: 平台开通的 Grok Imagine 视频模型名称。
example: grok-imagine-video-1.5-preview
prompt:
type: string
description: 视频提示词，描述主体、动作、环境、镜头、风格等。
example: 一只哥斯拉在深圳湾海岸线与城市天际线之间缓慢行走，低机位电影镜头，电影感，写实，高细节
image_urls:
type: array
minItems: 1
description: |
参考图 URL 数组。建议传 1 个公网可访问的 HTTPS 图片直链；如账号开通的模型配置支持多参考图，可按实际配置传入。
不支持本地文件路径、`data:image/...;base64`、`asset://...`、需要登录或会过期的临时 URL。
items:
type: string
example:
- >-
https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=1280&h=720&fit=crop
duration:
oneOf:
- type: integer
- type: string
description: 视频时长（秒）。建议显式传入；常见范围为 5 到 15，部分模型配置要求 6 秒起。
example: 6
aspect_ratio:
type: string
description: 画面比例。通用值为 `16:9`、`9:16`、`2:3`；部分模型配置还支持 `3:2`、`1:1`。
example: '16:9'
resolution:
type: string
description: 分辨率档位。部分模型配置支持 `480p`、`720p`；未传按模型配置默认值处理。
example: 720p
size:
type: string
description: resolution 的兼容别名。若同时传入 `resolution` 与 `size`，两者应保持一致。
example: 720p
additionalProperties: true
VideoGenerationCreateResponse:
type: object
required:
- id
- object
- created
- model
- status
properties:
id:
type: string
description: 平台任务 ID，用于查询任务。
example: vidtask_3cb6299b32d24f93a82e8a74b3e06161
object:
type: string
enum:
- video.generation.task
created:
type: integer
description: 任务创建时间，Unix 秒。
model:
type: string
description: 请求中的平台模型名称。
status:
type: string
enum:
- queued
description: 初始状态，通常为 `queued`。
expires_at:
type: integer
description: 任务过期时间估算，Unix 秒。
ErrorResponse:
type: object
properties:
error:
type: object
properties:
type:
type: string
example: invalid_request_error
code:
type: string
example: model_endpoint_mismatch
message:
type: string
example: 该模型不支持当前 endpoint。
responses:
BadRequest:
description: 请求参数无效。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: API Key 缺失或无效。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InsufficientQuota:
description: 余额或额度不足。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Forbidden:
description: 模型不可见、API Key 无权限或档位不可用。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
x-default: sk-your-api-key
````