Messages（Anthropic）

示例中的 <BASE_URL> 请从接入点选择并替换。

使用 Anthropic Messages API 格式创建模型回复。

POST <BASE_URL>/v1/messages

适用于 Anthropic SDK、Claude Code 等期望 Anthropic 请求/响应形态的客户端。也可用于非 Anthropic 模型（请求仍使用 Anthropic Messages 格式）。向 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 参数。

{
  "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 图片示例

{
  "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 图片示例

{
  "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 与 OpenAI image_url 格式，详见参数 → 多模态输入。

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

非流式响应

Anthropic 形态 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 说明见流式响应。

响应头（SupaNexus）

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

错误格式

/v1/messages 返回 Anthropic 形态错误（而非 Chat Completions 使用的数字 error.code）：

{
  "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`

若需要数字 error.code 形态的错误体，请使用 POST /v1/chat/completions。

OpenAI 与 Anthropic 端点对照

客户端	端点	错误体
OpenAI SDK	`POST /v1/chat/completions`	`{error:{code,message}}`（`code` 为 HTTP 状态码数字）
Anthropic SDK / Claude Code	`POST /v1/messages`	Anthropic `{type,error:{type,message}}`

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