Gemini 3 Pro (openai)

This page is generated from the upstream official OpenAPI documentation. Endpoints, parameters and examples match the official docs; brand and API domain are replaced with ModelFold.

Endpoint

POST /gemini-3-pro/v1/chat/completions

Full URL: https://ai.modelfold.online/gemini-3-pro/v1/chat/completions

Authentication: every request must include the Authorization: Bearer <API_KEY> header.

WARNING

⚠️ Chat only

This model currently supports chat requests only and has not yet been adapted for agent use. Connecting it to an agent may cause request errors or unexpected results.

Streaming Support

When stream: true is set in the request, the API returns responses as server-sent events (SSE) with Content-Type: text/event-stream. This allows for progressive response delivery, where message deltas are sent incrementally as they are generated. Each event contains partial message content, enabling real-time display of responses in your application.

Streaming Response Format:

Content-Type: text/event-stream
Each event line starts with data: followed by JSON
Events contain incremental message deltas
Final event indicates completion with finish_reason
The stream ends with a chunk carrying usage and credits_consumed, followed by data: [DONE].
- Multimodal — Text, image, video, audio and PDF input
- Real-time Search — Google Search grounding enabled
- Streaming — Server-sent events support
- Flexible Roles — Multiple message roles supported

⚠️ Important: Unified Media Structure

To simplify integration, all media types (Images, Videos, Audio, or Documents) in the messages array share the exact same JSON structure:

<ul style="color: #555; line-height: 1.8; margin-bottom: 15px; font-size: 14px;"> <li>The type field is fixed as "image_url"</li> <li>The image_url key name remains unchanged for all file types</li> <li>Only the url value points to your specific media file</li> </ul>

// Example for Video/Audio/PDF/Image:
 { "type": "image_url", "image_url": { "url": "https://..." } } 

Tools Parameter

The tools parameter is an optional array that allows you to define functions the model can call. The array can contain multiple objects. When using function calling, you can define multiple functions in the array.

Google Search

Use this format to enable Google Search grounding:

json

{
  "type": "function",
  "function": {
    "name": "googleSearch"
  }
}

This enables real-time information retrieval via Google Search.

Function Calling

Define your own functions with parameters. You can define multiple functions in the tools array:

json

[
  {
    "type": "function",
    "function": {
      "name": "get_current_weather",
      "description": "Get the current weather in a given location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"]
          }
        },
        "required": ["location"]
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "get_stock_price",
      "description": "Get the current stock price for a given symbol",
      "parameters": {
        "type": "object",
        "properties": {
          "symbol": {
            "type": "string",
            "description": "The stock symbol, e.g. AAPL"
          }
        },
        "required": ["symbol"]
      }
    }
  }
]

Function Declaration Requirements

When implementing function calling in your prompt, you need to create a tools array containing one or more function declarations. You can define functions using JSON (specifically, a selected subset of OpenAPI schema format).

A single function declaration can include the following parameters:

name (string, required): The unique name of the function (e.g., get_weather_forecast, send_email). Use descriptive names without spaces or special characters (use underscores or camelCase).
description (string, optional but recommended): A clear and detailed description of what the function does and its purpose. This is crucial for the model to understand when to use the function. Be specific and provide examples when necessary (e.g., "Find movie theaters by location, with an option to also find movies currently showing at those theaters.").
parameters (object, required): Defines the input parameters expected by the function. Contains:
- type (string): Specifies the overall data type, must be "object".
- properties (object): Lists individual parameters, each with:
  - type (string): The parameter's data type, such as string, integer, boolean, array.
  - description (string): Description of the parameter's purpose and format. Provide examples and constraints (e.g., "City and state, e.g. 'San Francisco, CA' or a postal code like '95616'.").
  - enum (array, optional): If parameter values come from a fixed set, use enum to list allowed values rather than just describing them in the description. This helps improve accuracy (e.g., "enum": ["daylight", "cool", "warm"]).
- required (array): An array of strings listing the parameter names required for the function to run.

Response Format Parameter

The response_format parameter is an optional JSON Schema object that defines the structure of the response. When provided, the model will generate responses that conform to this schema.

JSON Schema Support

The response_format follows the JSON Schema specification. Supported types include:

string: For text values
number: For floating-point numbers
integer: For whole numbers
boolean: For true/false values
object: For structured data with key-value pairs
array: For lists of items
null: To allow null values, add "null" to the type array (e.g., {"type": ["string", "null"]})

Type-Specific Properties

For object values:

properties: Object mapping property names to their schema definitions
required: Array of required property names
additionalProperties: Controls whether properties not in properties are allowed

For string values:

enum: List of specific possible string values for classification
format: Specifies string syntax (e.g., date-time, date, time)

