---
title: "Generate a chat completion"
method: POST
path: "/v1/chat/completions"
tags: ["Chat Completions"]
---

# Generate a chat completion

`POST /v1/chat/completions`

## Request

- Base URL: `https://inference.openrelay.inc`
- URL: `https://inference.openrelay.inc/v1/chat/completions`
- Auth: HTTP bearer

Generates a model response for a conversation in the OpenAI Chat Completions shape, from any model whose supported APIs include chat completions.
The hand-written `orl chat` is the friendlier front for this operation: model name completion, a readable transcript, and streaming output rendered to the terminal.

Requires a funded balance. Set "stream" to true to receive the completion incrementally as Server-Sent Events, ending with a `data: [DONE]` sentinel. The request body is capped at 10 MiB.

Requires the `inference.invoke` permission. See [Permissions](https://docs.openrelay.inc/docs/permissions) for the roles and API key permissions that include it.

## Request body

- ChatCompletionRequest: An OpenAI-compatible chat completions request. Opaque: unlisted OpenAI sampling and control parameters (temperature, top_p, stop, presence_penalty, frequency_penalty, seed, stream_options, ...) are forwarded as sent; unsupported ones are ignored rather than rejected.
  - `max_completion_tokens` integer: Upper bound on the number of tokens to generate.
  - `messages` object[], required: The conversation so far: {role, content} objects (system, user, assistant).
  - `model` string, required: An OpenRelay public model id, e.g. openrelay/gpt-oss-120b.
  - `stream` boolean: Stream the response as Server-Sent Events.

## Response `200`

OK

- ChatCompletionResponse: An OpenAI chat.completion object (opaque; additionalProperties carries the rest of the dialect).
  - `choices` object[]
  - `id` string
  - `model` string: Always the public OpenRelay model id requested.
  - `object` 'chat.completion'
  - `openrelay` OpenRelayResponseMeta: What the request is billed, on every online inference response.
    - `cost_nano_usd` integer: What this call is billed, in nanoUSD. Also sent as the OpenRelay-Cost-Nano-USD header.
    - `priced_at` string: Pricing basis, e.g. online.
  - `usage` object

## Other responses

- `400`: The request is invalid
- `401`: Missing or invalid API key
- `402`: Refused for spend: the organization's balance is below the spend floor (insufficient_balance), or the API key's spend budget is used up (key_budget_exceeded)
- `403`: Refused, type permission_error. An inference call, a batch create or a file upload is refused while the account is unavailable, paused or under review (account_suspended, account_unavailable) or being verified (account_pending_verification), and an inference call names a model that takes an access request first (model_access_required). With permissions enabled, a role, key restriction, network rule or policy refuses the request (permission_denied, with permission and denied_by), or the model is outside the key's, role's or organization's model list (model_not_allowed, with permission, denied_by, model and allowed_models_hint); the OpenRelay-Required-Permission header names the permission.
- `413`: The upload exceeds the 200 MB limit
- `429`: Too many concurrent uploads; retry shortly
- `503`: The action could not be dispatched; retry

## Changes

- **2026-10-26** `7fe59d94a9f5`: 31 info
  - added the non-success response with the status `403`
  - added the optional property `error/allowed_models_hint` to the response with the `400` status
  - added the optional property `error/allowed_models_hint` to the response with the `401` status
  - added the optional property `error/allowed_models_hint` to the response with the `402` status
  - …27 more
- **2026-10-21** `dc9750cb25b5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/openrelay/apis/openrelay-api/changes/v1/chat/completions/post.md)

---

[API](https://skmtc.dev/openrelay/apis/openrelay-api.md) - [All operations](https://skmtc.dev/openrelay/apis/openrelay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/openrelay/apis/openrelay-api/revisions/7fe59d94a9f5?raw)