> ## 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 Video 001

> 使用公开 Grok Imagine 视频接口创建图生视频任务，并理解输入图 + 输出视频秒数的计费口径。

Grok Imagine Video 001 使用公开 Grok Imagine 视频入口创建异步图生视频任务。提交任务后平台立即返回任务 ID，生成完成后通过查询接口获取视频 URL 和用量字段。

<Info>
  * 创建任务：`POST /v1/grok-imagine/videos/generations`
  * 查询结果：`GET /v1/grok-imagine/videos/generations/{id}`
  * 输入方式：提示词 + 参考图
  * 计费方式：可按输入图张数 + 输出视频秒数展示用量
</Info>

## 调用流程

1. 准备公网可访问的 HTTPS 图片直链。
2. 调用 `POST /v1/grok-imagine/videos/generations` 提交任务。
3. 保存响应中的 `id`。
4. 以 5 到 10 秒间隔轮询 `GET /v1/grok-imagine/videos/generations/{id}`。
5. `status=succeeded` 后读取 `content.video_url`，并及时下载转存。

## 请求要点

| 字段             | 建议                                                      |
| -------------- | ------------------------------------------------------- |
| `model`        | 使用平台开通的 Grok Imagine 视频模型名，实际可用值以 `/v1/models` 和控制台为准。  |
| `prompt`       | 必填，描述主体、动作、环境、镜头和风格。                                    |
| `image_urls`   | 必填，建议传 1 张公网 HTTPS 图片直链；不要传本地路径、`asset://...` 或 Base64。 |
| `duration`     | 建议显式传入，常见范围为 5 到 15 秒；不同模型配置的最小时长可能不同。                  |
| `aspect_ratio` | 通用比例为 `16:9`、`9:16`、`2:3`；部分模型配置还支持 `3:2`、`1:1`。        |
| `resolution`   | 可选，部分模型配置支持 `480p`、`720p`；未传时按模型配置默认值处理。                |

<Warning>
  请求体只需要传入文档列出的公开字段；额外字段可能会被忽略或返回参数错误。
</Warning>

## 请求示例

```bash 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": "一只电影感机器人在雨夜街道中缓慢转身，霓虹灯反射在地面，低机位，写实，高细节",
    "image_urls": [
      "https://example.com/reference-image.jpg"
    ],
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'
```

## 计费口径

Grok Imagine Video 001 的实际单价以你的账号可见价格和最终账单为准。文档只说明计费口径，不提供固定价格。

当任务使用参考图生成视频时，账单可能会把费用拆成两部分展示：

```text theme={null}
输入图：输入图张数 * 输入图单价
输出视频：输出视频秒数 * 输出视频单价
合计：输入图费用 + 输出视频费用
```

任务失败、取消或超时后，冻结金额会退回到对应 API Key 余额。

## 查询与对账

查询接口的 `usage` 字段仍使用 `video_second` 作为公开用量单位。对于拆分计费的任务，`usage` 可能额外返回输入图和输出视频的金额拆分字段。

| 字段                              | 含义                    |
| ------------------------------- | --------------------- |
| `usage.billing_unit`            | 固定为 `video_second`。   |
| `usage.requested_units`         | 请求时长，通常等于 `duration`。 |
| `usage.billable_units`          | 对外结算单位数，通常为输出视频秒数。    |
| `usage.billable_input_images`   | 实际计费的输入图张数。           |
| `usage.billable_output_seconds` | 实际计费的输出视频秒数。          |
| `usage.input_charge_amount`     | 输入图费用。                |
| `usage.output_charge_amount`    | 输出视频费用。               |
| `usage.charge_amount`           | 本次任务总费用。              |

示例金额仅用于说明字段含义，真实价格以控制台配置和账单为准。

```json theme={null}
{
  "usage": {
    "billing_unit": "video_second",
    "unit_name": "video_second",
    "requested_units": "5",
    "billable_units": "5",
    "billable_input_images": "1",
    "billable_output_seconds": "5",
    "input_charge_amount": "0.060000",
    "output_charge_amount": "4.200000",
    "charge_amount": "4.260000"
  }
}
```