For number and integer values:

enum: List of specific possible numeric values
minimum: Inclusive minimum value
maximum: Inclusive maximum value

For array values:

items: Schema definition for all array elements
prefixItems: List of schemas for the first N items (tuple-like structures)
minItems: Minimum number of items in the array
maxItems: Maximum number of items in the array

Example

json

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "structured_output",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "response": {
            "type": "string"
          }
        },
        "required": [
          "response"
        ]
      }
    }
  }
}

{"type":"json_object"} is also supported.

Best Practices

Clear descriptions: Use the description field in the schema to clearly explain what each property means
Strong typing: Use specific types (integer, string, enum) whenever possible
Prompt engineering: Clearly state in your prompt what you want the model to extract or structure
Validation: While structured output ensures JSON is syntactically correct, always validate the semantic correctness of values in your application code

Error Responses

Errors are returned with HTTP 200 and a JSON body {"code": <int>, "msg": "<reason>"}. Check code (200 = success) before reading choices/candidates.

Request Parameters

Body (application/json)

Parameter	Type	Required	Description
`messages`	`array<object>`	Yes	An array of message objects. Each message has a role and content. Unified Media File Format: In the content array, whether it's images, videos, audio, or other document types, all media files use the same format structure: - The `type` field is always `"image_url"` - The `image_url` field name remains unchanged - The only thing that changes is the `url` value, which points to the corresponding media file address For example: images, videos, audio, PDFs, and other documents all use the same `{ type: 'image_url', image_url: { url: '...' } }` structure.
`messages[].role`	`string`	Yes	Message role - developer: Developer-provided instructions that the model should follow, regardless of user messages. - system: Developer-provided instructions that the model should follow, regardless of user messages. - user: Messages sent by end users, containing prompts or additional context information. - assistant: Messages sent by the model in response to user messages. - tool: Content of tool messages. Allowed values：`developer` / `system` / `user` / `assistant` / `tool`。示例：`developer`。
`messages[].content`	`array<object	object>`	Yes
`stream`	`boolean`	No	Default is false. Set to true to receive server-sent events. Default：`false`。示例：`false`。
`tools`	`array<object>`	No	An optional array of tools the model may call. The array can contain multiple objects. Supports two formats: 1. Google Search: `{"type": "function", "function": {"name": "googleSearch"}}` - Enables real-time information retrieval via Google Search. 2. Function calling: Define your own functions with name, description, and parameters. You can define multiple functions in the array. Functions are defined using JSON (specifically, a selected subset of OpenAPI schema format). When using function calling, you can include multiple function definitions.
`tools[].type`	`string`	Yes	Utility type. Must be 'function'. Allowed values：`function`。示例：`function`。
`tools[].function`	`object`	Yes	Function declarations for enhanced network access.
`tools[].function.name`	`string`	Yes	Function name. Must be `googleSearch`.
`tools[].function.description`	`string`	No	Optional but recommended. A clear and specific description of the function's purpose. Helps the model understand when to call this function.
`tools[].function.parameters`	`object`	No	Defines a JSON Schema object for function parameters. Required for custom functions; not used by 'googleSearch'. Follows the JSON Schema specification.
`tools[].function.parameters.type`	`string`	Yes	Must be 'object' for function parameters Allowed values：`object`。示例：`object`。
`tools[].function.parameters.properties`	`object`	Yes	Map parameter names to objects defined in their JSON Schema.
`tools[].function.parameters.required`	`array<string>`	No	Required parameter name array
`include_thoughts`	`boolean`	No	Default false. Takes effect only with stream: true; thought summaries are streamed in choices[].delta.reasoning_content before the answer. Default：`false`。示例：`false`。
`reasoning_effort`	`string`	No	The effort level for the model to use for reasoning. Low effort is faster to respond, high effort is slower to respond but solves more complex problems. Default is "high". Default：`"high"`。 Allowed values：`low` / `high`。示例：`high`。
`response_format`	`object`	No	Optional JSON Schema object defining the structure of the response. When provided, the model will generate responses that conform to this schema. Example: `<code>json<br>{<br> "type": "json_schema",<br> "json_schema": {<br> "name": "structured_output",<br> "strict": true,<br> "schema": {<br> "type": "object",<br> "properties": {<br> "response": {<br> "type": "string"<br> }<br> },<br> "required": [<br> "response"<br> ]<br> }<br> }<br>}<br></code>` `{"type":"json_object"}` is also supported.
`response_format.type`	`string`	Yes	Only json_schema value
`response_format.json_schema`	`object`	Yes	JSON Schema object defining the structure of the response. When provided, the model will generate responses that conform to this schema.
`response_format.json_schema.name`	`string`	Yes	Only structured_output value
`response_format.json_schema.strict`	`boolean`	Yes	Enable strict mode?
`response_format.json_schema.schema`	`object`	Yes	—
`response_format.json_schema.schema.type`	`string`	Yes	The response_format follows the JSON Schema specification. Supported types include: string: For text values number: For floating-point numbers integer: For whole numbers boolean: For true/false values object: For structured data with key-value pairs array: For lists of items null: To allow null values, add "null" to the type array
`response_format.json_schema.schema.properties`	`object`	Yes	Object mapping property names to their JSON Schema definitions
`response_format.json_schema.schema.required`	`array<string>`	Yes	Array of required property names
`response_format.json_schema.schema.title`	`string`	Yes	Short description of the schema
`response_format.json_schema.schema.description`	`string`	Yes	Detailed description of the schema

