# POST /v1/messages

Anthropic 官方 `/v1/messages` 协议，字段与官方完全一致，现有 Anthropic SDK 代码几乎可直接迁移。

## 端点

```
POST https://relay.4aicode.net/v1/messages
```

## 请求

```http
POST /v1/messages HTTP/1.1
Host: relay.4aicode.net
Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx
anthropic-version: 2023-06-01
content-type: application/json

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "stream": true,
  "messages": [
    { "role": "user", "content": "Say hi" }
  ]
}
```

### 必填

| 字段 | 说明 |
|---|---|
| `model` | Claude 模型（Sonnet / Haiku / Opus 系列）或支持的 `gpt-*` 模型 |
| `max_tokens` | 最多生成 token 数 |
| `messages` | 对话数组 |

`/v1/messages` 会按 `model` 自动路由到对应的上游服务，支持 `claude-*` 和 `gpt-*` 模型。使用 Anthropic Messages 协议的客户端（如 Claude Code）可通过此接口接入这些模型。

### 常用可选

| 字段 | 说明 |
|---|---|
| `stream` | `true` 启用 SSE |
| `system` | 系统提示词 |
| `temperature` | 0~1 |
| `tools` | Function calling |
| `stop_sequences` | 遇到就停 |

## 流式响应

`stream: true` 返回 `text/event-stream`，事件序列与官方一致：

```
event: message_start
event: content_block_start
event: content_block_delta
event: content_block_stop
event: message_delta
event: message_stop
```

relay 全程不缓冲 SSE，首字节延迟基本等同直连。

## 非流式响应

```json
{
  "id": "msg_xxxx",
  "type": "message",
  "role": "assistant",
  "content": [{ "type": "text", "text": "Hi!" }],
  "model": "claude-sonnet-4-6",
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 8, "output_tokens": 3 }
}
```

`usage` 是计费依据（详见 [配额](/docs/guides/quota)）。

## ChatGPT 模型

Claude Code 使用 ChatGPT 模型时，只需要把模型设为支持的 `gpt-*`：

```bash
export ANTHROPIC_BASE_URL=https://relay.4aicode.net
export ANTHROPIC_AUTH_TOKEN=sk-4ai-xxxxxxxxxxxxxxxx
export ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-5.6-terra
export ANTHROPIC_DEFAULT_OPUS_MODEL_NAME="4AICode GPT 5.6 Terra"
export ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES=effort,xhigh_effort,thinking,adaptive_thinking,interleaved_thinking
export ANTHROPIC_MODEL=opus
export ANTHROPIC_DEFAULT_HAIKU_MODEL=gpt-5.4-mini
export CLAUDE_CODE_EFFORT_LEVEL=xhigh
claude --effort xhigh
```

`ANTHROPIC_DEFAULT_OPUS_MODEL` 会让 Claude Code 向 relay 请求 `gpt-5.6-terra`。`CLAUDE_CODE_EFFORT_LEVEL=xhigh` 会通过 Anthropic `output_config.effort` 映射到 OpenAI Responses `reasoning.effort=xhigh`。

支持的模型与 `/v1/chat/completions` 一致：`gpt-6-astra`、`gpt-6-sol`、`gpt-6.1-sol`、`gpt-6-luna`、`gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`、`gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`、`gpt-5.3-codex`。

## 错误

| HTTP | 含义 |
|---|---|
| **400** | 字段错误（缺 `max_tokens`、`model` 不存在等） |
| **401** | token 无效 |
| **403** | 团队被暂停 |
| **429** | 超限流或超配额 |
| **502** | 上游 Claude 抖动，重试即可 |
| **503** | 上游服务暂时不可用，详见 [服务冷却与重试](/docs/guides/account-cooldown) |

`503` 示例：

```json
{
  "code": "no_account_available",
  "message": "all accounts cooling down, retry in 60s"
}
```

## 完整例子（Python）

```python
from anthropic import Anthropic

client = Anthropic(
    base_url="https://relay.4aicode.net",
    api_key="sk-4ai-xxxxxxxxxxxxxxxx",
)

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=512,
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
```