> ## 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/completions — Legacy Text Completions API

> POST /v1/completions — legacy text completion endpoint for prompt-based models. Accepts a prompt string and returns generated text continuation.

The completions endpoint provides legacy-style text completion where you send a raw prompt and the model generates a continuation of that text. Unlike the chat completions endpoint, there is no structured message history — the model simply continues from where your prompt ends. Most modern use cases are better served by the [chat completions endpoint](/api-reference/chat-completions), which supports system instructions, multi-turn conversations, and tool calling. Use this endpoint only when you need direct prompt-continuation behaviour for legacy workflows.

<Note>
  The chat completions endpoint is recommended for all new development. The completions endpoint exists for compatibility with existing prompt-based pipelines and older models that do not support the chat format.
</Note>

## Endpoint

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

## Request Parameters

<ParamField body="model" type="string" required>
  The model ID to use in `provider/model` format. Not all models support the legacy completions format — check the model's documentation or use the [models endpoint](/api-reference/models) to verify compatibility.
</ParamField>

<ParamField body="prompt" type="string | array" required>
  The prompt to complete. Pass a string for a single prompt or an array of strings to generate completions for multiple prompts in a single request. When passing an array, the response `choices` array is ordered to match the input array.
</ParamField>

<ParamField body="max_tokens" type="integer" default="16">
  The maximum number of tokens to generate in the completion. The prompt tokens plus this value must not exceed the model's context limit.
</ParamField>

<ParamField body="temperature" type="number" default="1">
  Sampling temperature between `0` and `2`. Lower values produce more deterministic output; higher values produce more varied and creative output.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  When `true`, streams partial completions as Server-Sent Events. Each chunk contains a `choices[].text` delta. See the [Streaming guide](/guides/streaming) for details.
</ParamField>

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

## Request Example

```bash cURL theme={null}
curl https://api.portrix.ai/v1/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PORTRIX_API_KEY" \
  -d '{
    "model": "openai/gpt-3.5-turbo-instruct",
    "prompt": "The three laws of robotics are",
    "max_tokens": 128,
    "temperature": 0.5
  }'
```

## Response Fields

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

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

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

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

<ResponseField name="choices" type="array">
  An array of completion results. Contains one item per prompt when an array of prompts is provided.

  <Expandable title="Choice object fields">
    <ResponseField name="choices[].text" type="string">
      The generated text continuation. This is appended directly to your prompt.
    </ResponseField>

    <ResponseField name="choices[].finish_reason" type="string">
      Why the model stopped generating. One of `"stop"` (natural end or stop sequence reached) or `"length"` (`max_tokens` was hit).
    </ResponseField>

    <ResponseField name="choices[].index" type="integer">
      The index of this choice in the array. When a single prompt is used this is always `0`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage.prompt_tokens" type="integer">
  The number of tokens in the input prompt(s).
</ResponseField>

<ResponseField name="usage.completion_tokens" type="integer">
  The number of tokens in the generated completion(s).
</ResponseField>

<ResponseField name="usage.total_tokens" type="integer">
  The sum of `prompt_tokens` and `completion_tokens`.
</ResponseField>

## Response Example

```json theme={null}
{
  "id": "cmpl-def456uvw",
  "object": "text_completion",
  "created": 1719859200,
  "model": "openai/gpt-3.5-turbo-instruct",
  "choices": [
    {
      "index": 0,
      "text": ":\n1. A robot may not injure a human being or, through inaction, allow a human being to come to harm.\n2. A robot must obey orders given to it by human beings except where such orders would conflict with the First Law.\n3. A robot must protect its own existence as long as such protection does not conflict with the First or Second Law.",
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 68,
    "total_tokens": 77
  }
}
```

## Portrix-Specific Headers

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

| Header               | Example Value                   | Effect                                                                        |
| -------------------- | ------------------------------- | ----------------------------------------------------------------------------- |
| `x-portrix-model`    | `openai/gpt-3.5-turbo-instruct` | Override the model for this request without modifying the body `model` field. |
| `x-portrix-fallback` | `openai/gpt-3.5-turbo-instruct` | A fallback model to use if the primary model returns a `502` or `503` error.  |
| `x-portrix-route`    | `us-east`                       | Pin the request to a specific provider region or deployment tier.             |

<Warning>
  The completions endpoint does not support tool calling, vision inputs, or structured output features. If you need any of these capabilities, migrate to the [chat completions endpoint](/api-reference/chat-completions) instead.
</Warning>