gemini-3-1-pro-preview API Model Guide
TL;DR
- Supports Chat Completions for low-friction SDK migration.
- Supports streaming and tool-calling for agent workflows.
- Stabilize system/messages parameters before production rollout.
Core Capabilities
- Chat and reasoning：Supports multi-turn context and structured outputs.
- Streaming output：SSE token streaming for real-time UX.
- Tool calling：Compose retrieval/execution workflows with tools.
When to Use
- When building coding/Q&A assistants and task agents.
- When streaming and tool-calling are required.
When Not to Use
- For pure image/video generation tasks.
- For simple templated text without reasoning needs.
Runtime Behavior
- API calls are stateless; pass full context via messages.
- With stream=true, responses return as SSE events.
Minimal Request
{
"model": "gemini-3-1-pro-preview",
"messages": [
{
"role": "user",
"content": "Summarize suitable use cases for this model."
}
],
"max_tokens": 200
}
Minimal Response
{
"id": "chatcmpl_xxxxxxxx",
"model": "gemini-3-1-pro-preview",
"object": "chat.completion",
"choices": [
{
"index": 0,
"finish_reason": "stop"
}
]
}
Key Parameters
| Parameter | Type | Required | Default | Range | Description |
|---|
| model | string | Yes | gemini-3-1-pro-preview | - | Exact model identifier from ToAPIs. |
| messages | object[] | Yes | - | - | Conversation messages in chronological order. |
| max_tokens | integer | Yes | - | >=1 | Maximum output tokens. |
| stream | boolean | No | false | - | Enable SSE streaming output. |
| tools | object[] | No | - | - | Tool/function definitions for tool-calling. |
Common Errors
| HTTP | Code | Trigger | Fix Action | Retry Policy |
|---|
| 400 | invalid_request_error | Missing fields or invalid payload types. | Validate model/messages/max_tokens schema. | Retry only after payload fix. |
| 401 | authentication_error | Missing or invalid API key. | Verify Authorization header and key scope. | Retry after authentication fix. |
FAQ
- What is gemini-3-1-pro-preview best for?
Best for chat, reasoning, coding, and tool-calling assistant workflows.
Related APIs
