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

# Gemini 协议：generateContent 请求格式、媒体输入与 SDK

> 用 Gemini 原生格式调用老张API：generateContent 请求与认证、Google Gen AI SDK 配置、图片、PDF、音频与 MP4 视频输入、结果读取、多轮消息和流式入口。

Gemini 协议即 Google Gemini API 的原生格式。使用 Google Gen AI SDK 或已有 Gemini 请求时，把主机改为 `https://api.laozhang.ai` 并换上老张API密钥即可。

| 项目 | 内容 |
| - | - |
| 请求 | 向 `generateContent` 接口发送 `contents` |
| 结果 | 在 `candidates` 中返回 |
| 适用模型 | [模型与价格总表](/models)中「兼容端点」包含 Gemini 的模型 |
| 媒体输入 | 图片、PDF、音频、MP4 视频；视频见[视频理解 API](/api-capabilities/video-understanding) |
| 本页示例模型 | `gemini-3.8-flash` |

如果应用使用 OpenAI SDK 的 `messages` 格式，请参阅 [OpenAI 协议](/api-reference/chat-completions)；两种协议的请求体与返回字段不同。

## 请求地址与认证

```text theme={null}
POST https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent
```

模型 ID 位于 URL 中。[模型与价格总表](/models)中「兼容端点」包含 Gemini 的模型可以使用本协议，调用权限取决于令牌分组。

在[令牌管理](https://api.laozhang.ai/token)创建 API Key，计费模式选择按量优先（推荐）或按量计费，然后写入环境变量：

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
```

JSON 请求设置 `Content-Type: application/json`。认证可以使用 `Authorization: Bearer`，也可以使用 Google SDK 采用的 `x-goog-api-key`，两者任选其一。

```bash theme={null}
curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "请只回复：连接成功"}]
    }]
  }'
```

使用 API Key 认证头时，将上面的 Bearer 行替换为：

```bash theme={null}
-H "x-goog-api-key: $LAOZHANG_API_KEY"
```

原生接口使用 AI Studio 风格的 `v1beta` 路径，不需要 Vertex AI 的 project/location/publisher 路径，也不要在域名后增加 `/v1`。

## 使用 Google Gen AI Python SDK

先安装依赖：

```bash theme={null}
python -m pip install google-genai
```

`base_url` 设置为域名根路径，`api_version` 设置为 `v1beta`，SDK 会拼接模型路径。`timeout` 的单位是毫秒。

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

client = genai.Client(
    api_key=os.environ["LAOZHANG_API_KEY"],
    http_options={
        "base_url": "https://api.laozhang.ai",
        "api_version": "v1beta",
        "timeout": 120_000,
    },
)
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="请只回复：连接成功",
)
print(response.text)
```

`response.text` 适合读取文本答案。需要保留完整消息时，使用 `response.candidates`，其中可能包含多个内容块。

## 请求内容

| 字段 | 说明 |
| - | - |
| `contents` | 必需；按顺序排列的消息数组 |
| `contents[].role` | 用户消息用 `user`，模型回复用 `model` |
| `contents[].parts` | 一条消息中的内容块数组 |
| `parts[].text` | 文本内容 |
| `parts[].inlineData` | 图片、PDF、音频、视频等内联数据，包含 `mimeType` 与 Base64 `data` |
| `parts[].fileData` | 通过链接引用的媒体，包含 `fileUri` 与 `mimeType` |
| `systemInstruction` | 系统指令，使用 `parts` 结构 |
| `generationConfig` | 生成配置；可用字段由模型决定 |

REST JSON 使用 `inlineData`、`mimeType` 等 camelCase 名称。Python SDK 类型通常使用 `inline_data`、`mime_type` 等 snake\_case 名称，不要将两套字段名混用。

## 读取候选结果

文本响应的主要结构如下：

```json theme={null}
{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{"text": "连接成功"}]
    },
    "finishReason": "STOP"
  }]
}
```

处理 REST 响应时，遍历候选项的 `content.parts`，合并其中的 `text`。`finishReason` 表示生成结束原因；没有候选项或没有文本时，同时检查 `promptFeedback` 和其他内容块。

支持图片输出的模型可能返回 `inlineData`，需要按 `mimeType` 解码保存；若 SDK 已将内容转为字节，不要再次 Base64 解码。用 Gemini 协议生成和编辑图片的模型与示例见 [Nano Banana API 总览](/api-capabilities/nano-banana-image)。

`usageMetadata` 提供请求使用量信息，费用可在[调用日志](/faq/call-logs)查看。缺少某个统计字段不表示对应使用量或费用为零。

## 流式输出

需要边生成边返回时，把方法换成 `streamGenerateContent`，并加上查询参数 `alt=sse`，结果以 SSE 事件流返回：

