Messages（Anthropic） — Markdown 源文

> **AI Agents**: 索引 `/api/llms.txt` | 英文全文 `/api/llms-full-en.txt` | 中文全文 `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# Messages（Anthropic 兼容）

使用 **Anthropic Messages API** 格式创建模型回复，与 [OpenRouter `/v1/messages`](https://openrouter.ai/docs/api/api-reference/anthropic-messages/create-messages) 类似。

```
POST <BASE_URL>/v1/messages
```

适用于 **Anthropic SDK**、**Claude Code** 等期望原生 Anthropic 请求/响应形态的客户端。也可调用非 Anthropic 上游模型（网关转 OpenAI Chat Completions）。发图到 Claude 请用本接口。

## 认证

必需：`Authorization: Bearer <API_KEY>`（与 `/v1/chat/completions` 使用同一 SupaNexus API Key）。

## 请求头

| 头 | 必需 | 说明 |
|----|------|------|
| `Authorization` | 是 | Bearer API Key |
| `Content-Type` | 是 | `application/json` |
| `Idempotency-Key` | 否 | 24 小时内按 Key 去重 |
| `Accept-Language` / `X-Locale` | 否 | 部分错误文案本地化 |

## 请求体

SupaNexus 接受标准 Anthropic Messages JSON，识别 `model` 与 `stream` 参数。

```json
{
  "model": "anthropic/claude-3-5-sonnet",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "你好！"}
  ],
  "stream": false
}
```

| 字段 | 必需 | 说明 |
|------|------|------|
| `model` | 是 | `GET /v1/models` 返回的模型 id |
| `messages` | 是 | Anthropic 消息数组 |
| `max_tokens` | 是 | 最大输出 token（Anthropic 必填） |
| `system` | 否 | 系统提示（字符串或 content blocks） |
| `stream` | 否 | `true` 时返回 Anthropic SSE 事件流 |
| `temperature`、`top_p`、`stop_sequences` | 否 | 支持时透传 |
| `tools`、`tool_choice`、`thinking`、`metadata` | 否 | 按 Anthropic 兼容方式透传（如模型支持） |

## 多模态输入（图片）

当模型 `architecture.input_modalities` 包含 `"image"` 时，`messages[].content` 可为 **content block 数组**，同时携带文本与图片。

### Base64 图片示例

```json
{
  "model": "anthropic/claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg..."
          }
        },
        {"type": "text", "text": "请描述这张图片"}
      ]
    }
  ]
}
```

### URL 图片示例

```json
{
  "type": "image",
  "source": {
    "type": "url",
    "url": "https://example.com/photo.jpg"
  }
}
```

### 限制：OpenAI 协议上游模型

若目标模型的上游为 **OpenAI Chat Completions** 协议（非 `anthropic/*`），Anthropic image block **不会**被转换成 `image_url`，上游通常会拒绝请求。此时请改用 [`POST /v1/chat/completions`](./chat-completions.md) 与 OpenAI `image_url` 格式，详见 [参数 → 多模态输入](./parameters.md)。

**建议**：要发图片时，客户端协议须与模型上游协议一致——`anthropic/*` 用本端点，其余模型用 `/v1/chat/completions`。

## 非流式响应

Anthropic 形态 JSON：

```json
{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "claude-3-5-sonnet-20241022",
  "content": [{"type": "text", "text": "你好！有什么可以帮你的？"}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 12, "output_tokens": 8}
}
```

## 流式

`stream: true` 时返回 Anthropic 事件流（`message_start`、`content_block_delta`、`message_delta`、`message_stop`）。通用 SSE 说明见 [流式响应](./streaming.md)。

## 响应头（SupaNexus）

与 Chat Completions 相同：`X-SNX-Trace-ID`、`X-SNX-Model`、`X-SNX-Provider`。

## 错误格式

`/v1/messages` 返回 **Anthropic 形态**错误（非 OpenRouter 数字 `error.code`）：

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "you must provide a model parameter"
  }
}
```

| HTTP | 典型 `error.type` |
|------|-------------------|
| 400 | `invalid_request_error` |
| 401 | `authentication_error` |
| 402 | `billing_error` |
| 404 | `not_found_error` |
| 429 | `rate_limit_error` |
| 503 | `overloaded_error` |

若需要 OpenRouter 形态错误体，请使用 [`POST /v1/chat/completions`](./chat-completions.md)。

## OpenAI 与 Anthropic 端点对照

| 客户端 | 端点 | 错误体 |
|--------|------|--------|
| OpenAI SDK | `POST /v1/chat/completions` | OpenRouter `{error:{code,message}}` |
| Anthropic SDK / Claude Code | `POST /v1/messages` | Anthropic `{type,error:{type,message}}` |

两者共用 **同一 SupaNexus API Key**，路由、配额与计费逻辑一致。

## 相关

- [Anthropic SDK 集成](./anthropic-sdk-integration.md)
- [Chat Completions](./chat-completions.md)
- [认证](./authentication.md)
- [错误处理](./errors.md)