Gemini โ
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 โ
| Item | Value |
|---|---|
| Call address | https://mmu.vod-qcloud.com |
| Authentication | VOD Application-issued ApiToken / Bearer |
| Output | Text / structured response |
| Response method | JSON / SSE |
Supported Protocols โ
| Specification | Path | Target |
|---|---|---|
| Chat Completions | POST /v1/chat/completions | All models below |
| Messages | POST /v1/messages | All 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.
| Parameter | Setting |
|---|---|
temperature | Configurable |
top_p | Configurable |
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 ID | Reasoning text control | Hidden value |
|---|---|---|
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 | Reasoning text not returned | โ |
gemini-3.5-flash | thinking_enabled | false |
gemini-3.1-pro-preview | thinking_enabled | false |
gemini-3.1-flash-lite-preview | Reasoning text not returned | โ |
gemini-3.1-flash-lite | Reasoning text not returned | โ |
gemini-3-flash-preview | thinking_enabled | false |
gemini-2.5-pro | thinking_enabled | false |
gemini-2.5-flash | thinking_enabled | false |
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 โ
| Parameter | Required | Type | Description |
|---|---|---|---|
model | Required | String | A model ID from the per-version options table |
messages | Required | Array | Conversation input for Chat Completions / Messages |
max_tokens | Optional | Integer | Generation limit for Chat Completions / Messages. Required in Messages |
stream | Optional | Boolean | true: SSE / false: JSON |
Request Example โ
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"
}Response โ
{
"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
}Response โ
{
"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 โ
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.
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 field | Meaning |
|---|---|
usage.prompt_tokens | Input tokens |
usage.completion_tokens | Generated tokens including reasoning |
usage.total_tokens | Total tokens |
usage.prompt_tokens_details.cached_tokens | Cached tokens within the input |
usage.completion_tokens_details.reasoning_tokens | Reasoning 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.
| Situation | Handling |
|---|---|
401 | Confirm the key, permissions, and host. Do not reissue unconditionally |
429 | If Retry-After is present, apply it first and use exponential backoff with jitter |
5xx / timeout | Retry count and overall time limit. Even on timeout, the upstream service may have proceeded with generation |
| Connection closed during stream reception | Do not automatically replay the received answer from the beginning; handle it as a request failure or partial response |
| Error logs | Record 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 โ
| Version | reasoning_effort | Default |
|---|---|---|
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 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 โ
| Item | Value |
|---|---|
| Model | gemini-3.8-flash |
| Input | Text / Image / Video / Audio |
| Output | Text |
| Video Input | video_url.url, up to 10 per request |
| Streaming | Supported |
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
model | Required | String | gemini-3.8-flash |
messages | Required | Array | Question and video Part |
max_tokens | Optional | Integer | Maximum generated tokens including reasoning |
reasoning_effort | Optional | String | low / medium / high |
temperature | Optional | Number | Generation randomness |
stream | Optional | Boolean | Whether SSE streaming |
Request Example โ
{
"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 โ
{
"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
}
}