```text theme={null}
POST https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse
```

请求体、事件格式与 SDK 用法见 [Google generateContent 文档](https://ai.google.dev/api/generate-content)。

## 发送图片内容

图片输入通过 `parts[].inlineData` 传递。使用此格式前，在对应模型说明中确认图片输入要求。以下示例把当前目录中的 `input.png` 编码为 JSON，请求模型描述图片。

先创建请求文件，只需 Python 标准库：

```python theme={null}
import base64
import json
from pathlib import Path

request = {
    "contents": [{
        "role": "user",
        "parts": [
            {"text": "请描述图片中的物体。"},
            {"inlineData": {
                "mimeType": "image/png",
                "data": base64.b64encode(
                    Path("input.png").read_bytes()
                ).decode("ascii"),
            }},
        ],
    }],
}
Path("gemini-request.json").write_text(
    json.dumps(request, ensure_ascii=False), encoding="utf-8"
)
```

再发送文件内容：

```bash theme={null}
curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @gemini-request.json
```

`mimeType` 必须与文件内容一致，`data` 只放 Base64 字符串，不包含 `data:image/png;base64,` 前缀。用 OpenAI 协议传图的写法见[图片理解 API](/api-capabilities/vision-understanding)。

## 发送 PDF 和音频

PDF 和音频同样放在 `inlineData` 中，写法与图片相同，只需把 `mimeType` 换成文件的实际类型：

| 文件 | `mimeType` | 可以做什么 |
| - | - | - |
| PDF | `application/pdf` | 读取所有页面的内容，回答跨页问题 |
| MP3 音频 | `audio/mp3` | 转写中英文语音，总结内容，回答与音频有关的问题 |

以下示例读取当前目录中的 `invoice.pdf`，换成音频时把文件名改为 `audio.mp3`、`mimeType` 改为 `audio/mp3`，并修改提示词：

<Tabs>
  <Tab title="cURL">
    先生成请求文件：

    ```python theme={null}
    import base64
    import json
    from pathlib import Path

    request = {
        "contents": [{
            "role": "user",
            "parts": [
                {"inlineData": {
                    "mimeType": "application/pdf",
                    "data": base64.b64encode(
                        Path("invoice.pdf").read_bytes()
                    ).decode("ascii"),
                }},
                {"text": "这张发票的编号、应付总额和到期日分别是什么？"},
            ],
        }],
    }
    Path("gemini-file-request.json").write_text(
        json.dumps(request, ensure_ascii=False), encoding="utf-8"
    )
    ```

    再发送文件内容：

    ```bash theme={null}
    curl --fail-with-body --max-time 120 \
      "https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent" \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -H "Content-Type: application/json" \
      --data-binary @gemini-file-request.json
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    import os
    from pathlib import Path
    from google import genai
    from google.genai import types

    client = genai.Client(
        api_key=os.environ["LAOZHANG_API_KEY"],
        http_options={
            "base_url": "https://api.laozhang.ai",
            "api_version": "v1beta",
            "timeout": 120_000,
        },
    )
    response = client.models.generate_content(
        model="gemini-3.8-flash",
        contents=[
            types.Part.from_bytes(
                data=Path("audio.mp3").read_bytes(),
                mime_type="audio/mp3",
            ),
            "逐字转写这段音频，再用一句话总结。",
        ],
    )
    print(response.text)
    ```
  </Tab>
</Tabs>

音频按 token 计费，`usageMetadata.promptTokensDetails` 中列为 `AUDIO`。只需要把音频转成文字、不需要模型再做理解时，也可以用[音频转录接口](/api-capabilities/audio-transcription)。

## 发送视频内容

MP4 视频同样放在 `inlineData` 中，`mimeType` 写 `video/mp4`。已有公网地址或公开 YouTube 视频时，改用 `fileData` 传链接。模型会同时读取画面和音轨：

```json theme={null}
{"inlineData": {"mimeType": "video/mp4", "data": "<Base64 数据>"}}
```

```json theme={null}
{"fileData": {"fileUri": "https://www.youtube.com/watch?v=9hE5-98ZeCg", "mimeType": "video/mp4"}}
```

完整示例和常用场景见[视频理解 API](/api-capabilities/video-understanding)，包括：

* 上传本地视频与分析视频链接；
* 按时间戳拆分章节、输出结构化 JSON；
* 用 `videoMetadata` 截取片段、调整抽帧率；
* 多视频对比、流式输出和用 OpenAI SDK 调用。

## 保留多轮消息

多轮对话按“用户输入 → 模型回复 → 新用户输入”的顺序放入 `contents`，模型角色写作 `model`，不是 `assistant`。保留服务返回的完整模型内容块；存在 `thoughtSignature` 时原样回传，不要只保存可见文本或自行构造签名。

对于支持函数调用的模型，`functionCall` 表示模型请求调用函数，应用执行后通过 `functionResponse` 返回结果。工具声明、结构化输出和思考配置按对应模型文档设置，不要直接套用其他模型的字段和值。

## 错误处理

| 现象 | 检查方法 |
| - | - |
| 401 | 核对认证头和模型 API Key，勿使用账号 AccessToken |
| 400 | 检查消息角色、内容块、MIME、Base64 与生成配置 |
| 404 / 模型不可用 | 核对 `v1beta` 路径、模型 ID 和令牌分组 |
| 400，提示 Cannot fetch content from the provided URL | 视频链接无法直接下载；换成公开直链，或改用 `inlineData` 上传 |
| 上传文件时返回网页或 404 | 不提供 File API；改用 `inlineData` 或 `fileData` 链接 |
| 有响应但没有文本 | 查看候选项、结束原因、拦截信息和非文本内容块 |
| SDK 失败而 cURL 正常 | 比较实际请求地址与认证头，确认 SDK 的 Base URL 不含 `/v1` |

超时或服务错误时，先查看[调用日志](/faq/call-logs)，再决定是否重试。向支持团队提供模型 ID、请求时间及脱敏错误信息即可，不要提供完整密钥。

## 常见问题

### OpenAI 兼容接口能传哪些媒体？

Gemini 模型在 `/v1/chat/completions` 中的表现：

* 图片：用 `image_url` 传 URL 或 Base64 data URL，见[图片理解 API](/api-capabilities/vision-understanding)。
* 视频：用 `video_url` 传 Base64 data URL，见[视频理解 API：用 OpenAI SDK 调用](/api-capabilities/video-understanding#用-openai-sdk-调用)。
* PDF（`file` 内容块）和音频（`input_audio` 内容块）会被忽略，请求仍返回 200，模型可能在没看到文件的情况下作答。请改用本页的 `inlineData`。

### Gemini 模型能用 Responses API 吗？

不能。Gemini 模型发到 `/v1/responses` 会返回 400。使用 OpenAI SDK 时调用 Chat Completions，需要 PDF、音频、视频或视频链接时使用本页的原生接口。

### 支持 Google File API 吗？

不支持，以下写法都不可用：

* `/upload/v1beta/files` 上传接口；
* `files/...` 形式的文件引用；
* SDK 的 `client.files.upload()`。

本地文件用 `inlineData` 发送，公网视频用 `fileData` 传链接。

### 媒体输入如何计费？

Gemini 文本模型按 token 计费。图片、PDF、音频和视频都换算为输入 token，`usageMetadata.promptTokensDetails` 按 `IMAGE`、`AUDIO`、`VIDEO` 等类型列出数量。单价见[模型与价格总表](/models)，每次请求的实际扣费见[调用日志](/faq/call-logs)。

### Veo 和 Nano Banana Pro 能用原生接口吗？

* **Nano Banana Pro**：`gemini-3-pro-image` 支持原生 `generateContent`，示例见 [Nano Banana Pro 图片生成](/api-capabilities/nano-banana-pro-image)。
* **Veo**：截至 2026 年 9 月 28 日不在公开模型目录中，原生 `predictLongRunning` 请求会返回无可用渠道。视频生成可使用 [Wan 2.7](/api-capabilities/wan-video-generation) 或 [Seedance 2.0](/api-capabilities/seedance2-video-generation)。

### Google 模型走 AI Studio 还是 Vertex？

走 AI Studio。老张API的 Gemini 文本模型和 Nano Banana 图像模型都通过 Google 的 Gemini API（AI Studio）线路调用，不走 Vertex AI。因此：

* 模型 ID、停止日期和内容安全策略以 [Gemini API 文档](https://ai.google.dev/gemini-api/docs)为准，例如 [Google 弃用页](https://ai.google.dev/gemini-api/docs/deprecations)；
* 请求使用 AI Studio 风格的 `v1beta` 路径，不需要 Vertex 的 project、location 参数；
* 怀疑上游故障时，先查看 [AI Studio 状态页](https://aistudio.google.com/status)是否有 Gemini API 的故障通报。

## 相关文档

* [视频理解 API](/api-capabilities/video-understanding)
* [Google generateContent 请求与响应](https://ai.google.dev/api/generate-content)
* [Google Gen AI Python SDK](https://googleapis.github.io/python-genai/)
* [模型与价格总表](/models)
* [模型可用性与权限](/faq/model-availability)
* [OpenAI 协议](/api-reference/chat-completions)
* [Claude 协议](/api-reference/claude)


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