# Gemini Omni 1.2 Flash — /videos/generations

Gemini Omni 1.2 Flash 是 Google 2026 年 11 月发布的视频生成与编辑模型。通过 `POST /v1/videos/generations` 提交异步任务：不带图为文生视频，1 张图作首帧，首尾帧模式 2 张图作首尾帧，参考图模式 1–3 张图，再传一段 1–15 秒的视频就是视频编辑。720P / 1080P / 4K，16:9 或 9:16，自带声音，无可见水印。按秒计费，编辑按源视频秒数计费。

**端点:** `POST https://kovapi.com/v1/videos/generations`

## 快速开始

三步跑通：提交任务 → 查询结果 → 拿到视频链接。把 YOUR_API_KEY 换成你的 Key，下面的命令可以直接运行。

**第 1 步 · 提交任务（立刻返回任务号，HTTP 202）**

```
curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-omni-1.2-flash", "prompt": "雨夜的城市街道，一只纸船顺着积水漂流，穿黄色雨衣的孩子笑着追赶，霓虹倒影在水面晃动", "duration": 10, "resolution": "720P", "size": "16:9"}'
```

返回（HTTP 202）

```
{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "gemini-omni-1.2-flash"
}
```

**第 2 步 · 每 5–10 秒查询一次，直到 `status` 变成 `succeeded` 或 `failed`**

```
curl https://kovapi.com/v1/videos/jobs/img_5c2e8f1a9b3d7e6f0a4c8b2d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

成功时的返回

```
{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "gemini-omni-1.2-flash",
  "data": [
    {"url": "https://img.kovapi.com/i/8c1f0e5d2b7a49e3a6d0c4f1b9e2a7d5.mp4"}
  ],
  "usage": {"clips": 1, "model": "gemini-omni-1.2-flash"}
}
```

**第 3 步 · `data[0].url` 就是成片（MP4），保留 7 天；需要长期使用，请下载到你自己的存储。**

**完整示例（Python：提交 → 等待 → 保存到本地）**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. 提交任务
job = requests.post(f"{BASE}/videos/generations", headers=HEADERS, json={
    "model": "gemini-omni-1.2-flash",
    "prompt": "雨夜的城市街道，一只纸船顺着积水漂流，穿黄色雨衣的孩子笑着追赶，霓虹倒影在水面晃动",
    "duration": 10,
    "resolution": "720P",
    "size": "16:9",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. 每 10 秒查询一次，最多等一小时
deadline = time.time() + 3600
while job["status"] not in ("succeeded", "failed") and time.time() < deadline:
    time.sleep(10)
    job = requests.get(f"{BASE}/videos/jobs/{job['id']}", headers=HEADERS).json()

# 3. 下载视频
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("gemini-omni-1.2-flash.mp4", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
elif job["status"] == "failed":
    print("failed:", job["error"]["code"], job["error"]["message"])
else:
    print("still", job["status"], job["id"])
```

排队时，查询结果里还有 `queue_position`（前面还有几个任务）和 `eta_seconds`（预计还要等几秒）。超过你设的等待时间也不要重新提交：任务还在，稍后用同一个任务号接着查。

## 认证
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 规格速览

| 时长 | 3–15 秒逐秒可选（默认 10 秒）· 首帧 / 首尾帧 3–10 秒 · 编辑跟随源视频（1–15 秒） |
| --- | --- |
| 分辨率 | 720P / 1080P / 4K |
| 画面比例 | 16:9 / 9:16 |
| 参考图 | 首帧 1 张 · 首尾帧 2 张 · 参考图 1–3 张 · 编辑时参考图最多 5 张 |
| 视频编辑 | 视频编辑：1 段源视频，1–15 秒、mp4 / mov、≤ 50MB · 按源视频秒数计费 |
| 参考音频 | 不支持 |
| 声音 | 固定带声音（对白、音乐、音效写在提示词里），不能关（传 `audio: false` 会被拒绝） |
| 提示词长度 | 最多 20,000 个字符（中英文都按字符计） |
| 计费方式 | 按秒：所选分辨率的每秒单价 × 时长（编辑为源视频秒数） |

## 请求参数

