# Gemini Omni Flash 1.2

用 POST /v1/videos 调用 gemini-omni-1.2-flash。文生、图生、首尾帧和参考图。

`gemini-omni-1.2-flash` 生成带声音的 MP4。支持文生视频、首帧图生视频、首尾帧和 1 到 3 张参考图。720P 或 1080P，时长 3 到 15 秒。

提交会等到视频生成完才返回。客户端超时设到 900 秒以上。价格见控制台「模型与价格」。

```http
POST /v1/videos
GET /v1/videos/{task_id}
GET /v1/videos/{task_id}/content
```

## 请求参数

| 参数 | 必填 | 类型 | 范围 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | 是 | string | `gemini-omni-1.2-flash` | 固定这个模型 ID |
| `prompt` | 是 | string | — | 场景、动作、镜头。参考图可以写「第一张参考图里的人物」 |
| `seconds` | 否 | string | 见下方 | JSON 里必须是字符串，例如 `"6"`。传数字会被拒绝。不传按 8 秒 |
| `aspect_ratio` | 否 | string | `16:9`、`9:16` | 不传是 `16:9` |
| `size` | 否 | string | `宽x高` | 只用来判断横竖。同时传了 `aspect_ratio` 时以 `aspect_ratio` 为准 |
| `resolution` | 否 | string | `720p`、`1080p` | 不传是 `720p` |
| `first_frame` | 否 | string | data URL 或文件 | 首帧。也接受字段名 `image`、`input_reference` |
| `last_frame` | 否 | string | data URL 或文件 | 尾帧。也接受 `end_frame`。必须和首帧一起传 |
| `reference_images` | 否 | array | 1–3 | 参考图。只约束人物和物体的样子，不保证成为第一帧 |

不需要传 `mode`。传了哪种素材就是哪种用法。

| 用法 | 素材 | `seconds` |
| --- | --- | --- |
| 文生视频 | 只传 `prompt` | 3 到 15 的整数 |
| 图生视频 | `first_frame` 一张 | 3 到 15 的整数 |
| 首尾帧 | `first_frame` 和 `last_frame` 各一张 | 3 到 10 的整数 |
| 参考图 | `reference_images` 1 到 3 张 | 3 到 15 的整数 |

| 分辨率 | 16:9 | 9:16 |
| --- | --- | --- |
| `720p` | 1280×720 | 720×1280 |
| `1080p` | 1920×1080 | 1080×1920 |

成片时长等于请求的秒数，1080P 可能短零点几秒。

## 文生视频

```bash
curl --max-time 900 https://kaienapi.com/v1/videos \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-1.2-flash",
    "prompt": "黄昏的海边，一位骑手沿着沙滩慢慢骑行，海浪拍岸，镜头从远景平稳推进到中景",
    "seconds": "8",
    "aspect_ratio": "16:9"
  }'
```

720P 一般 50–80 秒返回，1080P 一般 90–130 秒。高峰更久。超时或 504 时任务可能已经创建，先查询再决定要不要重提。

## 图生视频

图片不接受网址。传 `https://` 会返回 400，不创建任务。用 `data:image/...;base64,...`，或用 multipart 上传文件。支持 PNG、JPEG、WebP，`data:` 里的类型必须和文件一致。提示词和图片合计不超过 15 MB，大图用 multipart。

```json
{
  "model": "gemini-omni-1.2-flash",
  "prompt": "画面里的纸船顺着溪流漂远，镜头跟随",
  "seconds": "7",
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "first_frame": "data:image/png;base64,iVBORw0KGgo..."
}
```

上传本地文件时不要手动设置 `Content-Type`：

```bash
curl --max-time 900 https://kaienapi.com/v1/videos \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -F model=gemini-omni-1.2-flash \
  -F prompt="画面里面蹦进来一只黑色简体风格的小猫" \
  -F seconds=4 \
  -F aspect_ratio=16:9 \
  -F resolution=720p \
  -F first_frame=@first.png
```

