> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ominiapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini Omni

# Gemini Omni API 接口文档

## 1. 文档说明

本文基于 Google DeepMind 官方页面 `https://deepmind.google/models/gemini-omni/prompt-guide/` 整理。

需要注意：该页面是 Gemini Omni 的 Prompt Guide，不是 API Reference。页面介绍了 Omni 的能力、提示词写法和使用场景，但没有公开独立的 REST endpoint、模型 ID、请求参数、价格、限流或返回结构。

因此，本文分为两类内容：

* 已公开的 Gemini API 通用调用方式。
* 基于 Gemini API 风格整理的 Omni 接入模板，具体模型名和字段需以 Google 官方实际开放为准。

## 2. 基础信息

| 项目     | 内容                                                         |
| ------ | ---------------------------------------------------------- |
| 产品     | Gemini Omni                                                |
| 主要能力   | 文本、图像、视频、音频输入，生成或编辑视频                                      |
| 官方页面   | `https://deepmind.google/models/gemini-omni/prompt-guide/` |
| 页面性质   | Prompt Guide，非 API 文档                                      |
| API 状态 | 页面未公开独立 Omni API                                           |
| 可能接入入口 | Google AI Studio、Gemini API、Vertex AI、Google Flow          |
| 认证方式   | Google API Key 或 Google Cloud OAuth，取决于接入平台                |

## 3. 能力范围

Gemini Omni 官方页面强调的是 “Create anything from anything”，即可以从多种输入生成或编辑视频。

| 能力     | 说明                                 |
| ------ | ---------------------------------- |
| 文本生成视频 | 根据自然语言提示词生成视频                      |
| 视频编辑   | 输入视频后，通过自然语言修改局部内容                 |
| 图像参考   | 使用图片作为角色、风格、构图或物体参考                |
| 音频参考   | 让画面动作、灯光、节奏与音频同步                   |
| 多模态组合  | 同时参考视频、图片、文本、音频                    |
| 风格迁移   | 将视频转换为动画、水彩、黏土、铅笔、玻璃、risograph 等风格 |
| 镜头控制   | 控制远景、中景、近景、推镜、拉镜、dolly zoom、固定机位等  |
| 文本渲染   | 在视频中生成更准确、更同步的文字                   |
| 连续迭代   | 保留已有视频，只修改指定部分                     |

## 4. Prompt 推荐结构

官方建议 Prompt 中包含以下元素：

| 元素                | 示例                                                            |
| ----------------- | ------------------------------------------------------------- |
| Shot framing      | `wide-angle shot`, `close-up`, `medium shot`                  |
| Camera motion     | `slow dolly in`, `quick tilt up`, `locked-off camera`         |
| Style             | `cinematic`, `realistic`, `anime`, `claymation`, `watercolor` |
| Lighting          | `warm sunset light`, `neon lighting`, `soft ethereal glow`    |
| Location          | `an alien landscape with clear azure water`                   |
| Action            | `a violinist plays while the camera moves over her shoulder`  |
| Text rendering    | `show one word at a time, synced to the beat`                 |
| Reference control | `use the character from the image as the main subject`        |
| Temporal control  | `entire story in 10 seconds`, `one continuous shot`           |

## 5. 通用 Gemini API 调用方式

如果 Gemini Omni 后续开放到 Gemini API，很可能沿用 Gemini API 的 `generateContent` 调用风格。

基础 Endpoint 通常类似：

```http theme={null}
POST https://generativelanguage.googleapis.com/v1beta/models/{MODEL_ID}:generateContent?key={API_KEY}
Content-Type: application/json
```

其中 `{MODEL_ID}` 需要替换为实际模型名。

可能的模型名形式如下，但这些名称当前不能从官方 Prompt Guide 页面确认，不能直接假定可用：

```text theme={null}
gemini-omni
gemini-omni-preview
gemini-omni-video
gemini-omni-latest
```

## 6. 文本生成视频接口模板

> 注意：以下为基于 Gemini 多模态 API 风格整理的接入模板，不代表 Omni 当前已公开可用。

### 请求

```http theme={null}
POST https://generativelanguage.googleapis.com/v1beta/models/{MODEL_ID}:generateContent?key={API_KEY}
Content-Type: application/json
```

### 请求体示例

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Create a 10-second cinematic video. A lone astronaut walks across a glowing alien ocean at sunset. Wide-angle shot, slow dolly forward, warm ethereal lighting, realistic style, one continuous shot."
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["VIDEO"]
  }
}
```

### 字段说明

| 字段                   | 类型     | 必填 | 说明                |
| -------------------- | ------ | -- | ----------------- |
| `contents`           | array  | 是  | 用户输入内容            |
| `contents[].role`    | string | 否  | 通常为 `user`        |
| `contents[].parts`   | array  | 是  | 多模态输入片段           |
| `parts[].text`       | string | 否  | 文本提示词             |
| `generationConfig`   | object | 否  | 生成配置              |
| `responseModalities` | array  | 否  | 期望输出模态，例如 `VIDEO` |

## 7. 视频编辑接口模板

Omni 页面明确支持输入视频并通过自然语言编辑，例如：

```text theme={null}
Change the butterfly to a bee.
Change the camera angle to be over the violinist's shoulder.
The lights of the apartments start turning on in sync with the music.
```

### 请求体示例

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "https://example.com/input-video.mp4"
          }
        },
        {
          "text": "Change the butterfly to a bee. Keep the rest of the video unchanged."
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["VIDEO"]
  }
}
```

