Text Completions

Some applications send a single prompt and expect a text-completions response instead of a chat message response. AISIX AI Gateway supports that OpenAI-compatible request shape through the completions proxy route.

Text completions are mainly useful for existing prompt-based clients. For new conversational applications, the chat-completions route usually gives broader provider support and chat-oriented client features.

Prerequisites

Before starting, prepare the following:

• A running AISIX gateway that can serve proxy requests.
• A caller API key that can access the model alias.
• A model alias backed by a provider and model that support text completions.

Send a Text-Completions Request

Send the request through the gateway proxy with the AISIX model alias in the request body:

curl -sS -X POST "http://127.0.0.1:3000/v1/completions" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-prod",
    "prompt": "Write one sentence about API gateways.",
    "max_tokens": 40
  }'

AISIX resolves the model alias, checks the caller API key, rewrites the upstream model ID, and forwards the remaining request body to the provider's completions endpoint.

The response keeps the OpenAI-compatible text-completions format:

{
  "id": "cmpl-***",
  "object": "text_completion",
  "model": "gpt-3.5-turbo-instruct",
  "choices": [
    {
      "text": "API gateways help manage, secure, and observe traffic between clients and services.",
      "index": 0,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 7,
    "completion_tokens": 13,
    "total_tokens": 20
  }
}

Provider and Gateway Behavior

The text-completions route is an OpenAI-compatible proxy path. Providers that support completions can receive the request through their configured adapter. Providers that do not support completions return 501 with error type not_implemented.

Input guardrails can inspect string prompts before AISIX calls the provider. Prompt arrays that contain strings are also inspectable. Token-ID prompts are forwarded, but they do not contain text for guardrails to scan.

Successful responses keep the OpenAI-compatible completions response format. When the upstream response includes token usage, AISIX records usage for the request.

Text-Completions Behavior

Use chat completions when the application can send role-based messages, use tools, stream assistant output, or work across the broadest set of configured provider backends.

If a request returns 501, the resolved provider path does not support text completions. Use a model backed by a provider that supports completions, or move the application to chat completions.

If an input guardrail does not block the prompt, check whether the prompt contains inspectable text. String prompts and arrays of strings can be scanned. Token-ID prompt arrays do not expose text to input guardrails.

Next Steps

You have now seen when to use text completions through AISIX and why chat completions are usually the better default for new integrations. For the main chat path, see OpenAI-Compatible API.