首尾帧再加 `-F last_frame=@last.png`。`reference_images` 可以重复传多个文件。首帧和尾帧必须同一种传法，参考图也不能混用 data URL 和文件。

## 不支持

- 参考视频。
- 首帧和参考图一起传。尾帧单独传，或尾帧和参考图一起传。
- 续写（`extend`）、4K、360P。

## 查询

创建返回的 `status` 通常已经是 `completed`。不是 `completed` 或 `failed` 时，每 10 秒查一次。

```bash
curl "https://kaienapi.com/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

```json
{
  "id": "task_example",
  "object": "video",
  "model": "gemini-omni-1.2-flash",
  "status": "completed",
  "progress": 100,
  "seconds": "4",
  "url": "https://kaienapi.com/v1/videos/task_example/content"
}
```

| 字段 | 说明 |
| --- | --- |
| `status` | `queued`、`in_progress` 继续查。`completed` 去下载。`failed` 看 `error.message`。`unknown` 仍在确认 |
| `seconds` | 计费秒数 |
| `url` | 完成后才有，指向本站 `/v1/videos/{id}/content` |
| `error` | 失败时才有 |

## 下载

返回 `video/mp4` 本身，不是 JSON。支持 `Range`。

```bash
curl "https://kaienapi.com/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  --output result.mp4
```

创建响应刚到时，下载可能短暂返回 400，`Task is not completed yet, current status: NOT_START`。等几秒用同一个 `id` 再下，不要重新提交。

## 错误

参数错误返回 HTTP 400，不创建任务。JSON 里的 `seconds` 必须是字符串：

```json
{"code":"invalid_json","message":"json: cannot unmarshal number into Go struct field .Alias.seconds of type string","data":null}
```

| `message` 中的文字 | 原因 |
| --- | --- |
| `prompt is required` | 没有提示词 |
| `seconds must be a whole number from 3 to 15` | 时长不在 3–15 的整数内 |
| `seconds must be a whole number from 3 to 10 with a last frame` | 首尾帧时长不在 3–10 |
| `must be a whole number of seconds` | 时长不是整数 |
| `seconds and duration must agree` | `seconds` 和 `duration` 不一致 |
| `resolution must be 720p or 1080p` | 分辨率不对 |
| `aspect_ratio must be 16:9 or 9:16` | 比例不对 |
| `must be a data: URL or an uploaded file` | 传了图片网址 |
| `must be a PNG, JPEG or WebP image` | 格式不对，或 data URL 类型和文件不符 |
| `with a matching Content-Type` | 上传文件没写类型或类型不对 |
| `takes a single first-frame image` | 首帧多于 1 张 |
| `takes a single last-frame image` | 尾帧多于 1 张 |
| `reference_images takes 1 to 3 images` | 参考图多于 3 张 |
| `a last frame needs a first frame` | 有尾帧没有首帧 |
| `cannot be combined` | 首帧和参考图一起传了 |
| `send the first and last frames both as uploaded files or both as data: URLs` | 首尾帧混用了文件和 base64 |
| `send every reference image as an uploaded file or every one as a data: URL` | 参考图混用了两种传法 |
| `must total at most 15 MiB` | 提示词和图片超过 15 MB |
| `cannot edit a reference video` | 不支持参考视频 |
| `is not supported by gemini-omni-1.2-flash` | 传了不支持的字段，例如 `extend` |
| `does not match the supplied inputs` | 传了 `mode`，但和素材不符。不要传 `mode` |
| `unexpected file field` | multipart 字段名不对 |
| `Task is not completed yet, current status: NOT_START` | 任务刚完成，稍等再下载 |

401 是密钥无效。403 是额度不足。404 `model_not_found` 是当前分组没开通。高峰可能直接 5xx。`failed` 常见原因是内容不合规，改提示词或素材后再提交。排查时带上响应里的 `request id` 或任务 `id`。
