# Gemini Omni API

> Gemini Omni — high-quality AI video generation.

- **Provider**: Google
- **Model id**: `gemini-omni-video`
- **Modality**: video
- **Price**: 31–151.12 credits

## Overview

Gemini Omni is called in two steps: create a generation task, then poll the task until the result is ready.

## Authentication

All requests require a Bearer Token in the request header:

```
Authorization: Bearer YOUR_API_KEY
```

## Create Task

`POST https://you.bot/api/v1/generate`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| modelId | string | Yes | Model id: `gemini-omni-video` |
| input | object | Yes | Input parameters object (see below) |
| callbackUrl | string | No | https URL we POST the finished task to. Signed with `X-Webhook-Signature` once you create a webhook signing key in Dashboard → Settings |

### input object parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| prompt | string | Yes | Describe the image you want to generate. Max 20000 characters. (example: Create a 4-second 16:9 advertising loop from the uploaded photo. Hold the framing and add only believable ambient motion: steam rising, fabric settling, light… — full value in the request example) |
| image_urls | string[] | No | Reference images. The base limit is 7; a video uses 2 image slots and each character_id uses 1 image slot. (image URL) |
| video_list | string | No | Optional video input. Only 1 video is allowed and it uses 2 image slots. |
| duration | string | No | Note: when video input is provided, the output duration is determined by the model automatically. This duration parameter will not take effect. (options: 4 \| 6 \| 8 \| 10) (default: 4) |
| aspect_ratio | string | No | Video ratio (options: 16:9 \| 9:16) (default: 16:9) |
| resolution | string | No | Output video resolution. Valid values: 720P(default), 1080P, 4k. (options: 720p \| 1080p \| 4k) (default: 720p) |

### Request example

```json
{
  "modelId": "gemini-omni-video",
  "input": {
    "prompt": "Create a 4-second 16:9 advertising loop from the uploaded photo. Hold the framing and add only believable ambient motion: steam rising, fabric settling, light drifting slowly across the surface. Keep every product edge and any label text exactly as uploaded. One soft key light, gentle falloff, muted palette. Seamless loop, no cuts, no camera shake. Ultra-realistic commercial cinematography. No logos, no brand references, no watermark, no people.",
    "image_urls": [
      "https://you.bot/examples/grok-imagine-text-to-image.jpg"
    ],
    "video_list": "example",
    "duration": "4",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }
}
```

### Response example

```json
{
  "taskId": "281e5b0…f39b9",
  "creditsCharged": 31
}
```

## Query Task

`GET https://you.bot/api/v1/task/{taskId}?model=gemini-omni-video`

When `state` is `success`, the output is in `resultUrls`: `{ "state": "success", "resultUrls": [ ... ] }`. (Text models return inline in the create response.)

## Error Codes

| Code | Description |
|------|-------------|
| 200 | Request successful |
| 400 | Invalid request parameters |
| 401 | Authentication failed — check API Key |
| 402 | Insufficient account balance |
| 403 | IP not allowed for this key, or the key is restricted to other models |
| 404 | Task not found, or it has expired |
| 409 | Duplicate request — an identical submit arrived moments ago. Nothing was charged; retry is safe |
| 413 | Payload too large — see the character and file-size limits for this model |
| 429 | Rate limit exceeded — retry after the Retry-After header |
| 500 | Internal server error |
| 504 | Upstream timed out — nothing was delivered; retry is safe |