POST /v1/completions — Legacy Text Completions API

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, which supports system instructions, multi-turn conversations, and tool calling. Use this endpoint only when you need direct prompt-continuation behaviour for legacy workflows.

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.

Endpoint

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

Request Parameters

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 to verify compatibility.

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.

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.

number

default:"1"

Sampling temperature between 0 and 2. Lower values produce more deterministic output; higher values produce more varied and creative output.

boolean

default:"false"

When true, streams partial completions as Server-Sent Events. Each chunk contains a choices[].text delta. See the Streaming guide for details.

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.

Request Example

cURL

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

string

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

string

Always "text_completion".

integer

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

string

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

array

An array of completion results. Contains one item per prompt when an array of prompts is provided.

Show Choice object fields

string

The generated text continuation. This is appended directly to your prompt.

string

Why the model stopped generating. One of "stop" (natural end or stop sequence reached) or "length" (max_tokens was hit).

integer

The index of this choice in the array. When a single prompt is used this is always 0.

integer

The number of tokens in the input prompt(s).

integer

The number of tokens in the generated completion(s).

integer

The sum of prompt_tokens and completion_tokens.

Response Example

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

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

Overview

Endpoints

POST /v1/completions — Legacy Text Completions API

Endpoint

Request Parameters

Request Example

Response Fields

Response Example

Portrix-Specific Headers

​Endpoint

​Request Parameters

​Request Example

​Response Fields

​Response Example

​Portrix-Specific Headers

Endpoint

Request Parameters

Request Example

Response Fields

Response Example

Portrix-Specific Headers