Request Example

bash

curl -X POST "https://ai.modelfold.online/gemini-3-pro/v1/chat/completions" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is in this image?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://file.aiquickdraw.com/custom-page/akr/section-images/1759055072437dqlsclj2.png"
          }
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "googleSearch"
      }
    }
  ],
  "stream": true,
  "include_thoughts": true,
  "reasoning_effort": "high",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "structured_output",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "response": {
            "type": "string"
          }
        }
      }
    }
  }
}'

json

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is in this image?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://file.aiquickdraw.com/custom-page/akr/section-images/1759055072437dqlsclj2.png"
          }
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "googleSearch"
      }
    }
  ],
  "stream": true,
  "include_thoughts": true,
  "reasoning_effort": "high",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "structured_output",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "response": {
            "type": "string"
          }
        }
      }
    }
  }
}

Response

200 — Request successful. When `response_format` is provided, the response will conform to the specified JSON schema. Otherwise, returns the standard chat completion format.

参数	类型	必填	说明
`id`	`string`	否	Unique identifier for the chat completion 示例：`chatcmpl-example-123`。
`object`	`string`	否	Object type 示例：`chat.completion`。
`created`	`integer`	否	Unix timestamp of when the completion was created 示例：`1677652288`。
`choices`	`array<object>`	否	Array of completion choices
`choices[].index`	`integer`	是	Index of the choice 示例：`0`。
`choices[].message`	`object`	是	—
`choices[].message.role`	`string`	是	示例：`assistant`。
`choices[].message.content`	`string`	是	Message content
`choices[].finish_reason`	`string`	是	Reason why the completion finished 示例：`stop`。
`usage`	`object`	否	—
`usage.prompt_tokens`	`integer`	是	Number of tokens in the prompt 示例：`10`。
`usage.completion_tokens`	`integer`	是	Number of tokens in the completion 示例：`50`。
`usage.total_tokens`	`integer`	是	Total number of tokens 示例：`60`。

json

{
  "id": "chatcmpl-example-123",
  "object": "chat.completion",
  "created": 1677652288,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A serene mountain landscape at sunrise"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 50,
    "total_tokens": 60
  }
}

500 — Server error.

参数	类型	必填	说明
`code`	`integer`	是	Response status code - 200: Success - Request has been processed successfully - 401: Unauthorized - Authentication credentials are missing or invalid - 402: Insufficient Credits - Account does not have enough credits to perform the operation - 404: Not Found - The requested resource or endpoint does not exist - 408: Timeout - No result has been returned for over 10 minutes. - 422: Validation Error - The request parameters failed validation checks - 429: Rate Limited - Request limit has been exceeded for this resource - 455: Service Unavailable - System is currently undergoing maintenance - 500: Server Error - An unexpected error occurred while processing the request - 501: Generation Failed - Content generation task failed - 505: Feature Disabled - The requested feature is currently disabled
`msg`	`string`	是	Response message, error description when failed
`data`	`object`	是	—

json

{
  "code": 500,
  "msg": "Server Error - An unexpected error occurred while processing the request",
  "data": null
}

Gemini 3 Pro (openai) ​

Endpoint ​

Streaming Support ​

Tools Parameter ​

Function Declaration Requirements ​

Response Format Parameter ​

Type-Specific Properties ​

Error Responses ​

Request Parameters ​

Body (application/json) ​

Request Example ​

Response ​

200 — Request successful. When response_format is provided, the response will conform to the specified JSON schema. Otherwise, returns the standard chat completion format. ​

500 — Server error. ​

Gemini 3 Pro (openai)

Endpoint

Streaming Support

Tools Parameter

Function Declaration Requirements

Response Format Parameter

Type-Specific Properties

Error Responses

Request Parameters

Body (application/json)

Request Example

Response

200 — Request successful. When `response_format` is provided, the response will conform to the specified JSON schema. Otherwise, returns the standard chat completion format.

500 — Server error.