### 字段说明

| 字段                   | 类型     | 说明                          |
| -------------------- | ------ | --------------------------- |
| `fileData.mimeType`  | string | 输入文件 MIME 类型，例如 `video/mp4` |
| `fileData.fileUri`   | string | 输入视频文件地址或上传后的文件 URI         |
| `text`               | string | 编辑指令                        |
| `responseModalities` | array  | 指定输出视频                      |

## 8. 图像、视频、音频组合接口模板

官方示例：

```text theme={null}
The birds from <video> loosely form the imperfect shape of a bird based on <image>. They move to the music from <audio> and dissipate as they fly.
```

### 请求体示例

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "https://example.com/birds.mp4"
          }
        },
        {
          "fileData": {
            "mimeType": "image/png",
            "fileUri": "https://example.com/bird-shape.png"
          }
        },
        {
          "fileData": {
            "mimeType": "audio/mpeg",
            "fileUri": "https://example.com/music.mp3"
          }
        },
        {
          "text": "The birds from the video loosely form the imperfect shape of the bird in the image. They move to the rhythm of the audio and dissipate as they fly."
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["VIDEO"]
  }
}
```

## 9. 文件上传流程

Gemini API 通常需要先上传文件，再在 `generateContent` 中引用文件 URI。

典型流程：

1. 上传图片、视频或音频。
2. 获取 `fileUri`。
3. 在生成请求中通过 `fileData.fileUri` 引用。
4. 获取生成结果。
5. 如果是长任务，轮询 operation 状态。

伪流程：

```text theme={null}
POST /upload/v1beta/files
-> 返回 fileUri

POST /v1beta/models/{MODEL_ID}:generateContent
-> 返回生成结果或 operation id

GET /v1beta/{operation}
-> 轮询视频生成状态
```

## 10. 异步生成接口预期

视频生成通常耗时较长，因此如果 Omni API 开放，更可能采用异步任务模式。

可能的请求形式：

```http theme={null}
POST /v1beta/models/{MODEL_ID}:predictLongRunning
```

或：

```http theme={null}
POST /v1beta/models/{MODEL_ID}:generateContent
```

### 任务返回示例

```json theme={null}
{
  "name": "operations/abc123",
  "metadata": {
    "state": "RUNNING"
  }
}
```

### 轮询请求

```http theme={null}
GET https://generativelanguage.googleapis.com/v1beta/operations/abc123?key={API_KEY}
```

### 完成返回示例

```json theme={null}
{
  "name": "operations/abc123",
  "done": true,
  "response": {
    "generatedVideos": [
      {
        "uri": "https://example.com/output.mp4"
      }
    ]
  }
}
```

注意：上面是合理推测的长任务模式，具体字段必须以官方实际 API 为准。

## 11. Prompt 示例

### 11.1 文本生成视频

```text theme={null}
Create a 10-second cinematic video of a small wooden boat drifting across a misty lake at sunrise. Wide-angle shot, slow dolly forward, soft golden light, realistic style, one continuous shot.
```

### 11.2 编辑主体

```text theme={null}
Change the butterfly to a bee. Keep the flower, lighting, camera movement, and background unchanged.
```

### 11.3 改变镜头

```text theme={null}
Change the camera angle to be over the violinist's shoulder. Keep the music performance and room lighting the same.
```

### 11.4 改变动作

```text theme={null}
The lights of the apartments start turning on in sync with the music.
```

### 11.5 风格迁移

```text theme={null}
Transform this video into a watercolor animation. Preserve the original motion, composition, and character placement. Use soft paper texture, hand-painted edges, and gentle color bleeding.
```

### 11.6 文本渲染

```text theme={null}
Show one word on screen at a time: did, you, know, that, this, model, can, do, pretty, good, text. Each word appears with a different animated style, perfectly paced to the rhythm.
```

### 11.7 Storyboard

```text theme={null}
Follow this storyboard exactly in order, starting from the top left. Turn the entire story into a 10-second cinematic video.
```

## 12. Node.js 调用模板

```js theme={null}
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: process.env.GEMINI_API_KEY,
});

const response = await ai.models.generateContent({
  model: "REPLACE_WITH_ACTUAL_OMNI_MODEL_ID",
  contents: [
    {
      role: "user",
      parts: [
        {
          text: "Create a 10-second cinematic video of a glowing city at night. Slow drone shot, neon reflections, realistic style."
        }
      ]
    }
  ],
  config: {
    responseModalities: ["VIDEO"]
  }
});

console.log(response);
```

## 13. Python 调用模板

```python theme={null}
from google import genai
import os

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