`POST /v1/videos/generations` 的请求体（JSON）：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| model | string | 是 | 模型 id：`gemini-omni-1.2-flash`。 |
| prompt | string | 是 | 视频内容、镜头、动作和声音的描述，最长 20,000 个字符（中英文都按字符计）。多张参考图时可用 @Image1 / @Image2 点名；编辑时写要改什么，例如「把场景改成夜晚，其余保持不变」。不支持 negative_prompt，不想要的内容直接写进提示词。 |
| duration | integer | 否 | 时长：3–15 之间的整数秒（默认 10），也可写作 `seconds`。首帧 / 首尾帧模式 3–10 秒；视频编辑时不用传，成片时长跟随源视频。按秒计费，见下方「价格」。 |
| resolution | string | 否 | 分辨率：720P（默认）/ 1080P / 4K（1080P 和 4K 是官方的高清放大；4K 竖屏为 2160×3840）。也接受 720p、1080p、4k、2160p。暂不支持 360P。 |
| size | string | 否 | 画幅：16:9（默认）/ 9:16，也可写作 aspect_ratio。其他比例会被拒绝。视频编辑不传时按源视频的横竖自动选。 |
| images | array | 否 | 多张图（每张不超过 16MB）：2–3 张默认作参考图（最多 3 张）；image_role=first_frame 时 2 张作首尾帧；视频编辑时最多 5 张参考图。也接受 image_urls、image_with_roles（[{"url": ..., "role": "first_frame" \| "last_frame" \| "reference"}]）。超过上限直接报错，不会截断。 一张图（公网 URL、data: URI 或 base64）：默认作首帧（3–10 秒）；加 image_role=reference 则作参考图。也接受 first_frame_image（首帧）和 last_frame_image（尾帧）。 |
| image_role | string | 否 | `first_frame`（首帧 / 首尾帧，3–10 秒）或 `reference`（1–3 张参考图）。不传时 1 张作首帧、2–3 张作参考图。也接受其他常见写法：`first_frame_image`、`last_frame_image`、`image_urls`、`image_with_roles`、`omni_reference_task_type`。 |
| video_urls | array | 否 | 视频编辑：传 1 段 1–15 秒的视频（mp4 / mov，不超过 50MB；公网链接、data:video/mp4;base64,... 或 Playground 上传后的链接），也可写作 video_url / video_references。成片时长跟随源视频，按源视频秒数计费；不是整秒的部分会截掉（4.5 秒按 4 秒编辑和计费）。不能和首帧 / 首尾帧一起用；暂不支持续写（extend）。 |
| audio | boolean | 否 | 该模型固定生成声音（对白、音乐、音效写在提示词里），此参数可省略（传 false 会被拒绝）。 |
| callback_url | string | 否 | 任务结束时把结果推送到这个地址，见下文的 Webhook。 |
| n | integer | 否 | 每个任务出 1 条视频，不用传。传了大于 1 的值也只出 1 条，但提交时会按 n 条预扣，任务结束后退回多扣的部分。 |

其他字段（如 `seed`、`negative_prompt`、`fps`、`watermark`）不会转发，也不影响价格；成片一律是 MP4，通过 `url` 返回。

## 价格

按秒计费：费用 = 所选分辨率的每秒单价 × 时长。视频编辑按源视频的秒数计费（不是整秒的部分会截掉，不计费）。参考图不计费。提交时按这个金额预扣，成功按同样的金额结算，失败全额退回。1 积分 = $0.005。

| 分辨率 | 积分 / 秒 | 美元 / 秒 | 10 秒一条 | 编辑 8 秒源视频 |
| --- | --- | --- | --- | --- |
| 720P | 7 | $0.035 | $0.35 | $0.28 |
| 1080P | 10 | $0.05 | $0.50 | $0.40 |
| 4K | 20 | $0.10 | $1.00 | $0.80 |

## 参考素材

- **首帧 / 首尾帧**：`image` 传 1 张作首帧；`images` 传 2 张并加 `image_role: first_frame` 作首尾帧。最长 10 秒。图的横竖最好和 `size` 一致。

- **参考图**：`images` 传 1–3 张并加 `image_role: reference`（2–3 张不传也按参考图），图里的人物、物体或场景会出现在视频里，但不作为某一帧。在提示词里可以用 @Image1 / @Image2 点名。

- **视频编辑**：`video_urls` 传 1 段 1–15 秒的视频，提示词写要改什么，例如「把场景改成夜晚，其余保持不变」；可再带最多 5 张参考图（例如「把画面里的人换成 @Image1 的人」）。提交时我们会下载源视频并测出时长：读不出、不到 1 秒或超过 15 秒的直接返回 400，不扣费。

- 暂不支持：360P、续写（extend）、参考视频 / 参考音频输入、negative_prompt（不想要的内容直接写进提示词）。

- 每张图可以是公网图片链接、`data:` URI 或 base64，单张不超过 16MB，多张用数组放在 `images` 里。提交时我们先把图片转存好再排队；读不到的图片会直接返回 400，`message` 写明是第几张，这一单不计费。

- 我们转存的参考素材和成片都保留 7 天。

**视频编辑：改场景，并换上参考图里的人**

```
curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-omni-1.2-flash", "prompt": "把场景改成月光下的夜晚，把画面中央的人换成 @Image1 的人，其余保持不变", "video_urls": ["https://example.com/clip-8s.mp4"], "images": ["https://example.com/person.png"], "resolution": "720P"}'
```

成片时长跟随源视频；源视频 8 秒，按 8 秒计费，参考图不计费。

## 任务状态与返回字段

