---
title: "Text Completions"
method: POST
path: "/v1/completions"
tags: ["openai-compat"]
---

# Text Completions

`POST /v1/completions`

OpenAI-compatible text completions endpoint.

Thin shell over :func:`services.inference.adapters.openai_text.run_text_completion`.
The adapter handles project routing, dispatch (LLM passthrough vs
Pioneer-task), SSE rendering, persistence, and error mapping. The
router keeps only HTTP-shaped concerns: route declaration, auth,
rate limiting.

Args:
    body: Validated :class:`TextCompletionRequest`.
    request: FastAPI request (forwarded so the adapter can read
        API-key billing context out of ``request.state`` for
        streaming responses).
    auth: Authenticated request context.

Returns:
    :class:`TextCompletionResponse` for non-streaming, or a
    :class:`StreamingResponse` of ``text_completion`` SSE events
    terminated by ``data: [DONE]`` when ``body.stream`` is true.

## Request body

- TextCompletionRequest — OpenAI-compatible text completion request.
  - `model` string, required
  - `prompt` string, required
  - `temperature` number, nullable
  - `max_tokens` integer, nullable
  - `stop` union
    - string[]
    - string
  - `echo` boolean
  - `logprobs` integer, nullable
  - `stream` boolean, nullable
  - `extra_body` object, nullable
  - `reasoning` object, nullable — Opt-in reasoning / extended-thinking controls. Accepts the OpenRouter-normalized shape (``enabled``, ``max_tokens``, ``effort``, ``exclude``); ``effort`` and ``max_tokens`` are mutually exclusive. Pioneer extensions for Claude routes: ``mode`` (manual/adaptive) and ``display`` (summarized/omitted). Pioneer canonicalizes this and renders each provider's native field at the wire boundary.
  - `store` boolean
  - `schema` union — Schema for the Pioneer encoder. **Deprecated when supplied as a flat list** of entity labels; use the unified dict shape instead. Deprecated submissions emit ``Deprecation: true`` and ``Sunset: <RFC 7231 date>`` headers.
    - string[]
    - object
  - `task_type` string, nullable — **Deprecated.** Legacy task hint. The unified schema disambiguates the task automatically. Submitting this field emits ``Deprecation: true`` and ``Sunset: <RFC 7231 date>`` headers.
  - `include_confidence` boolean
  - `include_spans` boolean
  - `effort` 'low' | 'medium' | 'high' | 'xhigh' | 'max' — Per-request routing-effort tier, ascending in cost and quality. A router-agnostic label the caller sends as the ``effort`` param (or as a ``model`` suffix). Each router type maps these tiers to its own concrete policy via its :class:`RouterProfile`.
  - `models` string[], nullable — Per-request candidate-model subset the router may select between. Overrides the router's stored candidate set for this request only; ignored for non-router models.

## Response `200`

Text completion. Returns ``application/json`` (``TextCompletionResponse``) by default, or ``text/event-stream`` of ``TextCompletionStreamChunk`` events terminated by ``data: [DONE]`` when ``stream=true``.

- TextCompletionResponse — OpenAI-compatible text completion response.
  - `id` string
  - `object` string
  - `created` integer
  - `model` string, required
  - `choices` TextCompletionChoice[], required
    - `index` integer
    - `text` string
    - `logprobs` object, nullable
    - `finish_reason` string, nullable
    - `reasoning_content` string, nullable
  - `usage` ChatCompletionUsage, required — Token usage statistics. ``prompt_tokens`` follows the upstream wire contract — *includes* every input class (non-cached, cache read, and cache write). The breakdown is exposed under ``prompt_tokens_details`` so consumers can attribute the cached-read and cache-write subsets. Cache-aware billing on the brain side reads the canonical ``InferenceUsage`` fields directly, not this wire payload.
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer
    - `prompt_tokens_details` PromptTokensDetails — Per-input-class breakdown for OpenAI-shape usage payloads. Mirrors OpenAI's ``prompt_tokens_details`` block and OpenRouter's cache-creation extension so clients reading ``usage.prompt_tokens_details.cached_tokens`` / ``cache_write_tokens`` keep working when Pioneer relays a cache-aware upstream response. Both counts are subsets of ``prompt_tokens`` on the wire — that's the upstream contract Pioneer relays faithfully. Attributes: cached_tokens: Input tokens served from the upstream prompt cache (cache read). cache_write_tokens: Input tokens written into the upstream prompt cache (cache creation). ``0`` for upstreams that bill writes as plain input (OpenAI, Fireworks, vLLM).
      - `cached_tokens` integer
      - `cache_write_tokens` integer
  - `x_pioneer` PioneerExtension — Pioneer-specific extension fields appended to OpenAI-compatible responses. OpenAI's API contract reserves the unprefixed top-level keys (``id``, ``choices``, ``usage``, …); custom data must live under a clearly namespaced key. ``x_pioneer`` is that key. Attributes: inference_id: The Pioneer-side identifier of the persisted ``inferences`` row associated with this completion. Present when persistence is enabled (``extra_body.store == True``) and the row was successfully recorded; ``None`` for ad-hoc requests that opted out of persistence. The frontend uses this to poll ``GET /inferences/{id}`` for asynchronous judge results without coupling the inference response latency to the judge. routed_model: Backend catalog model selected by a router project (for example ``pioneer/auto``). ``None`` when the request was not routed or the routed model matches the requested id. savings: Routed-vs-frontier per-1M-token savings rate diff (same wire shape as the Anthropic ``pioneer_savings`` extension). The Codex routing-savings hook multiplies these rates by per-turn token usage to surface cumulative money saved. ``None`` when the request was not routed below the frontier reference model.
    - `inference_id` string, nullable
    - `routed_model` string, nullable
    - `savings` object, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/pioneer/apis/brain-api.md) · [All operations](https://skmtc.net/pioneer/apis/brain-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pioneer/brain-api/revisions/31dfe831e079/schema)