---
title: "Chat completions (OpenAI-compatible)"
method: POST
path: "/v1/chat/completions"
tags: ["openai-compat"]
---

# Chat completions (OpenAI-compatible)

`POST /v1/chat/completions`

OpenAI-compatible chat completions endpoint. Works with the OpenAI Python SDK by setting `base_url="https://api.pioneer.ai/v1"`. Set `stream=true` for SSE streaming. The response includes a `x_pioneer` extension field with `inference_id` and `routed_model`.

## Request body

- ChatCompletionRequest
  - `model` string, required — Model ID, project name, or `pioneer/auto` for automatic routing.
  - `messages` object[], required
    - `role` string
    - `content` union
      - string
      - object[]
    - `tool_calls` unknown[]
      - unknown
    - `tool_call_id` string
  - `temperature` number
  - `max_tokens` integer
  - `stream` boolean
  - `stop` union
    - string
    - string[]
  - `response_format` object
  - `tools` unknown[]
    - unknown
  - `tool_choice` union
    - string
    - object
  - `top_p` number
  - `store` boolean — Persist to inference history. Set false to opt out.
  - `metadata` object — Pioneer reads `metadata.project_id` for attribution.
  - `reasoning` object — Opt-in reasoning controls (OpenRouter-normalized). Keys: enabled, effort (minimal/low/medium/high/xhigh/none), max_tokens, exclude, mode (manual/adaptive, Anthropic-only), display (summarized/omitted, Anthropic-only). effort and max_tokens are mutually exclusive.
  - `schema` union — Pioneer encoder extension: extraction schema dict.
    - object
    - string[]
  - `seed` integer
  - `n` integer
  - `presence_penalty` number
  - `frequency_penalty` number
  - `user` string

## Response `200`

Chat completion result. Returns `application/json` when `stream=false` (default) and `text/event-stream` SSE when `stream=true`. Each SSE event is `data: {...}\n\n` terminated by `data: [DONE]\n\n`.

- ChatCompletionResponse
  - `id` string, required
  - `object` 'chat.completion', required
  - `created` integer, required
  - `model` string, required
  - `choices` object[], required
    - `index` integer
    - `message` object
    - `finish_reason` string
  - `usage` UsageStats, required
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer
    - `prompt_tokens_details` object
      - `cached_tokens` integer — Input tokens served from cache (cache read).
      - `cache_write_tokens` integer — Input tokens written to cache (cache creation).
  - `x_pioneer` PioneerExtension — Pioneer-specific extension on OpenAI-compatible responses.
    - `inference_id` string — Pioneer inference record ID. Use with GET /inferences/{inference_id} to poll for async LLM-judge results. Null when persistence was disabled.
    - `routed_model` string — Actual backend model selected by a router project (e.g. `pioneer/auto`). Null when not routed.

## Other responses

- `401` — Missing or invalid API key.
- `402` — Insufficient credits or no active billing plan.
- `404` — Model ID not found or not yet deployed.
- `422` — Request body failed schema validation.
- `429` — Rate limit exceeded. Retry after the duration in the `Retry-After` response header.

---

[API](https://skmtc.net/fastino-ai/apis/pioneer-inference-api.md) · [All operations](https://skmtc.net/fastino-ai/apis/pioneer-inference-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fastino-ai/pioneer-inference-api/revisions/2541b0de636c/schema)