> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/router-for-me/CLIProxyAPI/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Completions

> Send chat completion requests using the OpenAI-compatible format

# POST /v1/chat/completions

Create a model response for the given conversation history. This endpoint is fully compatible with the OpenAI Chat Completions API and supports both streaming and non-streaming responses.

## Request Body

<ParamField body="model" type="string" required>
  The model to use for completion. Examples: `gemini-2.5-pro`, `claude-sonnet-4`, `gpt-4o`, or any model supported by your configured providers.
</ParamField>

<ParamField body="messages" type="array" required>
  An array of message objects representing the conversation history.

  Each message object contains:

  * `role` (string, required): One of `system`, `user`, `assistant`, or `tool`
  * `content` (string or array, required): The message content. Can be a string or an array of content parts for multimodal inputs
  * `name` (string, optional): The name of the message author
  * `tool_calls` (array, optional): Tool calls made by the assistant
  * `tool_call_id` (string, optional): The ID of the tool call this message is responding to (for tool messages)
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  If set to `true`, the server will send partial message deltas as Server-Sent Events (SSE). If `false`, the server will wait until the generation is complete before sending the full response.
</ParamField>

<ParamField body="temperature" type="number" default="1.0">
  Sampling temperature between 0 and 2. Higher values make output more random, lower values make it more deterministic.
</ParamField>

<ParamField body="top_p" type="number" default="1.0">
  Nucleus sampling parameter. The model considers the results of tokens with top\_p probability mass.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Number of chat completion choices to generate. Note: Not all providers support values greater than 1.
</ParamField>

<ParamField body="max_tokens" type="integer">
  The maximum number of tokens to generate. If not specified, the model will generate until it reaches a natural stopping point.
</ParamField>

<ParamField body="stop" type="string or array">
  Up to 4 sequences where the API will stop generating further tokens.
</ParamField>

<ParamField body="presence_penalty" type="number" default="0">
  Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far.
</ParamField>

<ParamField body="frequency_penalty" type="number" default="0">
  Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text.
</ParamField>

<ParamField body="tools" type="array">
  A list of tools (functions) the model may call. Each tool object contains:

  * `type` (string): Must be `function`
  * `function` (object): Function definition with `name`, `description`, and `parameters`
</ParamField>

<ParamField body="tool_choice" type="string or object">
  Controls which (if any) function is called by the model. Options:

  * `none`: Model will not call any function
  * `auto`: Model can choose to call a function or generate a message
  * `required`: Model must call one or more functions
  * Object with specific function name to force that function
</ParamField>

<ParamField body="reasoning_effort" type="string">
  Controls the level of reasoning for models that support extended thinking. Options:

  * `none`: No extended reasoning
  * `low`: Minimal reasoning effort
  * `medium`: Moderate reasoning effort
  * `high`: Maximum reasoning effort
  * `auto`: Let the model decide

  This is mapped to provider-specific thinking configurations (e.g., Gemini's `thinkingConfig`).
</ParamField>

<ParamField body="modalities" type="array">
  Response modalities for multimodal models. Supported values: `text`, `image`.

  Example: `["text", "image"]` for models that can generate both text and images.
</ParamField>

## Response Format

### Non-Streaming Response

<ResponseField name="id" type="string">
  A unique identifier for the chat completion.
</ResponseField>

<ResponseField name="object" type="string">
  Always `chat.completion`.
</ResponseField>

<ResponseField name="created" type="integer">
  Unix timestamp (in seconds) of when the completion was created.
</ResponseField>

<ResponseField name="model" type="string">
  The model used for the completion.
</ResponseField>

<ResponseField name="choices" type="array">
  Array of completion choices. Each choice contains:

  <ResponseField name="index" type="integer">
    The index of this choice in the array.
  </ResponseField>

  <ResponseField name="message" type="object">
    The generated message.

    <ResponseField name="role" type="string">
      Always `assistant`.
    </ResponseField>

    <ResponseField name="content" type="string">
      The content of the message.
    </ResponseField>

    <ResponseField name="tool_calls" type="array">
      If the model called functions, this contains the function call details.
    </ResponseField>
  </ResponseField>

  <ResponseField name="finish_reason" type="string">
    Why the model stopped generating tokens. Possible values:

    * `stop`: Natural completion
    * `length`: Maximum token limit reached
    * `tool_calls`: Model called a function
    * `content_filter`: Content filtered by safety systems
  </ResponseField>
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage statistics.

  <ResponseField name="prompt_tokens" type="integer">
    Number of tokens in the prompt.
  </ResponseField>

  <ResponseField name="completion_tokens" type="integer">
    Number of tokens in the completion.
  </ResponseField>

  <ResponseField name="total_tokens" type="integer">
    Total tokens used (prompt + completion).
  </ResponseField>
</ResponseField>

### Streaming Response

When `stream: true`, the server sends chunks as Server-Sent Events (SSE). Each chunk follows this format:

```
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gemini-2.5-pro","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gemini-2.5-pro","choices":[{"index":0,"delta":{"content":" there"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gemini-2.5-pro","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

Each chunk contains a `delta` object with the incremental changes to the message. The stream ends with a `data: [DONE]` message.

## Examples

### Basic Chat Completion

```bash theme={null}
curl http://localhost:8317/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gemini-2.5-pro",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'
```

### Streaming Response

```bash theme={null}
curl http://localhost:8317/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "claude-sonnet-4",
    "messages": [
      {"role": "user", "content": "Tell me a short story."}
    ],
    "stream": true
  }'
```

### Function Calling

```bash theme={null}
curl http://localhost:8317/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gemini-2.5-pro",
    "messages": [
      {"role": "user", "content": "What is the weather in San Francisco?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather in a location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
              }
            },
            "required": ["location"]
          }
        }
      }
    ]
  }'
```

### With Reasoning Effort

```bash theme={null}
curl http://localhost:8317/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gemini-2.5-flash-thinking-exp",
    "messages": [
      {"role": "user", "content": "Solve this complex math problem: ..."}
    ],
    "reasoning_effort": "high"
  }'
```

## Implementation Details

The `/v1/chat/completions` endpoint is implemented in `sdk/api/handlers/openai/openai_handlers.go`. Key behaviors:

* **Provider Translation**: Requests are automatically translated to the target provider's format (Gemini, Claude, etc.)
* **Function Calling**: Tool calls are preserved across provider translations
* **Streaming**: SSE streaming uses chunked transfer encoding with immediate flushing
* **Auto-conversion**: Some clients send OpenAI Responses-format payloads to this endpoint; these are automatically converted to Chat Completions format

<Note>
  If the request doesn't include a `messages` field but has `input` or `instructions`, it will be automatically treated as an OpenAI Responses-format request and converted.
</Note>

## Error Responses

All errors follow the OpenAI error format:

```json theme={null}
{
  "error": {
    "message": "Invalid request: model field is required",
    "type": "invalid_request_error",
    "code": "invalid_request"
  }
}
```

Common HTTP status codes:

* `400 Bad Request`: Invalid request parameters
* `401 Unauthorized`: Missing or invalid API key
* `429 Too Many Requests`: Rate limit exceeded
* `500 Internal Server Error`: Server-side error
* `503 Service Unavailable`: Provider temporarily unavailable