Gemini
Endpoint: https://mmu.vod-qcloud.com/v1认证: VOD ApiToken / Bearer
Gemini 是多模态理解与文本生成模型,支持文本、图片、视频、音频输入,并以文本或结构化结果返回。通过兼容 OpenAI 的接口调用,支持 Chat Completions 与 Messages 协议及 JSON / SSE 流式响应。
基本信息
| 项目 | 取值 |
|---|---|
| 调用地址 | https://mmu.vod-qcloud.com |
| 认证 | VOD 应用签发的 ApiToken / Bearer |
| 输出 | 文本 / 结构化响应 |
| 响应方式 | JSON / SSE |
支持的协议
| 规格 | 路径 | 对象 |
|---|---|---|
| Chat Completions | POST /v1/chat/completions | 下方所有模型 |
| Messages | POST /v1/messages | 下方所有模型 |
下方的模型 ID 使用相应规格。认证与公共字段遵循 API Reference。
采样选项
对本文档列出的所有模型通用。
| 参数 | 设置 |
|---|---|
temperature | 可设置 |
top_p | 可设置 |
temperature 指定采样温度,top_p 指定累积概率范围。请以其中一种方式为主进行调整。
各版本推理设置
| 模型 ID | 推理文本控制 | 隐藏值 |
|---|---|---|
gemini-3.8-flash | thinking_enabled | false |
gemini-3.7-flash | thinking_enabled | false |
gemini-3.6-flash | thinking_enabled | false |
gemini-3.5-flash-lite | 不返回推理文本 | — |
gemini-3.5-flash | thinking_enabled | false |
gemini-3.1-pro-preview | thinking_enabled | false |
gemini-3.1-flash-lite-preview | 不返回推理文本 | — |
gemini-3.1-flash-lite | 不返回推理文本 | — |
gemini-3-flash-preview | thinking_enabled | false |
gemini-2.5-pro | thinking_enabled | false |
gemini-2.5-flash | thinking_enabled | false |
以 Chat Completions 为准。请区分 thinking_enabled 对应的推理文本返回与内部推理运算的启用与否。推理内容从 reasoning_content 读取,最终答复从 content 读取,内部推理成本请确认返回的 usage。
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
model | 必填 | String | 各版本选项表中的模型 ID |
messages | 必填 | Array | Chat Completions / Messages 的对话输入 |
max_tokens | 可选 | Integer | Chat Completions / Messages 的生成上限。在 Messages 中为必填 |
stream | 可选 | Boolean | true:SSE / false:JSON |
请求示例
Chat Completions
{
"model": "gemini-3.8-flash",
"messages": [
{
"role": "user",
"content": "Reply with exactly OK and nothing else."
}
],
"max_tokens": 2048,
"stream": false,
"reasoning_effort": "low"
}响应
{
"id": "01a0de40-61b3-783f-afbb-eb22dda5c73b",
"object": "chat.completion",
"model": "gemini-3.8-flash",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "OK",
"extra_content": {
"google": {
"thought_signature": "AY89a1+xrShbzLWCg3rEDSySoUYNiYV2NT1Spwa10pKOomiWkE/4JygxGm5cFuuesYhb5cXvKbkL3D/+85niNN/dJ+cYS1O2XguW/Kc0Ufu9FGdUMg=="
}
}
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 8,
"prompt_tokens_details": {
"audio_tokens": 0,
"cached_tokens": 0,
"text_tokens": 8
},
"prompt_cached_tokens_details": {
"audio_tokens": 0
},
"completion_tokens": 1,
"completion_tokens_details": {
"accepted_prediction_tokens": 0,
"audio_tokens": 0,
"reasoning_tokens": 0,
"rejected_prediction_tokens": 0
},
"total_tokens": 9
}
}Messages
{
"model": "gemini-3.8-flash",
"messages": [
{
"role": "user",
"content": "Reply with exactly OK and nothing else."
}
],
"max_tokens": 512,
"stream": false
}响应
{
"id": "01a0de33-1cf6-7971-8721-674043b69557",
"model": "gemini-3.8-flash",
"type": "message",
"role": "assistant",
"content": [
{
"text": "OK",
"type": "text"
}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 8,
"output_tokens": 111
}
}OpenAI 兼容 Chat Completions 对接
在 https://text-aigc.vod-qcloud.com/v1/chat/completions 中也可通过 VOD ApiToken 使用 Gemini 的 JSON 响应与 SSE 流式。OpenAI Python SDK 的 base_url 设置为 https://text-aigc.vod-qcloud.com/v1。请勿将该地址的 Chat Completions 示例与既有 mmu.vod-qcloud.com 的 Messages 路径混用。
认证令牌复用
令牌签发遵循 API Reference 的调用准备。请指定用于 CreateAigcApiToken 的 VOD 应用的 SubAppId,并将响应的 ApiToken 保存在服务端密钥存储中。SecretId 与 SecretKey 是用于令牌签发的 CAM 凭证,而非 Bearer 令牌。
签发的密钥无限期有效,因此请勿在每次请求或服务器每次重启时重新签发。多个服务器实例也应复用受管理的密钥,密钥更替应通过显式的轮换流程执行。若 401,请确认令牌值、是否已删除、权限及调用地址并解决原因。请勿在每次出错时自动生成新密钥。
Python SDK
import os
from openai import OpenAI
client = OpenAI(
base_url="https://text-aigc.vod-qcloud.com/v1",
api_key=os.environ["VOD_API_TOKEN"],
timeout=120.0,
max_retries=0,
)
response = client.chat.completions.create(
model="gemini-2.5-flash",
messages=[{"role": "user", "content": "用一句话打个招呼。"}],
max_tokens=2048,
)
print(response.choices[0].message.content)
if response.usage is not None:
print(response.usage.model_dump)虽然支持 Chat Completions 格式的对接,但并不意味着所有 OpenAI 模型、选项与扩展字段都有相同行为。模型 ID、多模态输入种类、推理选项遵循所用模型的规格。
SSE 与用量收集
请同时指定 stream=true 与 stream_options.include_usage=true。答复以 delta.content 区分,推理文本以 delta.reasoning_content 区分。仅含角色的事件、结束事件、choices 为空的用量事件均需处理。
stream = client.chat.completions.create(
model="gemini-2.5-flash",
messages=[{"role": "user", "content": "用一句话打个招呼。"}],
max_tokens=2048,
stream=True,
stream_options={"include_usage": True},
)
usage = None
with stream:
for chunk in stream:
if chunk.usage is not None:
usage = chunk.usage.model_dump
for choice in chunk.choices or :
text = choice.delta.content
if text:
print(text, end="", flush=True)
if usage is not None:
print("\n[usage]", usage)SDK 会处理 SSE 与 [DONE]。若自行实现解析器,请先确认 HTTP 错误,并汇集以空行分隔的 SSE 事件的 data: 行后进行解析。[DONE] 不是 JSON,因此需单独做结束处理,响应中途的 error 事件也需处理。
| 用量字段 | 含义 |
|---|---|
usage.prompt_tokens | 输入令牌 |
usage.completion_tokens | 含推理的生成令牌 |
usage.total_tokens | 全部令牌 |
usage.prompt_tokens_details.cached_tokens | 输入中的缓存令牌 |
usage.completion_tokens_details.reasoning_tokens | 生成令牌中的推理令牌 |
缓存令牌与推理令牌属于明细,因此不要再加回输入令牌与生成令牌。明细字段可能缺失或为 null。用量事件在收到时保存,并按请求汇总一次。若流中断未能收到用量,请勿以 0 确定。金额按各模型单价与折扣、缓存费率单独计算。
推理选项与运维处理
reasoning_effort 的允许值因模型、版本而异。请勿将 none / minimal / low / medium / high / max 对所有 Gemini 模型通用。请勿将 Google 原生的 thinkingConfig.thinkingBudget 直接放入 Chat Completions 正文。请勿仅凭请求成功或推理文本缺失就判定推理运算已被禁用。
| 情况 | 处理 |
|---|---|
401 | 确认密钥、权限、主机。不要无条件重新签发 |
429 | 若有 Retry-After 则优先采用,并使用指数退避与抖动 |
5xx / 超时 | 重试次数与总时间限制。即使超时,上游服务也可能已在生成 |
| 流接收中连接中断 | 不自动从头重放已接收的答复,按请求失败、部分响应处理 |
| 错误日志 | 以 HTTP 状态、请求 ID、错误码为中心记录。令牌、对话、媒体 URL 等敏感信息脱敏 |
后端不会将 Bearer 令牌传给客户端。原样中继 SSE 时需防止缓冲,并在客户端连接中断时一并关闭上游流。请勿在以 OpenAI SDK 作为客户端的路径中混入其他 schema 的调试事件。
特殊设置
Gemini 支持文本 / 图片 / 视频 / 音频输入。图片使用 image_url Part,视频使用 video_url Part。多模态输入也使用与文本调用相同的认证与路径。
推理结果与最终答复以 reasoning_content 与 content 区分。工具调用响应的 thought_signature 在下一次对话请求中也需保留。
各版本附加选项
推理强度
| 版本 | reasoning_effort | 默认值 |
|---|---|---|
3.8 / 3.7 Flash | low / medium / high | medium |
3.6 / 3.5 Flash | minimal / low / medium / high | medium |
3.5 / 3.1 Flash Lite | minimal / low / medium / high | minimal |
3.1 Pro | low / medium / high | high |
Gemini 3 及以上无法关闭默认推理。请勿将 thinking_enabled=false 混入公共示例。
视频 / 音频输入请参考 Gemini Media Understanding。
视频及音频输入
基本信息
| 项目 | 取值 |
|---|---|
| 模型 | gemini-3.8-flash |
| 输入 | 文本 / 图片 / 视频 / 音频 |
| 输出 | 文本 |
| 视频输入 | video_url.url,每次请求最多 10 个 |
| 流式 | 支持 |
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
model | 必填 | String | gemini-3.8-flash |
messages | 必填 | Array | 问题与视频 Part |
max_tokens | 可选 | Integer | 含推理的最大生成令牌 |
reasoning_effort | 可选 | String | low / medium / high |
temperature | 可选 | Number | 生成随机性 |
stream | 可选 | Boolean | 是否 SSE 流式 |
请求示例
{
"model": "gemini-3.8-flash",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "用一句话描述视频中的主要主体及其动作。"
},
{
"type": "video_url",
"video_url": {
"url": "https://example.com/video.mp4"
}
}
]
}
],
"max_tokens": 2048,
"reasoning_effort": "medium",
"temperature": 0.7,
"stream": false
}特殊设置
视频区间与采样
Gemini 的 extra_content.google 支持 fps / media_resolution / start_offset / end_offset。时间偏移为 {seconds, nanos} 结构。提高采样频率能捕捉更多细微动作,但输入令牌也会增加。
推理与输出长度
推理令牌也包含在 max_tokens 内。相较于视频分析,若令牌上限过小,最终说明可能中途结束。各版本推理强度与全部模型 ID 请参考 Gemini Text。
响应示例
{
"object": "chat.completion",
"model": "gemini-3.8-flash",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "一辆红色跑车沿着湿漉漉的城市道路向前行驶。"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 923,
"completion_tokens": 220,
"total_tokens": 1143
}
}