Skip to main content
POST
/
gemini-3-pro
/
v1
/
chat
/
completions
Chat Completions
curl --request POST \
  --url https://api.kie.ai/gemini-3-pro/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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": "object",
    "properties": {
      "response": {
        "type": "string"
      }
    }
  }
}
'
{
  "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT",
  "object": "chat.completion",
  "created": 1741569952,
  "model": "gemini-3-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "hello,can i help you?",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "service_tier": "default"
}

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

Multimodal

Supports text and image inputs

Real-time Search

Google Search grounding enabled

Streaming

Server-sent events support

Flexible Roles

Multiple message roles supported

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 and function calling are mutually exclusive: You cannot use both Google Search and function calling in the same request. Choose one based on your needs.
Define your own functions with parameters. You can define multiple functions in the tools array:
[
  {
    "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.
response_format and function calling are mutually exclusive: You cannot use response_format together with function calling in the same request. Choose one based on your needs.
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
{
  "response_format": {
    "type": "object",
    "properties": {
      "response": {
        "type": "string"
      }
    }
  }
}
  • 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
{
  "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT",
  "object": "chat.completion",
  "created": 1741569952,
  "model": "gemini-3-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "hello,can i help you?",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "service_tier": "default"
}

Authorizations

Authorization
string
header
required

All APIs require authentication via Bearer Token.

Get API Key:

  1. Visit API Key Management Page to get your API Key

Usage: Add to request header: Authorization: Bearer YOUR_API_KEY

Note:

  • Keep your API Key secure and do not share it with others
  • If you suspect your API Key has been compromised, reset it immediately in the management page

Body

application/json
messages
object[]
required

An array of message objects. Each message has a role and content.

Minimum array length: 1
stream
boolean
default:true

If set to true, partial message deltas will be sent as server-sent events. Default is true.

tools
object[]

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).

Important: Google Search and function calling are mutually exclusive - you cannot use both in the same request. When using function calling, you can include multiple function definitions. Function calling and response_format are also mutually exclusive - you cannot use both in the same request.

include_thoughts
boolean
default:true

Whether to include thoughts in the response. If set to true, thoughts will be included in the response, otherwise they will not be included. Default is true.

reasoning_effort
enum<string>
default:high

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

Available options:
low,
high
response_format
object

Optional JSON Schema object defining the structure of the response. When provided, the model will generate responses that conform to this schema. response_format and function calling are mutually exclusive - you cannot use both in the same request.

Example:

{
"type": "object",
"properties": {
"response": {
"type": "string"
}
}
}

Response

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

Example:

"chatcmpl-123"

object
string

Object type

Example:

"chat.completion"

created
integer<int64>

Unix timestamp of when the completion was created

Example:

1677652288

model
string

Model name

Example:

"gemini-3-pro"

choices
object[]

Array of completion choices

usage
object