`GET /v1/videos/jobs/{id}` 返回这些状态，各字段的说明见 [异步任务](https://docs.kovapi.com/zh/guide/async-jobs#fields)。每 5–10 秒查一次，或者用下面的 Webhook 等推送。查询不收费，同一个账号的任何 Key 都能查。

| 状态 | 含义 |
| --- | --- |
| queued | 排队中。返回里带 `queue_position`（前面还有几个任务）和 `eta_seconds`（预计等待秒数）。 |
| processing | 生成中。 |
| succeeded | 已完成。结果在 `data[0].url`，计费明细在 `usage`。 |
| failed | 失败。原因在 `error`，预扣的积分已全额退回。 |

- `processing` 有时会回到 `queued`：例如服务繁忙、成片正在重新取回，或者服务重启。任务没能完成时，网关可能自动重新生成；无论重试几次，一个任务只扣一次费用。

- 同一个账号最多 50 个任务同时生成，更多的任务按提交顺序排队；排队超过 15 分钟还没开始的任务会自动失败并全额退款。任务记录保留 3 天，视频链接保留 7 天。

## 出片时间

我们的测试：3–6 秒 720P 约 1 分钟，13 秒 1080P 约 2.5 分钟，4K 约 3 分钟，编辑约 1.5 分钟；排队多时会更久，最长等 20 分钟，超时全额退款。

近 7 天真实调用：中位 57 秒，90% 在 102 秒 内完成。

## 错误与退款

提交时出错会直接返回 HTTP 4xx / 5xx，不建任务、不扣费；提交成功后的失败写在查询结果里，预扣的积分全额退回。全部错误码见 [错误码](https://docs.kovapi.com/zh/guide/errors)。

### 提交时返回的错误

| HTTP | code | 原因 | 怎么办 |
| --- | --- | --- | --- |
| 400 | invalid_request | 参数不合法：时长、分辨率、比例或素材数量超出这个模型的范围，提示词太长，参考图或参考视频读不到，或者给固定带声音的模型传了 `audio: false` 等。`message` 写明原因。 | 按 `message` 修改后重新提交。 |
| 400 | invalid_source_video | 源视频没有被接受：读不出时长、不到 1 秒、超过 15 秒或文件损坏。 | 换一段 1–15 秒、能正常播放的 mp4 / mov 再提交；本次没有扣费。 |
| 400 | invalid_callback_url | `callback_url` 不是公网的 http(s) 地址，或超过 2000 个字符。 | 换成能从公网访问的地址。 |
| 400 | model_not_found | 型号写错、没有传 `model`，或这个型号不能用在这个接口上（例如拿对话模型调生图接口）。 | 以 `GET /v1/models` 或 [API 手册](https://docs.kovapi.com/zh/api) 里的模型 id 为准。 |
| 401 | invalid_api_key | Key 不存在、已删除或已停用，或者账号已停用。 | 到控制台「API Keys」页面检查这把 Key。 |
| 402 | insufficient_quota | 余额不够预扣这一单。网关先按这一单可能的最高费用预扣，同时发很多请求时也可能出现。 | 如果是并发突发，稍等几秒重试；否则充值。 |
| 429 | rate_limit_exceeded | 超过了这把 Key 设置的每分钟请求数（按最近 60 秒计）。不带 `Retry-After`。 | 等几秒再试，或在控制台调高这把 Key 的上限。 |
| 503 | model_maintenance | 型号维护中，暂停接单，期间不会改由其他模型作答。 | 维护结束后重试，进度见 [服务状态](https://kovapi.com/zh/status)。 |
| 503 | service_unavailable | 我们这边临时出错，例如保存参考素材失败。这一单没有创建任务，也没有扣费。 | 稍后重试。 |

### 任务失败（`status` 为 `failed`）

| code | 什么时候出现 | 怎么办 |
| --- | --- | --- |
| content_policy | 提示词或参考图没有通过模型方的内容审核。 | 改写提示词或更换素材后再提交；原样重交还会被拒。 |
| invalid_request | 模型方不接受这组参数（例如这个模式和分辨率的组合）。`message` 写明原因。 | 按 `message` 调整参数后再提交。 |
| wait_timeout | 视频：超过 120 分钟仍未生成结果，按超时处理，积分全额退还；之后如果生成成功，视频免费交付。 | 重新提交。 |
| upstream_error | 其他失败：自动重试后仍然失败、排队 15 分钟还没开始、上游拒绝但没有说明原因等，`message` 写明具体情况。 | 通常重新提交就能成功。 |

请按 `code` 判断，不要匹配 `message` 的文字。遇到不认识的 `code`（或者没有 `code`），按 `upstream_error` 处理：重新提交通常就能成功。失败的任务一律全额退款。

## 用 Webhook 代替轮询

提交时加上 `callback_url`，任务一结束（成功或失败），网关就把和查询接口完全一样的结果推送到这个地址，带签名，失败会自动重试。也可以在控制台「设置 → Webhook」里配一个账户级地址。 [Webhook 文档 →](https://docs.kovapi.com/zh/webhooks)

```
curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-omni-1.2-flash", "prompt": "雨夜的城市街道，一只纸船顺着积水漂流，穿黄色雨衣的孩子笑着追赶，霓虹倒影在水面晃动", "duration": 10, "resolution": "720P", "size": "16:9", "callback_url": "https://your-domain.com/webhook"}'
```
