Skip to content

Gemini โ€‹

Updated

Endpoint: https://mmu.vod-qcloud.com/v1Authentication: VOD ApiToken / Bearer

Gemini is a multimodal understanding and text generation model that accepts text, image, video, and audio input and returns text or structured results. It is called through an OpenAI-compatible API, supporting the Chat Completions and Messages protocols with JSON / SSE streaming responses.

Basic Information โ€‹

ItemValue
Call addresshttps://mmu.vod-qcloud.com
AuthenticationVOD Application-issued ApiToken / Bearer
OutputText / structured response
Response methodJSON / SSE

Supported Protocols โ€‹

SpecificationPathTarget
Chat CompletionsPOST /v1/chat/completionsAll models below
MessagesPOST /v1/messagesAll models below

The model IDs below use the corresponding specification. Authentication and common fields follow API Reference.

Sampling Options โ€‹

Applied in common to all models listed in this document.

ParameterSetting
temperatureConfigurable
top_pConfigurable

temperature specifies the sampling temperature, and top_p specifies the cumulative probability range. Adjust with one method as the focus.

Reasoning Settings by Version โ€‹

Model IDReasoning text controlHidden value
gemini-3.8-flashthinking_enabledfalse
gemini-3.7-flashthinking_enabledfalse
gemini-3.6-flashthinking_enabledfalse
gemini-3.5-flash-liteReasoning text not returnedโ€”
gemini-3.5-flashthinking_enabledfalse
gemini-3.1-pro-previewthinking_enabledfalse
gemini-3.1-flash-lite-previewReasoning text not returnedโ€”
gemini-3.1-flash-liteReasoning text not returnedโ€”
gemini-3-flash-previewthinking_enabledfalse
gemini-2.5-prothinking_enabledfalse
gemini-2.5-flashthinking_enabledfalse

Based on Chat Completions. Distinguish between the reasoning text return and whether the internal reasoning computation is enabled according to thinking_enabled. Read the reasoning content from reasoning_content and the final answer from content, and check the returned usage for the internal reasoning cost.

Request Parameters โ€‹

ParameterRequiredTypeDescription
modelRequiredStringA model ID from the per-version options table
messagesRequiredArrayConversation input for Chat Completions / Messages
max_tokensOptionalIntegerGeneration limit for Chat Completions / Messages. Required in Messages
streamOptionalBooleantrue: SSE / false: JSON

Request Example โ€‹

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

Response โ€‹

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
}

Response โ€‹

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-compatible Chat Completions Integration โ€‹

In https://text-aigc.vod-qcloud.com/v1/chat/completions as well, via VOD ApiToken you can use Gemini's JSON response and SSE streaming. Set the OpenAI Python SDK's base_url to https://text-aigc.vod-qcloud.com/v1. Do not mix this address's Chat Completions example with the existing mmu.vod-qcloud.com Messages path.

Reusing the Authentication Token โ€‹

Token issuance follows the call preparation in API Reference. For CreateAigcApiToken, specify the VOD Application's SubAppId, and store the response's ApiToken in a server-side secret store. SecretId and SecretKey are the CAM credentials used for token issuance, not Bearer tokens.

An issued key is valid indefinitely, so do not reissue it on every request or every time the server restarts. Reuse the managed key across multiple server instances as well, and perform key replacement through an explicit rotation procedure. If 401, confirm the token value, whether it was deleted, permissions, and the call address, and resolve the cause. Do not automatically generate a new key on every error.

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": "Say hello in one sentence."}],
    max_tokens=2048,
)
print(response.choices[0].message.content)
if response.usage is not None:
    print(response.usage.model_dump)

It supports Chat Completions-format integration, but this does not mean that all OpenAI models, options, and extension fields behave identically. The model ID, multimodal input types, and reasoning options follow the specification of the model you use.

SSE and Usage Collection โ€‹

Specify stream=true and stream_options.include_usage=true together. The answer is distinguished by delta.content, and the reasoning text by delta.reasoning_content. Handle role-only events, termination events, and usage events where choices is empty.

