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

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

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

如果应用使用 OpenAI SDK 的 messages 格式，请参阅 OpenAI 协议；两种协议的请求体与返回字段不同。

请求地址与认证

POST https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent

模型 ID 位于 URL 中。模型与价格总表中「兼容端点」包含 Gemini 的模型可以使用本协议，调用权限取决于令牌分组。在令牌管理创建 API Key，计费模式选择按量优先（推荐）或按量计费，然后写入环境变量：

export LAOZHANG_API_KEY="替换为你的老张API密钥"

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

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 行替换为：

-H "x-goog-api-key: $LAOZHANG_API_KEY"

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

使用 Google Gen AI Python SDK

先安装依赖：

python -m pip install google-genai

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

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 名称，不要将两套字段名混用。

读取候选结果

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

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{"text": "连接成功"}]
    },
    "finishReason": "STOP"
  }]
}

处理 REST 响应时，遍历候选项的 content.parts，合并其中的 text。finishReason 表示生成结束原因；没有候选项或没有文本时，同时检查 promptFeedback 和其他内容块。支持图片输出的模型可能返回 inlineData，需要按 mimeType 解码保存；若 SDK 已将内容转为字节，不要再次 Base64 解码。用 Gemini 协议生成和编辑图片的模型与示例见 Nano Banana API 总览。 usageMetadata 提供请求使用量信息，费用可在调用日志查看。缺少某个统计字段不表示对应使用量或费用为零。

流式输出

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

POST https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse

请求体、事件格式与 SDK 用法见 Google generateContent 文档。

发送图片内容

图片输入通过 parts[].inlineData 传递。使用此格式前，在对应模型说明中确认图片输入要求。以下示例把当前目录中的 input.png 编码为 JSON，请求模型描述图片。先创建请求文件，只需 Python 标准库：

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"
)

再发送文件内容：

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。

发送 PDF 和音频

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

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

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

cURL
Python SDK

先生成请求文件：

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"
)

再发送文件内容：

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

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)

音频按 token 计费，usageMetadata.promptTokensDetails 中列为 AUDIO。只需要把音频转成文字、不需要模型再做理解时，也可以用音频转录接口。

发送视频内容

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

{"inlineData": {"mimeType": "video/mp4", "data": "<Base64 数据>"}}

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

完整示例和常用场景见视频理解 API，包括：

上传本地视频与分析视频链接；
按时间戳拆分章节、输出结构化 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	图片或视频链接无法直接下载；换成无需登录的公开直链，并确认站点的 `robots.txt` 没有禁止抓取，或改用 `inlineData` 上传
413	请求体过大：整个请求不要超过 20MB，大文件改用 `fileData` 传链接
上传文件时返回网页或 404	不提供 File API；改用 `inlineData` 或 `fileData` 链接
有响应但没有文本	查看候选项、结束原因、拦截信息和非文本内容块
SDK 失败而 cURL 正常	比较实际请求地址与认证头，确认 SDK 的 Base URL 不含 `/v1`

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

常见问题

Gemini API 多少钱？需要 Google 账号吗？

不需要 Google 账号或 AI Studio API Key，用老张API密钥即可调用；Gemini 文本模型预付余额、按 token 计费。2026 年 10 月 14 日公开价格配置中，常用模型每 1M tokens：

gemini-4-argon：输入 $2，输出 $10
gemini-3.8-flash：输入 $0.75，输出 $3.75
gemini-2.5-flash：输入 $0.3，输出 $2.4

其余 Gemini 模型及长上下文分档见模型与价格总表，每次请求的实际扣费见调用日志。平台不限制并发、不限速，429 来自上游容量，见并发与 429。

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

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

图片：用 image_url 传 URL 或 Base64 data URL，见图片理解 API。
视频：用 video_url 传 Base64 data URL，见视频理解 API：用 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 等类型列出数量。单价见模型与价格总表，每次请求的实际扣费见调用日志。

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

Nano Banana Pro：gemini-3-pro-image 支持原生 generateContent，示例见 Nano Banana Pro 图片生成。
Veo：截至 2026 年 9 月 28 日不在公开模型目录中，原生 predictLongRunning 请求会返回无可用渠道。视频生成可使用 Wan 2.7 或 Seedance 2.0。

Google 模型走 AI Studio 还是 Vertex？

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

模型 ID、停止日期和内容安全策略以 Gemini API 文档为准，例如 Google 弃用页；
请求使用 AI Studio 风格的 v1beta 路径，不需要 Vertex 的 project、location 参数；
怀疑上游故障时，先查看 AI Studio 状态页是否有 Gemini API 的故障通报。

开始使用

图像生成与编辑 API

视频生成 API

文本 API

多模态与音频 API

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

请求地址与认证

使用 Google Gen AI Python SDK

请求内容

读取候选结果

流式输出

发送图片内容

发送 PDF 和音频

发送视频内容

保留多轮消息

错误处理

常见问题

Gemini API 多少钱？需要 Google 账号吗？

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

Gemini 模型能用 Responses API 吗？

支持 Google File API 吗？

媒体输入如何计费？

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

Google 模型走 AI Studio 还是 Vertex？

相关文档

​请求地址与认证

​使用 Google Gen AI Python SDK

​请求内容

​读取候选结果

​流式输出

​发送图片内容

​发送 PDF 和音频

​发送视频内容

​保留多轮消息

​错误处理

​常见问题

​Gemini API 多少钱？需要 Google 账号吗？

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

​Gemini 模型能用 Responses API 吗？

​支持 Google File API 吗？

​媒体输入如何计费？

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

​Google 模型走 AI Studio 还是 Vertex？

​相关文档

请求地址与认证

使用 Google Gen AI Python SDK

请求内容

读取候选结果

流式输出

发送图片内容

发送 PDF 和音频

发送视频内容

保留多轮消息

错误处理

常见问题

Gemini API 多少钱？需要 Google 账号吗？

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

Gemini 模型能用 Responses API 吗？

支持 Google File API 吗？

媒体输入如何计费？

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

Google 模型走 AI Studio 还是 Vertex？

相关文档