> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/chat/completions — Chat Completions API

> POST /v1/chat/completions — generate chat responses from 400+ models. Accepts messages array, model ID, temperature, max_tokens, and streaming flag.

The chat completions endpoint is the primary way to interact with language models through Portrix. You send a conversation history as an array of messages — each with a role and content — and the model returns a generated reply. The endpoint is fully compatible with the OpenAI Chat Completions API, so any code that uses `openai.chat.completions.create` works without modification beyond the base URL and key.

## Endpoint

```
POST https://api.portrix.ai/v1/chat/completions
```

## Request Parameters

<ParamField body="model" type="string" required>
  The model ID to use in `provider/model` format. For example, `openai/gpt-4o`, `anthropic/claude-3-5-sonnet`, or `google/gemini-2.0-flash`. See [GET /v1/models](/api-reference/models) for the full list of available IDs.
</ParamField>

<ParamField body="messages" type="array" required>
  An ordered array of message objects representing the conversation history. Each message has the following fields:

  * `role` (string, required): One of `system`, `user`, or `assistant`.
  * `content` (string, required): The text content of the message.

  The array must contain at least one message. Include a `system` message as the first item to set the model's behaviour and persona.
</ParamField>

<ParamField body="temperature" type="number" default="1">
  Controls the randomness of the output. Values range from `0` (deterministic) to `2` (highly creative). Lower values make the model more focused and repeatable; higher values introduce more variety. For most tasks a value between `0.2` and `0.8` works well.
</ParamField>

<ParamField body="max_tokens" type="integer">
  The maximum number of tokens to generate in the response. The request plus the response must not exceed the model's context window. If omitted, the model uses its default maximum.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  When `true`, the API streams partial message deltas as Server-Sent Events instead of returning the full response at once. Each event contains a `delta` field with incremental content. See the [Streaming guide](/guides/streaming) for a complete example.
</ParamField>

<ParamField body="top_p" type="number" default="1">
  Nucleus sampling parameter. The model considers only the tokens whose cumulative probability exceeds `top_p`. Use either `temperature` or `top_p`, not both.
</ParamField>

<ParamField body="n" type="integer" default="1">
  The number of independent completion choices to generate. Each choice is a separate model response. Generating multiple completions increases token usage proportionally.
</ParamField>

<ParamField body="stop" type="string | array">
  One or more sequences at which the model stops generating. The stop sequence itself is not included in the output. Pass a string for a single sequence or an array for up to four sequences.
</ParamField>

<ParamField body="tools" type="array">
  A list of tool definitions the model can call. Each tool has a `type` (currently `"function"`), a `function.name`, a `function.description`, and a `function.parameters` JSON Schema object describing the arguments.
</ParamField>

<ParamField body="tool_choice" type="string | object" default="auto">
  Controls how the model selects tools. Pass `"none"` to disable tools, `"auto"` to let the model decide, or `{"type": "function", "function": {"name": "my_function"}}` to force a specific function call.
</ParamField>

## Request Example

```bash cURL theme={null}
curl https://api.portrix.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PORTRIX_API_KEY" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ],
    "temperature": 0.7,
    "max_tokens": 256
  }'
```

## Response Fields

<ResponseField name="id" type="string">
  A unique identifier for this completion, prefixed with `chatcmpl-`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"chat.completion"` for non-streaming responses. Streaming chunks use `"chat.completion.chunk"`.
</ResponseField>

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

<ResponseField name="model" type="string">
  The model ID that was used to generate this response, in `provider/model` format.
</ResponseField>

<ResponseField name="choices" type="array">
  An array of completion choices. Contains `n` items when `n > 1` is requested.

  <Expandable title="Choice object fields">
    <ResponseField name="choices[].message.role" type="string">
      Always `"assistant"` for chat completions.
    </ResponseField>

    <ResponseField name="choices[].message.content" type="string">
      The text content of the model's response. May be `null` when the model makes a tool call instead.
    </ResponseField>

    <ResponseField name="choices[].finish_reason" type="string">
      The reason the model stopped generating. One of:

      * `"stop"` — the model reached a natural stopping point or a stop sequence.
      * `"length"` — `max_tokens` was reached.
      * `"tool_calls"` — the model made one or more tool calls.
      * `"content_filter"` — content was blocked by a safety filter.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage.prompt_tokens" type="integer">
  The number of tokens in the input messages.
</ResponseField>

<ResponseField name="usage.completion_tokens" type="integer">
  The number of tokens in the generated response.
</ResponseField>

<ResponseField name="usage.total_tokens" type="integer">
  The sum of `prompt_tokens` and `completion_tokens`. This is what Portrix uses to calculate billing.
</ResponseField>

## Response Example

```json theme={null}
{
  "id": "chatcmpl-abc123xyz",
  "object": "chat.completion",
  "created": 1719859200,
  "model": "openai/gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 9,
    "total_tokens": 37
  }
}
```

## Streaming

Set `"stream": true` in your request body to receive incremental response chunks as they are generated. The API switches to `text/event-stream` and sends a series of `data:` lines, each containing a JSON delta object. A final `data: [DONE]` message signals the end of the stream.

See the [Streaming guide](/guides/streaming) for full code examples in Python and TypeScript, including how to reconstruct the full message from deltas and how to handle tool calls in streaming mode.

## Portrix-Specific Headers

You can attach these optional headers to any chat completions request to enable Portrix routing features.

| Header               | Example Value                                    | Effect                                                                                                                                    |
| -------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `x-portrix-model`    | `anthropic/claude-3-5-sonnet`                    | Override the model for this request without modifying the body `model` field. Takes precedence over the body value when both are present. |
| `x-portrix-fallback` | `anthropic/claude-3-5-sonnet,openai/gpt-4o-mini` | If the primary model returns a `502` or `503`, Portrix retries using the next model in the list.                                          |
| `x-portrix-route`    | `eu-west`                                        | Pin the request to a specific provider region or deployment tier.                                                                         |

<Tip>
  Use `x-portrix-fallback` in production to improve reliability. If your primary model experiences an outage, requests automatically fail over to your specified backup model without any changes to your application code.
</Tip>