---
title: "Create a chat completion"
method: POST
path: "/chat/completions"
tags: ["Run a model"]
---

# Create a chat completion

`POST /chat/completions`

## Request

- Base URL: `https://api.hedra.com/v3`
- URL: `https://api.hedra.com/v3/chat/completions`
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer

OpenAI-compatible chat completions. Errors use the v3 error body, which the OpenAI SDKs parse: `error.code`, `error.param` and `error.type` populate the SDK exception, and the `x-should-retry` header tells the SDK whether to retry. An empty API wallet answers 402 (deliberate divergence from OpenAI's 429 `insufficient_quota`: retrying cannot fix an empty wallet). With `stream: true` the response is `text/event-stream` in the OpenAI chunk dialect, terminated by `data: [DONE]`; a failure after streaming has begun is delivered as one in-band `data: {"error": ...}` event carrying the same error body. Errors before the first byte are JSON responses. A top-level field the model's `input_schema` does not list is ignored, except `audio`, `functions` and `function_call`, which get a 400.

## Response `200`

Successful Response

- unknown

## Other responses

- `400`: Invalid or failed-validation request.
- `401`: Authentication failed: missing, malformed, or invalid credentials.
- `402`: The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.
- `403`: Insufficient scope or plan.
- `404`: Resource not found.
- `429`: Rate limit exceeded.
- `500`: Internal error.
- `503`: The model is temporarily unavailable.
- `504`: The model did not answer in time.

## Changes

- **2026-10-16** `06692d16e78a`: 1 info
  - endpoint added

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

---

[API](https://skmtc.dev/hedra-labs/apis/hedra-api.md) - [All operations](https://skmtc.dev/hedra-labs/apis/hedra-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hedra-labs/apis/hedra-api/revisions/6ef35a11cefe?raw)