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

# 视频理解

> 通过 Gemini 原生 generateContent 接口让 Gemini 模型解析视频的画面和声音，按 tokens 计费。

Gemini 模型可以观看视频，回答画面中出现了什么、声音里说了什么。OmniRelay 以 Gemini 原生接口提供这些模型，因此 Google 的 Gemini SDK 和已有的 `generateContent` 请求只需更换 base URL 和 Key 即可使用：

* `POST https://api.omnirelay.ai/v1beta/models/{model}:generateContent` 以 JSON 一次性返回完整回答。
* `POST https://api.omnirelay.ai/v1beta/models/{model}:streamGenerateContent?alt=sse` 以服务器推送事件（SSE）流式返回。

请在 `x-goog-api-key` 请求头中发送 OmniRelay API Key（Gemini SDK 的默认方式），也可以作为 Bearer token 发送。Key 的规则与其他模型相同：有效期、[IP 白名单](https://omnirelay.ai/docs/cn/overview/rate-limits.md#key-的-ip-白名单)、[模型限制](https://omnirelay.ai/docs/cn/overview/authentication.md#限定-key-可调用的模型)、预算以及[速率与并发限制](https://omnirelay.ai/docs/cn/overview/rate-limits.md)。放在 `?key=` 查询参数中的 Key 不会被读取。

## 模型

| 模型 ID | 视频输入 | 最大输出 tokens |
| - | - | - |
| `gemini-3.1-pro-preview` | 画面与音频 | 64,512 |

其他模型调用此接口会返回 `unsupported_parameter`，不产生费用。纯文本的 Gemini 调用也可以使用 [Chat Completions](https://omnirelay.ai/docs/cn/llms/chat-completions.md)。

## 解析视频

把视频放在 `fileData` 部分，使用可公开访问的 `https` URL，后面跟上你的问题：

```bash cURL theme={null}
curl "https://api.omnirelay.ai/v1beta/models/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: $OMNIRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [
        {"fileData": {"mimeType": "video/mp4", "fileUri": "https://example.com/clip.mp4"}},
        {"text": "请结合视频画面和音频进行详细解析，用中文输出 JSON。包含 summary（整体摘要）、timeline（事件数组，每项包含 start_time、end_time、visual_description、audio_summary）、visible_text（可辨认的画面文字数组）。看不清或听不清的内容标记为无法确认，不要编造。"}
      ]
    }],
    "generationConfig": {"responseMimeType": "application/json", "maxOutputTokens": 8192}
  }'
```

```python Python theme={null}
from google import genai
from google.genai import types

client = genai.Client(
    api_key=OMNIRELAY_API_KEY,
    http_options=types.HttpOptions(base_url="https://api.omnirelay.ai"),
)
response = client.models.generate_content(
    model="gemini-3.1-pro-preview",
    contents=[
        types.Part.from_uri(file_uri="https://example.com/clip.mp4", mime_type="video/mp4"),
        "请结合视频画面和音频进行解析，输出包含 summary、timeline、visible_text 的 JSON。",
    ],
    config=types.GenerateContentConfig(response_mime_type="application/json", max_output_tokens=8192),
)
print(response.text)
```

响应保持 Gemini 原生格式：回答位于 `candidates[0].content.parts`，`usageMetadata` 报告 tokens 用量，其中 `promptTokensDetails` 列出视频所占的部分。

### 视频输入

* **URL 方式**：`fileData.fileUri` 必须是模型可以下载的公开 `https` URL。
* **内联方式**：较小的片段可以以 base64 放入 `inlineData`。整个请求体上限为 4 MB，更大的视频请使用 URL。
* 不支持 Gemini Files API 的 URI（`generativelanguage.googleapis.com/.../files/...`）和 `cachedContent`。

`generateContent` 请求的其他字段会按原样传给模型：`systemInstruction`、`generationConfig`（包括 `responseSchema` 和 `thinkingConfig`）、`safetySettings`，以及带 `functionDeclarations` 的 `tools` 和 `toolConfig.functionCallingConfig`。字段名请使用 camelCase。`candidateCount` 必须为 1，`thinkingBudget` 不能超过 `maxOutputTokens`；此接口不提供内置的搜索、URL 上下文、代码执行和文件检索工具。请不要在请求体中放 `model` 或 `stream`，二者由路径决定。如果省略 `generationConfig.maxOutputTokens`，OmniRelay 会使用模型默认值 32,000。

## 流式输出

使用 `:streamGenerateContent?alt=sse`。每个事件都是 Gemini 格式的 JSON 片段，且都带有截至当前的用量。模型报告结束原因后，按最后一个片段的用量计费。长视频更适合流式调用：非流式调用必须在 90 秒内返回结果，而流式调用只需在这段时间内返回第一个片段。

## 价格

视频理解按模型的[文本价格](https://omnirelay.ai/docs/cn/llms/listing-models.md)以 tokens 计费。视频的画面帧和音频计为**输入 tokens**；与 Google 自身的计费方式一致，模型的思考过程计为**输出 tokens**。`gemini-3.1-pro-preview` 的价格：

| | 输入 | 输出（含思考） |
| - | - | - |
| 输入不超过 200,000 tokens | USD 2 / M | USD 12 / M |
| 输入超过 200,000 tokens（整个请求） | USD 4 / M | USD 18 / M |

一段短视频加一份详细的 JSON 解析，通常约 **USD 0.01–0.02**。你的折扣与文本模型一样适用。

调用开始时，OmniRelay 会冻结其最高费用：请求本身的文本、**每个 URL 视频 131,072 个输入 tokens**，以及完整的 `maxOutputTokens` 再加 1,024 个 tokens（模型可能略微超出上限才结束）。你只需为实际报告的 tokens 付费，其余冻结金额在调用结束时退回余额。请让 `maxOutputTokens` 接近实际需要，以减少冻结金额。用量远超冻结金额的调用（例如很长的视频）会转为人工核对，而不是自动扣费。

非流式调用的费用在响应头 `X-OmniRelay-Cost-Microusd` 中返回；两种调用的费用都可以在[用量页面](https://omnirelay.ai/docs/cn/general/usage-billing.md)查看。

## 错误

错误以 Gemini 格式返回，Gemini SDK 会将其作为 API 错误抛出：

```json theme={null}
{"error": {"code": 400, "message": "This model does not support one of the request parameters. Nothing was charged.", "status": "unsupported_parameter", "param": "cachedContent"}, "request_id": "…"}
```

`code` 是 HTTP 状态码，`status` 是 OmniRelay 的[错误码](https://omnirelay.ai/docs/cn/general/errors.md)。如果模型无法获取或读取视频，调用会以 `invalid_parameter` 失败，不产生费用。流式调用中的失败会作为最后一个事件返回，内容是同样的 `error` 对象。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.