response = client.models.generate_content(
    model="REPLACE_WITH_ACTUAL_OMNI_MODEL_ID",
    contents=[
        {
            "role": "user",
            "parts": [
                {
                    "text": "Create a 10-second cinematic video of a glowing city at night. Slow drone shot, neon reflections, realistic style."
                }
            ],
        }
    ],
    config={
        "response_modalities": ["VIDEO"]
    },
)

print(response)
```

## 14. cURL 调用模板

```bash theme={null}
curl "https://generativelanguage.googleapis.com/v1beta/models/REPLACE_WITH_ACTUAL_OMNI_MODEL_ID:generateContent?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Create a 10-second cinematic video of a glowing city at night. Slow drone shot, neon reflections, realistic style."
          }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["VIDEO"]
    }
  }'
```

## 15. 返回结果预期结构

### 同步返回示例

```json theme={null}
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "fileData": {
              "mimeType": "video/mp4",
              "fileUri": "https://example.com/generated-video.mp4"
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ]
}
```

### 异步任务返回示例

```json theme={null}
{
  "name": "operations/video-generation-abc123",
  "done": false
}
```

### 异步任务完成示例

```json theme={null}
{
  "name": "operations/video-generation-abc123",
  "done": true,
  "response": {
    "videos": [
      {
        "uri": "https://example.com/output.mp4",
        "mimeType": "video/mp4"
      }
    ]
  }
}
```

## 16. 常见错误码

如果通过 Gemini API 接入，常见错误大致如下：

| HTTP 状态码 | 含义         | 处理方式                    |
| -------- | ---------- | ----------------------- |
| `400`    | 请求参数错误     | 检查 JSON、模型名、文件类型、prompt |
| `401`    | API Key 无效 | 检查密钥                    |
| `403`    | 无权限        | 检查账号权限、地区、模型是否开放        |
| `404`    | 模型不存在      | 检查 `MODEL_ID`           |
| `429`    | 频率限制       | 降低并发，增加重试               |
| `500`    | 服务端错误      | 稍后重试                    |
| `503`    | 服务不可用      | 退避重试                    |

## 17. Prompt 编写建议

官方页面给出的核心经验：

| 建议        | 说明                                                             |
| --------- | -------------------------------------------------------------- |
| 细节越多，控制越强 | 明确镜头、动作、风格、光线、地点                                               |
| 不必逐帧描述    | Omni 会利用世界知识补全细节                                               |
| 可以自然语言迭代  | 只说要改哪里，不必重写完整 prompt                                           |
| 明确保留项     | 编辑视频时写 `keep everything else unchanged`                        |
| 明确镜头语言    | 如 `one continuous shot`, `locked-off`, `push in`, `dolly zoom` |
| 多输入可组合    | 视频负责动作，图片负责形状或角色，音频负责节奏                                        |
| 文本要指定节奏   | 如 `one word at a time`, `synced to the beat`                   |

## 18. 当前不可确认的 API 信息

官方 Prompt Guide 页面没有提供以下内容：

| 信息               | 状态                |
| ---------------- | ----------------- |
| Omni 模型 ID       | 未公开               |
| REST endpoint    | 未公开               |
| SDK 专用方法         | 未公开               |
| 视频参数，如分辨率、时长、帧率  | 未公开               |
| 输出格式             | 未公开               |
| 计费方式             | 未公开               |
| 区域限制             | 页面仅提示功能因地区和订阅层级而异 |
| 是否支持企业 Vertex AI | 页面未说明             |
| 是否支持批量生成         | 未公开               |
| 是否支持 seed        | 未公开               |
| 是否支持负向提示词        | 未公开               |

## 19. 实际接入建议

工程化接入建议按下面顺序确认：

1. 在 Google AI Studio 的模型列表中查找是否存在 Gemini Omni。
2. 如果存在，复制真实模型 ID。
3. 用 `generateContent` 做最小文本生成测试。
4. 再测试 `responseModalities: ["VIDEO"]` 是否被接受。
5. 如果返回长任务 ID，实现 operation 轮询。
6. 如果模型不在 Gemini API 出现，只能通过 Gemini App 或 Google Flow 使用，暂时不能 API 化。

## 20. 最小封装设计

建议业务侧抽象成如下接口：

```ts theme={null}
type OmniInput = {
  prompt: string;
  videoUri?: string;
  imageUris?: string[];
  audioUri?: string;
};

type OmniOutput = {
  status: "queued" | "running" | "succeeded" | "failed";
  operationId?: string;
  videoUri?: string;
  error?: string;
};

async function generateOmniVideo(input: OmniInput): Promise<OmniOutput> {
  // 1. 组装 contents.parts
  // 2. 调用 Gemini 或 Vertex API
  // 3. 如果是异步任务，返回 operationId
  // 4. 如果同步完成，返回 videoUri
  throw new Error("Implement after official Omni model ID is available");
}
```

## 21. 结论

Gemini Omni 官方目前公开的是能力介绍和 Prompt Guide，不是 API 文档。

如果需要可调用接口，目前能确定的只有通用 Gemini API 接入模式；Omni 的真实 `MODEL_ID`、视频生成参数和返回结构需要等 Google AI Studio、Gemini API 或 Vertex AI 正式公开后才能最终确认。