Anthropic 兼容

Messages

用 Anthropic Messages 格式调用 NoviaHub 上的模型：地址、请求头、请求参数、响应、流式事件和示例代码。

与 Anthropic 的 Messages 接口兼容。Claude Code 等工具使用的就是这个接口。

POST https://noviahub.com/v1/messages

适用于端点标签里有 Anthropic 的模型（在模型&价格页面查看）。用它调用非 Claude 模型时，NoviaHub 会自动做协议转换，注意事项见协议转换兼容性。

请求头

请求头	必填	说明
`x-api-key`	二选一	你的 API 密钥。
`Authorization`	二选一	`Bearer <你的 API 密钥>`，与 `x-api-key` 任选其一。
`anthropic-version`	否	协议版本。不传时，NoviaHub 转发给上游时会使用 `2023-06-01`。
`anthropic-beta`	否	启用 Anthropic 的测试功能，会原样转发给上游。能否生效取决于模型。
`Content-Type`	是	`application/json`

请求参数

下表列出 NoviaHub 能识别并转发的参数。参数最终是否生效，取决于模型本身是否支持。

参数	类型	必填	说明
`model`	string	是	模型 ID，例如 `claude-sonnet-5`。
`messages`	array	是	对话消息，结构见下文。
`max_tokens`	integer	是	最多生成多少 token。Anthropic 协议要求必填；NoviaHub 本身不检查，缺少时由上游决定是否报错。
`system`	string / array	否	系统提示词，可以是字符串，也可以是文本块数组（可带 `cache_control`）。
`temperature`	number	否	采样温度。
`top_p`	number	否	核采样。
`top_k`	integer	否	Top-K 采样。
`stop_sequences`	array	否	遇到这些字符串时停止。
`stream`	boolean	否	`true` 时以流式（SSE）返回。
`tools`	array	否	可供模型调用的工具。
`tool_choice`	object	否	工具选择方式。
`thinking`	object	否	扩展思考设置，如 `{"type": "enabled", "budget_tokens": 2048}`。
`metadata`	object	否	附加信息，原样转发。
`output_config`、`output_format`	object	否	输出设置，原样转发。
`context_management`、`container`、`mcp_servers`、`cache_control`	—	否	按 Anthropic 规范原样转发。

messages 的结构

每条消息包含 role（user 或 assistant）和 content。content 可以是一段文字，也可以是内容块数组，按 Anthropic 规范书写，例如：

文字块：{"type": "text", "text": "..."}
图片块：{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "..."}}
工具调用与结果：tool_use、tool_result
思考块：thinking（含 signature）

示例代码

curl https://noviahub.com/v1/messages \
  -H "x-api-key: $NOVIAHUB_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "用一句话解释什么是 API。"}]
  }'

import os

import anthropic

client = anthropic.Anthropic(
    base_url="https://noviahub.com",
    api_key=os.environ["NOVIAHUB_API_KEY"],
)

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "用一句话解释什么是 API。"}],
)

print(message.content[0].text)

import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic({
  baseURL: 'https://noviahub.com',
  apiKey: process.env.NOVIAHUB_API_KEY,
})

const message = await client.messages.create({
  model: 'claude-sonnet-5',
  max_tokens: 1024,
  messages: [{ role: 'user', content: '用一句话解释什么是 API。' }],
})

console.log(message.content[0].type === 'text' ? message.content[0].text : message.content)

注意 Anthropic SDK 的 base_url 只填 https://noviahub.com，不要带 /v1。

响应

字段	说明
`id`	本次回复的 ID。
`type`	固定为 `message`。
`role`	固定为 `assistant`。
`model`	模型 ID。
`content[]`	回复内容块，文字在 `type` 为 `text` 的块的 `text` 字段；还可能有 `thinking`、`tool_use` 等块。
`stop_reason`	停止原因，如 `end_turn`（正常结束）、`max_tokens`（达到长度上限）、`tool_use`（要调用工具）。
`usage.input_tokens`	输入 token 数。
`usage.output_tokens`	输出 token 数。
`usage.cache_creation_input_tokens`	写入缓存的输入 token 数。
`usage.cache_read_input_tokens`	从缓存读取的输入 token 数。

{
  "id": "msg_mock123",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5",
  "content": [{ "type": "text", "text": "Hello from the mock upstream." }],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 7,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

流式输出

加 "stream": true 后，响应以 SSE 事件返回，事件顺序与 Anthropic 官方一致：

message_start：开始，包含消息的基本信息。
content_block_start：一个内容块开始。
content_block_delta：内容块的增量，文字在 delta.text（delta.type 为 text_delta）。
content_block_stop：内容块结束。
message_delta：结束原因（delta.stop_reason）和用量（usage）。
message_stop：全部结束。

用量以 message_delta 事件里的 usage 为准。NoviaHub 会在这里补上 input_tokens，方便你一次拿到输入和输出的数量。

event: message_start
data: {"type":"message_start","message":{"id":"msg_mock123","type":"message","role":"assistant","model":"claude-sonnet-5","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"output_tokens":1,"cache_creation_input_tokens":0,"cache_read_input_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" from the mock upstream."}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":7,"input_tokens":12}}

event: message_stop
data: {"type":"message_stop"}

Python
TypeScript

import os

import anthropic

client = anthropic.Anthropic(
    base_url="https://noviahub.com",
    api_key=os.environ["NOVIAHUB_API_KEY"],
)

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "写一首四句的短诗。"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic({
  baseURL: 'https://noviahub.com',
  apiKey: process.env.NOVIAHUB_API_KEY,
})

const stream = client.messages.stream({
  model: 'claude-sonnet-5',
  max_tokens: 1024,
  messages: [{ role: 'user', content: '写一首四句的短诗。' }],
})

stream.on('text', (text) => process.stdout.write(text))
await stream.finalMessage()

不支持的功能

POST /v1/messages/count_tokens（计算 token 数）不可用，调用会返回 404。

常见错误

/v1/messages 的错误有两种结构，见 API 概览 · 错误格式。

HTTP 状态码	原因
400	缺少 `model`，或请求体不是合法 JSON。
401	密钥无效、已禁用、已过期或额度已用完。
403	密钥不允许使用这个模型、IP 不在白名单，或账户余额不足。
503	模型 ID 写错，或该模型当前没有可用线路。

完整说明见错误码与排查。