# POST /v1/chat/completions

OpenAI-compatible protocol with fields matching the official API. Intended for:

- Official OpenAI SDKs (`openai-python` / `openai` npm)
- Any OpenAI-compatible client that supports configuring `base_url`
- IDE plugins such as Cursor, Cline, and Continue
- Frameworks such as LangChain and LlamaIndex

## Endpoint

```
POST https://relay.4aicode.com/v1/chat/completions
```

## Request

```http
POST /v1/chat/completions HTTP/1.1
Host: relay.4aicode.com
Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx
content-type: application/json

{
  "model": "gpt-5.6-terra",
  "stream": true,
  "messages": [
    { "role": "system", "content": "You are helpful." },
    { "role": "user",   "content": "Write fizzbuzz in Go." }
  ]
}
```

## Supported Models

GPT-6:

| Model | Best for |
|---|---|
| `gpt-6-astra` | New-generation flagship; short-context input $1.50/M and output $7.50/M (15% of official price) |
| `gpt-6.1-sol` | GPT-6.1 flagship for complex coding and long-running tasks; $0.30/M input and $1.50/M output (15% of list price) |
| `gpt-6-sol` | GPT-6 flagship for complex coding and long-running tasks; $0.30/M input and $1.50/M output (15% of list price) |
| `gpt-6-luna` | Lightweight GPT-6 model for fast everyday tasks; $0.015/M input and $0.075/M output (15% of list price) |

GPT-5 series:

| Model | Best for |
|---|---|
| `gpt-5.6-sol` | Flagship model, prioritized for complex coding and long-running tasks; supports `max` reasoning effort |
| `gpt-5.6-terra` | Balanced tier with excellent value |
| `gpt-5.6-luna` | Fast and affordable; sufficient for everyday use |
| `gpt-5.5` | Previous-generation general-purpose model |
| `gpt-5.4` | General-purpose use |
| `gpt-5.4-mini` | Fast and affordable |
| `gpt-5.3-codex` | Code optimization |

Google Gemini:

| Model | Best for |
|---|---|
| `google/gemini-3.1-pro-preview` | Google Gemini Pro preview |
| `google/gemini-3-flash-preview` | Google Gemini Flash preview |
| `google/gemini-2.5-flash` | Stable Google Gemini Flash model |
| `google/gemini-2.5-pro` | Stable Google Gemini Pro model |

GPT-5.2 and earlier models have been deprecated upstream. Other models, such as `gpt-4o` and `gpt-4`, will be rejected with a `400` response whose error message includes a list of available models.

> Model availability depends on upstream support and service status. If the upstream service reports that a model is unsupported, the relay returns an explicit `400` response directly.

## Ignored Parameters

The following parameters are accepted but have no effect, ensuring SDK compatibility without errors:

- `logit_bias`
- `user`
- `functions` (use the newer `tools` instead)

## Response

Matches the official OpenAI response format:

- `choices[].message.content`
- `choices[].finish_reason`
- `usage` (`prompt_tokens` / `completion_tokens` / `total_tokens`)

Streaming format:

```
data: {"choices":[{"delta":{"content":"Hello"}}]}
data: {"choices":[{"delta":{"content":", world"}}]}
data: [DONE]
```

## Complete Examples

### Python

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://relay.4aicode.com/v1",
    api_key="sk-4ai-xxxxxxxxxxxxxxxx",
)

resp = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Introduce yourself in one sentence"},
    ],
)
print(resp.choices[0].message.content)
```

### TypeScript

```ts
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://relay.4aicode.com/v1",
  apiKey: process.env.OPENAI_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "gpt-5.4-mini",
  messages: [{ role: "user", content: "hi" }],
});
console.log(resp.choices[0].message.content);
```

## Errors

| HTTP | Meaning |
|---|---|
| **400** | Invalid field / model not in the allowlist |
| **401** | Invalid token |
| **403** | Team suspended |
| **429** | Rate limit or quota exceeded |
| **502** | Upstream OpenAI service instability |
| **503** | Upstream services are temporarily unavailable; see [Service Cooldowns and Retries](/docs/en/guides/account-cooldown) |

## Differences from `/v1/messages`

| Aspect | `/v1/messages` | `/v1/chat/completions` |
|---|---|---|
| Protocol | Anthropic | OpenAI |
| Available models | All Claude models | `gpt-5*` / `google/gemini-*` |
| Required fields | `max_tokens` | — |
| Usage fields | `input_tokens` / `output_tokens` | `prompt_tokens` / `completion_tokens` |