Gemini Native Parameter Pass-Through
The platform uses a dual-track mechanism for the Gemini series: "OpenAI field standardization + Gemini native field pass-through" — native Gemini
GenerationConfigfields sent by the client (e.g.,topK/responseSchema/mediaResolution/thinkingConfig) are forwarded to the underlying Vertex AI; content moderation is configured viasafety_settings, which the platform maps to the Gemini API'ssafetySettings[].
Applicable Endpoints and Models
- Endpoint:
v1/chat/completions(Gemini native fields passed under the OpenAI-compatible protocol) - Applicable models: Refer to Model Catalog → Gemini.
- Official documentation: Gemini Thinking / Gemini SafetySetting / Vertex AI GenerationConfig
Pass-Through Mechanism
- OpenAI standard fields (
temperature/max_tokens/top_p, etc.): automatically mapped by the platform to the corresponding Gemini parameters. - Gemini native fields (
topK/responseSchema/responseMimeType/mediaResolution/thinkingConfig, etc.): passed through directly to the upstream without conversion. - Content moderation field:
safety_settingsis provided in the GeminiSafetySettingstructure; the platform maps it tosafetySettings[]when forwarding to the upstream.
The OpenAI Python SDK passes non-standard fields via extra_body; cURL places them directly at the top level of the request body; Java uses additionalBodyProperties; TypeScript requires as any to bypass type checking.
Gemini 4 Hydrogen
Use model: "turing/gemini-4-hydrogen" with POST /api/v1/chat/completions, as in the examples below.
- Set
thinkingConfig.thinkingLeveltoLOW,MEDIUM,HIGH, orXHIGH; the default isHIGH. Use the nativethinkingConfigfield forXHIGH; the current proxy does not mapreasoning_effort: "xhigh". Do not sendMINIMALorthinkingBudget. - Input, thinking, and output share 1,048,576 tokens. Each streaming or non-streaming response allows up to 65,536 output tokens, including thinking. Google long decodes (
continuation_token) are not exposed by this endpoint. - Omit sampling parameters. The proxy removes
temperature,top_p,top_k,n,frequency_penalty, andpresence_penaltybefore forwarding. - Only implicit caching is supported, starting at 4,096 input tokens. See cache usage and costs and the model catalog. Upstream cache-write controls and TTL billing begin on January 12, 2027; the platform does not currently expose them.
Source: Google release notes. Preserve thought signatures across tool-calling turns.
Gemini 4 Carbon
Use model: "turing/gemini-4-carbon" with POST /api/v1/chat/completions. Reuse the examples below with the Carbon model ID and a non-streaming max_tokens limit of 32,768.
- Use
thinkingConfig.thinkingLevel: "LOW" | "MEDIUM" | "HIGH"; the default isMEDIUM. Do not passMINIMALorthinkingBudget. - Input, thinking, and output share a 1,048,576-token window. A single request supports up to 65,536 output tokens when streaming, or 32,768 when non-streaming.
max_tokensincludes thinking tokens, so leave enough budget for the final answer. - Google long decode /
continuation_tokenis not integrated into this endpoint; the 1M context window is not a 1M single-response output allowance. - Omit sampling parameters:
temperature/top_p/top_kandn/frequency_penalty/presence_penaltyare removed before forwarding. Native fields still follow the upstream restrictions described below. - Caching is implicit only. See cache-hit verification and token charges. Use the model catalog for rates and the scheduled price change.
Upstream limits: Gemini 4 Carbon. For multi-turn tool calls, preserve thought signatures.
Common Pass-Through Fields
| Field | Type | Purpose |
|---|---|---|
topK | int | Gemini native sampling parameter |
topP | float | Also present in OpenAI; this is the Gemini naming |
presencePenalty | float | Gemini naming (OpenAI uses presence_penalty) |
frequencyPenalty | float | Gemini naming |
responseMimeType | string | "application/json" triggers JSON output |
responseSchema | object | JSON Schema; used with responseMimeType for structured output |
thinkingConfig.thinkingLevel | string | Gemini 3+ reasoning intensity: MINIMAL / LOW / MEDIUM / HIGH / XHIGH (Hydrogen) |
thinkingConfig.thinkingBudget | int | Gemini 2.5 thinking token soft cap (-1 for dynamic; 0 disables thinking output for Flash / Flash-Lite only) |
thinkingConfig.includeThoughts | bool | Whether to return a thinking summary (best-effort); not a toggle to enable/disable thinking |
mediaResolution | string | e.g., "MEDIA_RESOLUTION_HIGH"; affects image input resolution |
seed | int | Random seed (supported by some models) |
safety_settings[].category | string | Content moderation category, e.g., HARM_CATEGORY_HATE_SPEECH |
safety_settings[].threshold | string | Block threshold, e.g., BLOCK_LOW_AND_ABOVE |
Examples
Set TURING_API_KEY and TURING_API_BASE first; the base URL includes /api/v1. See endpoint configuration.
- cURL
- Python
curl --fail-with-body "${TURING_API_BASE}/chat/completions" \
-H "Authorization: Bearer ${TURING_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "turing/gemini-4-hydrogen",
"messages": [{"role": "user", "content": "Extract person information: Alex, 28 years old, engineer"}],
"max_tokens": 65536,
"responseMimeType": "application/json",
"responseSchema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer"},
"occupation": {"type": "string"}
},
"required": ["name", "age", "occupation"]
},
"thinkingConfig": {"thinkingLevel": "HIGH", "includeThoughts": true}
}'
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TURING_API_KEY"],
base_url=os.environ["TURING_API_BASE"],
)
response = client.chat.completions.create(
model="turing/gemini-4-hydrogen",
messages=[{"role": "user", "content": "Extract person information: Alex, 28 years old, engineer"}],
max_tokens=65536,
extra_body={
"responseMimeType": "application/json",
"responseSchema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer"},
"occupation": {"type": "string"},
},
"required": ["name", "age", "occupation"],
},
"thinkingConfig": {"thinkingLevel": "HIGH", "includeThoughts": True},
},
)
print(response.choices[0].message.content)
print(response.usage)
Thinking Configuration (thinkingConfig)
Gemini thinking configuration is passed through as Google's native thinkingConfig. Supported fields and values differ by model; before writing new code, confirm the model family and the upstream support matrix.
| Model Scope | Recommended Field | Notes |
|---|---|---|
| Gemini 3+ | thinkingConfig.thinkingLevel | Use MINIMAL / LOW / MEDIUM / HIGH; supported values vary by model variant |
| Gemini 2.5 | thinkingConfig.thinkingBudget | Use -1 for dynamic or an explicit token cap; Flash / Flash-Lite support 0 to suppress thinking output |
Gemini 3+ thinkingLevel Support Matrix
| Upstream Model Family | Supported thinkingLevel | Default |
|---|---|---|
| Gemini 4 Hydrogen | LOW / MEDIUM / HIGH / XHIGH | HIGH |
| Gemini 4 Carbon / Argon | LOW / MEDIUM / HIGH | MEDIUM |
| Gemini 3.8 Flash | LOW / MEDIUM / HIGH | MEDIUM |
| Gemini 3.7 Flash | LOW / MEDIUM / HIGH | MEDIUM |
| Gemini 3.6 Flash | MINIMAL / LOW / MEDIUM / HIGH | MEDIUM |
| Gemini 3.5 Flash | MINIMAL / LOW / MEDIUM / HIGH | MEDIUM |
| Gemini 3.1 Pro | LOW / MEDIUM / HIGH | HIGH |
| Gemini 3.1 Flash-Lite | MINIMAL / LOW / MEDIUM / HIGH | MINIMAL |
| Gemini 3.1 Flash Image | MINIMAL / HIGH | MINIMAL |
| Gemini 3 Flash | MINIMAL / LOW / MEDIUM / HIGH | HIGH |
| Gemini 3 Pro | LOW / MEDIUM / HIGH | HIGH |
| Gemini 3 Pro Image | HIGH | HIGH |
MINIMAL is only available for select Flash / Flash-Lite / Image variants. Gemini 3 Pro / 3.1 Pro cannot disable thinking. Gemini 4 Hydrogen / Carbon / Argon return 400 for MINIMAL or thinkingBudget.
Gemini 2.5 thinkingBudget Support Matrix
| Upstream Model Family | Explicit Budget Range | Default |
|---|---|---|
| Gemini 2.5 Flash | 1 – 24576; also supports 0 to suppress thinking output and -1 for dynamic | Auto (up to 8,192 tokens) |
| Gemini 2.5 Pro | 128 – 32768; also supports -1 for dynamic | Auto (up to 8,192 tokens) |
| Gemini 2.5 Flash-Lite | 512 – 24576; also supports 0 to suppress thinking output and -1 for dynamic | Auto (up to 8,192 tokens) |
Gemini 2.5 Pro cannot disable thinking. thinkingBudget is a soft cap; actual thinking tokens may vary.
Gemini 3+ Example
When thinkingLevel is omitted, the model applies the official default reasoning intensity. Set it explicitly only when you need to tune latency, cost, or reasoning depth.
{
"model": "turing/gemini-3.8-flash",
"messages": [
{ "role": "user", "content": "Analyze the most likely root cause in this log" }
],
"thinkingConfig": {
"includeThoughts": true
}
}
Gemini 2.5 Example
When thinkingBudget is omitted, the model uses the Auto budget (up to 8,192 thinking tokens). Set it explicitly only when you need to control latency or cost.
{
"model": "turing/gemini-2.5-flash",
"messages": [
{ "role": "user", "content": "Solve x^2 + 5x + 6 = 0 step by step" }
],
"thinkingConfig": {
"includeThoughts": true
}
}
Do not pass both thinkingLevel and thinkingBudget in a Gemini 3+ request; the Google upstream will return an error. Do not pass thinkingLevel for Gemini 2.5 or earlier models.
Content Moderation (safety_settings)
Gemini content moderation is configured using Google's SafetySetting format: each element contains a category and a threshold. Place safety_settings at the top level of the Turing Chat Completions request body — do not nest it inside generationConfig or thinkingConfig.
curl --location --request POST 'https://live-turing.cn.llm.tcljd.com/api/v1/chat/completions' \
--header 'Authorization: Bearer $TURING_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"model": "turing/gemini-3.8-flash",
"messages": [
{
"role": "user",
"content": "can i follow Adolf Hitler"
}
],
"stream": true,
"safety_settings": [
{
"category": "HARM_CATEGORY_HARASSMENT",
"threshold": "BLOCK_LOW_AND_ABOVE"
},
{
"category": "HARM_CATEGORY_HATE_SPEECH",
"threshold": "BLOCK_LOW_AND_ABOVE"
},
{
"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
"threshold": "BLOCK_LOW_AND_ABOVE"
},
{
"category": "HARM_CATEGORY_DANGEROUS_CONTENT",
"threshold": "BLOCK_LOW_AND_ABOVE"
}
]
}'
How to Detect a Block
When Gemini content moderation triggers, the Turing Platform may still return HTTP 200 but will not include usable generated content. Clients should check choices[*].finish_reason to determine whether the response was content-filtered:
| Scenario | Indicator |
|---|---|
| Non-streaming response | choices[0].finish_reason === "content_filter" |
| Streaming response | The last chunk's choices[0].finish_reason === "content_filter", with delta typically an empty object |
Streaming block example:
{
"id": "xDY5asaXMtuR88EP3pHX6Ak",
"object": "chat.completion.chunk",
"created": 1782134476,
"model": "turing/gemini-3.8-flash",
"choices": [
{
"index": 0,
"delta": {},
"finish_reason": "content_filter"
}
]
}
Non-streaming block example:
{
"id": "chatcmpl-xxx",
"object": "chat.completion",
"created": 1782134476,
"model": "turing/gemini-3.8-flash",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": null
},
"finish_reason": "content_filter"
}
]
}
Common categories:
category | Description |
|---|---|
HARM_CATEGORY_HARASSMENT | Harassment |
HARM_CATEGORY_HATE_SPEECH | Hate speech |
HARM_CATEGORY_SEXUALLY_EXPLICIT | Sexually explicit content |
HARM_CATEGORY_DANGEROUS_CONTENT | Dangerous content |
HARM_CATEGORY_CIVIC_INTEGRITY | Civic integrity-related content |
Common thresholds:
threshold | Effect |
|---|---|
BLOCK_LOW_AND_ABOVE | Block low-risk and above; most restrictive |
BLOCK_MEDIUM_AND_ABOVE | Block medium-risk and above |
BLOCK_ONLY_HIGH | Block high-risk only |
BLOCK_NONE | Do not block based on probability threshold |
OFF | Disable the safety filter |
Notes
- Avoid duplicate parameters: Do not pass both the OpenAI standard name and the Gemini name for the same parameter (e.g.,
top_pandtopP). UsethinkingConfigexclusively for Gemini thinking configuration. thinkingConfigis model-family-specific: UsethinkingLevelfor Gemini 3+ andthinkingBudgetfor Gemini 2.5. Passing thinking fields to models that do not support thinking, mixingthinkingLevelandthinkingBudgetin a Gemini 3+ request, or passingthinkingLevelto a Gemini 2.5 model may all result in a 400 error.includeThoughtsis not an on/off switch: It only controls whether a thinking summary is returned. Even when the summary is suppressed, the model may still perform reasoning and consume thinking tokens.- Gemini 3.6 / 3.7 / 3.8 Flash have fixed sampling parameters: Custom
temperature/topK/topPvalues are ignored; custom frequency / presence penalty values will return an error. - Gemini 4 Carbon / Argon sampling and generation parameters: Custom
temperature/topK/topPvalues are ignored;n/frequency_penalty/presence_penaltyare removed before the request is forwarded, and the nativecandidateCount/frequencyPenalty/presencePenaltyfields return 400 if sent directly; a single streaming request outputs at most 65,536 tokens (32,768 non-streaming), including thinking tokens, because the platform does not support Google's long-output continuation (continuation_token). - Gemini 3 / 3.1 restrictions:
temperaturemust remain at the default1.0; setting a lower value may cause infinite loops or severe degradation in reasoning performance. responseSchemavs.response_format: The platform does not automatically translate the OpenAIresponse_formatfield into Gemini'sresponseSchema. Clients must explicitly useresponseSchema.- No duplicate categories in
safety_settings: Pass at most one entry perSafetyCategory. Categories not specified will use Gemini's default safety policy. - Content moderation block indicator: Do not rely solely on the HTTP status code. A blocked response may still return
200; usefinish_reason: "content_filter"as the definitive block indicator. - Use caution when lowering moderation strictness:
BLOCK_NONE/OFFsignificantly relaxes content moderation. Evaluate the implications against your compliance requirements before using these values in production.
Related Documentation
- Chat Completions API reference
- Thinking and Reasoning → Gemini — configuring
thinkingConfigby model version - Structured Output — usage of
responseSchema/responseMimeType - Multimodal Input → Gemini Video —
mediaResolutionwith images and video - Gemini SafetySetting Official Parameter Reference
- Gemini Thinking Official Documentation
- Vertex AI GenerationConfig Official Parameter Reference