> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viviai.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Anthropic 原生接口

> 使用 Messages 协议调用 Claude 系列模型，配置系统指令、消息和流式输出。

## 请求地址

```http theme={null}
POST https://api.viviai.cc/v1/messages
```

## 鉴权与协议版本

```http theme={null}
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
Content-Type: application/json
```

使用 ViVi-API API Key。本文按 `2023-06-01` 版本展示 Messages 基础格式；如模型或接入渠道要求其他版本，请按要求调整，不能仅因上游新增版本就假设网关已支持。

> [!NOTE]
>
> `YOUR_ANTHROPIC_MODEL` 是占位符，请替换为账号实际可用、支持 Anthropic Messages 协议的完整模型 ID。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | 完整模型 ID。 |
| `max_tokens` | integer | 是 | 最大生成 token 数，示例使用 1024。 |
| `messages` | array | 是 | 按顺序排列的用户与助手消息。 |
| `messages[].role` | string | 是 | `user` 或 `assistant`。 |
| `messages[].content` | string / array | 是 | 文本，或模型支持的内容块。 |
| `system` | string / array | 否 | 顶层系统指令。 |
| `stream` | boolean | 否 | 设置为 `true` 时返回 SSE 事件流。 |
| `temperature` | number | 否 | 采样参数；具体支持情况依模型而定。 |
| `stop_sequences` | array | 否 | 自定义停止字符串。 |

系统指令放在顶层 `system` 中，不要在 `messages` 里添加 `role: "system"`。启用思考、工具等高级能力前，请确认模型及接入渠道支持情况。

## 调用示例

先设置环境变量 `VIVI_API_KEY`，方法见[快速开始](https://docs.viviai.cc/quickstart.md)。cURL 使用 Bash 语法。

```bash cURL theme={null}
curl --fail-with-body https://api.viviai.cc/v1/messages \
  -H "x-api-key: $VIVI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_ANTHROPIC_MODEL",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "请用三句话介绍 API。"}
    ]
  }'
```

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://api.viviai.cc/v1/messages",
    headers={
        "x-api-key": os.environ["VIVI_API_KEY"],
        "anthropic-version": "2023-06-01",
    },
    json={
        "model": "YOUR_ANTHROPIC_MODEL",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "请用三句话介绍 API。"}],
    },
    timeout=120,
)
response.raise_for_status()
data = response.json()
print("".join(
    block["text"] for block in data.get("content", [])
    if block.get("type") == "text"
))
```

Python 示例需先执行 `python -m pip install requests`。

## 返回结果

以下为结构示意。`content` 是内容块数组，业务代码应按 `type` 读取。

```json theme={null}
{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "model": "YOUR_ANTHROPIC_MODEL",
  "content": [{"type": "text", "text": "API 是应用之间通信的接口。"}],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {"input_tokens": 20, "output_tokens": 15}
}
```

| 字段 | 说明 |
| - | - |
| `content` | 输出内容块。本文读取 `type: "text"` 的块。 |
| `stop_reason` | 结束原因。`end_turn` 表示本轮结束，`max_tokens` 表示达到生成上限。 |
| `usage` | 输入与输出 token 用量，其他字段依模型和功能而定。 |

若使用工具，可能收到 `tool_use` 内容块和对应停止原因；不要将其当作普通文本。

## 系统指令与多轮对话

```json theme={null}
{
  "model": "YOUR_ANTHROPIC_MODEL",
  "max_tokens": 1024,
  "system": "你是一名耐心的编程助手，请使用中文回答。",
  "messages": [
    {"role": "user", "content": "我正在学习 Python。"},
    {"role": "assistant", "content": "你想先学习哪部分？"},
    {"role": "user", "content": "请介绍列表。"}
  ]
}
```

每次请求都需要发送必要的历史消息；模型的上下文长度与输出上限依所选模型而定。

## 流式输出

```bash theme={null}
curl --no-buffer --fail-with-body https://api.viviai.cc/v1/messages \
  -H "x-api-key: $VIVI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_ANTHROPIC_MODEL",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "写一段简短的欢迎语。"}]
  }'
```

常见事件顺序为 `message_start` → `content_block_start` → `content_block_delta` → `content_block_stop` → `message_delta` → `message_stop`。中间可能穿插 `ping` 或错误事件。

```text theme={null}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"你好"}}
```

仅在 `delta.type` 为 `text_delta` 时读取 `delta.text`。工具参数、思考等增量具有其他结构；发生流中错误时，即使最初 HTTP 状态为 200，也应按失败处理。

## 接入提示

* `max_tokens` 是必填参数。
* 版本号写在 `anthropic-version` 请求头中。
* 返回文本位于 `content` 数组中，不是 `choices[0].message.content`。
* 接入失败时，查看返回的错误正文，并对照[错误排查](https://docs.viviai.cc/quickstart.md#常见问题)。

协议参考：[Anthropic Messages](https://platform.claude.com/docs/en/api/messages/create) · [API 版本说明](https://platform.claude.com/docs/en/api/versioning)。ViVi-API 的模型范围与可选功能以实际服务为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.