POST /v1/chat/completions — Chat Completions API

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

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 for the full list of available IDs.

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.

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.

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.

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 for a complete example.

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.

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.

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.

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.

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.

Request Example

cURL

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

string

A unique identifier for this completion, prefixed with chatcmpl-.

string

Always "chat.completion" for non-streaming responses. Streaming chunks use "chat.completion.chunk".

integer

Unix timestamp (seconds) of when the completion was created.

string

The model ID that was used to generate this response, in provider/model format.

array

An array of completion choices. Contains n items when n > 1 is requested.

Show Choice object fields

string

Always "assistant" for chat completions.

string

The text content of the model’s response. May be null when the model makes a tool call instead.

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.

integer

The number of tokens in the input messages.

integer

The number of tokens in the generated response.

integer

The sum of prompt_tokens and completion_tokens. This is what Portrix uses to calculate billing.

Response Example

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

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.

Overview

Endpoints

POST /v1/chat/completions — Chat Completions API

Endpoint

Request Parameters

Request Example

Response Fields

Response Example

Streaming

Portrix-Specific Headers

​Endpoint

​Request Parameters

​Request Example

​Response Fields

​Response Example

​Streaming

​Portrix-Specific Headers

Endpoint

Request Parameters

Request Example

Response Fields

Response Example

Streaming

Portrix-Specific Headers