---
title: "Create an OpenAI-format chat completion"
method: POST
path: "/api/{provider}/v1/chat/completions"
tags: ["Provider Gateway"]
---

# Create an OpenAI-format chat completion

`POST /api/{provider}/v1/chat/completions`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/{provider}/v1/chat/completions`
- Auth: HTTP bearer

Relay an OpenAI-format chat completions payload to one provider and get that provider's response back byte for byte. Respan authenticates the request, applies your [limits](/docs/documentation/features/gateway/limits), and logs it, but doesn't translate the request or recompute usage. Respan removes `respan_params` and merges a literal `extra_body` object into the body; unknown and provider-only fields are passed through. Streams are relayed frame by frame, and requests time out after 600 seconds.

`{provider}` is a provider with an OpenAI-format API, such as `openai`, `azure_openai`, `xai`, `groq`, `mistral`, `deepseek`, `togetherai`, `fireworks`, or `perplexity`. A provider without an OpenAI-format API returns `404`. A provider with no fixed public endpoint, such as Azure OpenAI, needs the provider URL saved with its key; without it the request returns `400`. Anthropic, Google and OpenRouter have their own endpoints.

Upstream, Respan sends only `accept`, `accept-language`, `content-type`, `user-agent`, and headers that start with `x-` plus the provider ID, with `_` written as `-` (for example `x-azure-openai-`). The response includes `X-Respan-Log-Id`, `X-Respan-Upstream-Request-Id`, and the provider's `x-ratelimit-*` and `retry-after` headers.

The example uses `openai` with `gpt-6-luna`. If you select another provider, use that provider's model ID and a model supported on Respan credits, or configure your provider key in Settings > Providers.

## Path parameters

- `provider` string, required

## Request body

- object
  - `model` string, required: The provider's own model ID.
  - `messages` object[], required: Chat messages in OpenAI format.
  - `stream` boolean: Stream the provider's response as server-sent events.
  - `respan_params` object: Respan parameters such as `customer_identifier` or `metadata`. Removed before the request is forwarded.

## Response `200`

The provider's response, unchanged.

- object

## Other responses

- `400`: No endpoint is known for the provider: save the provider URL with its key. Otherwise, the provider's own `400`.
- `401`: No usable key for the provider. The code is `activation_required` when your organization has no credits and no provider key for the model.
- `402`: The request's customer is over their budget.
- `403`: The API key is missing, invalid or expired.
- `404`: The provider isn't available on this route.
- `429`: Your Respan key's rate limit or an API key limit's block rule, or the provider's own `429`.

## Changes

- **2026-10-21** `c30bcb383ee8`: 1 breaking, 4 info
  - request body became required
  - api operation id `providerGateway_createProviderChatCompletion` removed and replaced with `createProviderChatCompletion`
  - api tag `Provider Gateway` added
  - api tag `providerGateway` removed
  - …1 more
- **2026-10-02** `b830b79cfd52`: 1 info
  - endpoint added

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

---

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