POST /v1/completions — OpenAI Legacy Completions

The /v1/completions endpoint provides the OpenAI legacy text completions interface. Instead of a messages array, you pass a single prompt string and receive a generated completion. Rolter proxies the request to the upstream target selected by the named route, applying the same authentication, load balancing, and param injection as every other inference endpoint.

Note

For most use cases, prefer /v1/chat/completions. The chat interface is the current OpenAI standard and is supported across all provider kinds (OpenAI, Anthropic, and OpenAI-compatible). This endpoint exists for backward compatibility with legacy clients and tooling that predate the chat format.

Request#

POST /v1/completions

Headers#

Authorizationstringrequired#

Bearer <virtual-key> — your Rolter virtual key.

Content-Typestringrequired#

Must be application/json.

Body#

modelstringrequired#

The route name defined in your rolter.toml. Rolter rewrites this to the upstream model ID before forwarding. Returns 404 if no matching route exists.

promptstringrequired#

The text prompt the model completes. Unlike the chat endpoint, this is a plain string rather than a structured messages array.

max_tokensinteger#

Maximum number of tokens to generate in the completion. Many upstream providers require this field for the legacy endpoint; check your upstream’s documentation.

streamboolean#

Set to true to receive the completion as a Server-Sent Events stream. Each event carries a delta chunk; the stream terminates with data: [DONE].

Default: "false"

temperaturenumber#

Sampling temperature between 0 and 2. Passed through to the upstream and subject to the route’s param_policy.

stopstring | array#

One or more sequences at which the model stops generating.

top_pnumber#

Nucleus sampling probability mass.

Example#

curl http://localhost:4000/v1/completions \  -H "Authorization: Bearer sk-rolter-dev" \  -H "Content-Type: application/json" \  -d '{    "model": "gpt-4o",    "prompt": "Rust is",    "max_tokens": 50  }'

curl -N http://localhost:4000/v1/completions \  -H "Authorization: Bearer sk-rolter-dev" \  -H "Content-Type: application/json" \  -d '{    "model": "gpt-4o",    "prompt": "Rust is",    "max_tokens": 50,    "stream": true  }'

from openai import OpenAIclient = OpenAI(    base_url="http://localhost:4000/v1",    api_key="sk-rolter-dev",)response = client.completions.create(    model="gpt-4o",    prompt="Rust is",    max_tokens=50,)print(response.choices[0].text)

Response#

A successful non-streaming response follows the standard OpenAI completions shape:

{  "id": "cmpl-abc123",  "object": "text_completion",  "created": 1720000000,  "model": "gpt-4o",  "choices": [    {      "text": " a systems programming language focused on safety and performance.",      "index": 0,      "finish_reason": "stop"    }  ],  "usage": {    "prompt_tokens": 3,    "completion_tokens": 12,    "total_tokens": 15  }}

idstring#

Unique identifier for this completion, prefixed with cmpl-.

choicesarray#

Array of completion choices. Each entry contains:

Show Choice object fields

textstring#

The generated text continuation.

indexinteger#

Zero-based index of this choice.

finish_reasonstring#

Why generation stopped: stop, length, or content_filter.

usageobject#

Token counts for the request.

Show Usage fields

prompt_tokensinteger#

Tokens in the prompt.

completion_tokensinteger#

Tokens generated.

total_tokensinteger#

Sum of prompt and completion tokens.