python
stream = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
    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 handles SSE and [DONE]. If you implement your own parser, first check for HTTP errors, then gather and parse the data: lines of the SSE events separated by blank lines. [DONE] is not JSON, so handle its termination separately, and also handle error events in the middle of the response.

Usage fieldMeaning
usage.prompt_tokensInput tokens
usage.completion_tokensGenerated tokens including reasoning
usage.total_tokensTotal tokens
usage.prompt_tokens_details.cached_tokensCached tokens within the input
usage.completion_tokens_details.reasoning_tokensReasoning tokens within the generated tokens

Cached and reasoning tokens are breakdown items, so do not add them back to the input and generated tokens. The breakdown fields may be absent or null. Store usage events when received and aggregate them once per request. If the stream is cut off and no usage is received, do not finalize it as 0. Amounts are calculated separately by each model's unit price and discount and cache rates.

Reasoning Options and Operational Handling โ€‹

The allowed values of reasoning_effort differ by model and version. Do not apply none / minimal / low / medium / high / max in common to all Gemini models. Do not put Google-native thinkingConfig.thinkingBudget directly into the Chat Completions body. Do not judge that the reasoning computation is disabled based only on a successful request or the absence of reasoning text.

SituationHandling
401Confirm the key, permissions, and host. Do not reissue unconditionally
429If Retry-After is present, apply it first and use exponential backoff with jitter
5xx / timeoutRetry count and overall time limit. Even on timeout, the upstream service may have proceeded with generation
Connection closed during stream receptionDo not automatically replay the received answer from the beginning; handle it as a request failure or partial response
Error logsRecord centered on the HTTP status, request ID, and error code. Mask sensitive information such as tokens, conversations, and media URLs

The backend does not pass the Bearer token to the client. When relaying SSE as-is, prevent buffering and close the upstream stream when the client connection ends. Do not mix debug events of a different schema into a path that uses the OpenAI SDK as a client.

Special Settings โ€‹

Gemini supports text / image / video / audio input. Use the image_url Part for images and the video_url Part for video. Multimodal input also uses the same authentication and path as text calls.

The reasoning result and the final answer are distinguished by reasoning_content and content. The thought_signature of a tool-call response is also preserved in the next conversation request.

Additional Options by Version โ€‹

Reasoning Effort โ€‹

Versionreasoning_effortDefault
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 and above cannot turn off default reasoning. Do not mix thinking_enabled=false into the common examples.

For video / audio input, see Gemini Media Understanding.

Video and Audio Input โ€‹

Basic Information โ€‹

ItemValue
Modelgemini-3.8-flash
InputText / Image / Video / Audio
OutputText
Video Inputvideo_url.url, up to 10 per request
StreamingSupported

Request Parameters โ€‹

ParameterRequiredTypeDescription
modelRequiredStringgemini-3.8-flash
messagesRequiredArrayQuestion and video Part
max_tokensOptionalIntegerMaximum generated tokens including reasoning
reasoning_effortOptionalStringlow / medium / high
temperatureOptionalNumberGeneration randomness
streamOptionalBooleanWhether SSE streaming

Request Example โ€‹

json
{
  "model": "gemini-3.8-flash",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Describe the main subject and its motion in the video in one sentence."
        },
        {
          "type": "video_url",
          "video_url": {
            "url": "https://example.com/video.mp4"
          }
        }
      ]
    }
  ],
  "max_tokens": 2048,
  "reasoning_effort": "medium",
  "temperature": 0.7,
  "stream": false
}

Special Settings โ€‹

Video Segments and Sampling โ€‹

Gemini's extra_content.google supports fps / media_resolution / start_offset / end_offset. The time offset is a {seconds, nanos} structure. Raising the sampling frequency captures more subtle motion but also increases input tokens.

Reasoning and Output Length โ€‹

Reasoning tokens are also included in max_tokens. Compared with video analysis, if the token limit is too small, the final description may end midway. For per-version reasoning effort and the full model IDs, see Gemini Text.

Response Example โ€‹

json
{
  "object": "chat.completion",
  "model": "gemini-3.8-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A red sports car drives forward along a wet city street."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 923,
    "completion_tokens": 220,
    "total_tokens": 1143
  }
}

Built with VitePress ยท Deployed on Tencent EdgeOne Pages