跳到内容

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 CompletionsPOST /v1/chat/completions下方所有模型
MessagesPOST /v1/messages下方所有模型

下方的模型 ID 使用相应规格。认证与公共字段遵循 API Reference。

采样选项 ​

对本文档列出的所有模型通用。

参数设置
temperature可设置
top_p可设置

temperature 指定采样温度,top_p 指定累积概率范围。请以其中一种方式为主进行调整。

各版本推理设置 ​

模型 ID推理文本控制隐藏值
gemini-3.8-flashthinking_enabledfalse
gemini-3.7-flashthinking_enabledfalse
gemini-3.6-flashthinking_enabledfalse
gemini-3.5-flash-lite不返回推理文本—
gemini-3.5-flashthinking_enabledfalse
gemini-3.1-pro-previewthinking_enabledfalse
gemini-3.1-flash-lite-preview不返回推理文本—
gemini-3.1-flash-lite不返回推理文本—
gemini-3-flash-previewthinking_enabledfalse
gemini-2.5-prothinking_enabledfalse
gemini-2.5-flashthinking_enabledfalse

以 Chat Completions 为准。请区分 thinking_enabled 对应的推理文本返回与内部推理运算的启用与否。推理内容从 reasoning_content 读取,最终答复从 content 读取,内部推理成本请确认返回的 usage。

请求参数 ​

参数必填类型说明
model必填String各版本选项表中的模型 ID
messages必填ArrayChat Completions / Messages 的对话输入
max_tokens可选IntegerChat Completions / Messages 的生成上限。在 Messages 中为必填
stream可选Booleantrue:SSE / false:JSON

请求示例 ​

Chat Completions ​

json
{
  "model": "gemini-3.8-flash",
  "messages": [
    {
      "role": "user",
      "content": "Reply with exactly OK and nothing else."
    }
  ],
  "max_tokens": 2048,
  "stream": false,
  "reasoning_effort": "low"
}

响应 ​

json
{
  "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 ​

json
{
  "model": "gemini-3.8-flash",
  "messages": [
    {
      "role": "user",
      "content": "Reply with exactly OK and nothing else."
    }
  ],
  "max_tokens": 512,
  "stream": false
}

响应 ​

json
{
  "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 ​

python
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 为空的用量事件均需处理。

python
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 Flashlow / medium / highmedium
3.6 / 3.5 Flashminimal / low / medium / highmedium
3.5 / 3.1 Flash Liteminimal / low / medium / highminimal
3.1 Prolow / medium / highhigh

Gemini 3 及以上无法关闭默认推理。请勿将 thinking_enabled=false 混入公共示例。

视频 / 音频输入请参考 Gemini Media Understanding。

视频及音频输入 ​

基本信息 ​

项目取值
模型gemini-3.8-flash
输入文本 / 图片 / 视频 / 音频
输出文本
视频输入video_url.url,每次请求最多 10 个
流式支持

请求参数 ​

参数必填类型说明
model必填Stringgemini-3.8-flash
messages必填Array问题与视频 Part
max_tokens可选Integer含推理的最大生成令牌
reasoning_effort可选Stringlow / medium / high
temperature可选Number生成随机性
stream可选Boolean是否 SSE 流式

请求示例 ​

json
{
  "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。

响应示例 ​

json
{
  "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
  }
}

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages