Claude (Anthropic) 兼容说明

重要提示：我们提供兼容 Anthropic 标准的API服务，因此我们强烈推荐直接参考 Anthropic 官方 API 文档获取最全面、最新的参数细节和示例。以下是简化的接口概述，聚焦核心字段和使用说明。

接口概述

UModelverse 平台提供了与 Anthropic Claude API 兼容的 Messages 接口，开发者可以使用 Anthropic SDK 或其他支持的工具直接调用 Modelverse 上的 Claude 系列模型，无需额外适配开发。

核心接口信息

请求方法：POST
接口端点：https://api\.modelverse\.cn/v1/messages
认证方式：使用 API 密钥，通过以下任一方式传递
- 请求头：x\-api\-key: \{api\_key\}
- 请求头：Authorization: Bearer \{api\_key\}

关键说明： 1. /v1/messages 端点仅支持 Claude 系列模型；其他模型（如 GPT、Gemini、DeepSeek 等）请使用 OpenAI 兼容的 /v1/chat/completions 端点。 2. 虽然 Claude 和 OpenAI 都使用 /v1/models 接口获取模型列表，但两者的调用接口（生成响应的端点）不同，请勿混淆。

核心字段说明

以下仅列出核心请求和响应字段，详细参数请参考 Anthropic 官方文档。

请求字段（Request Parameters）

字段	类型	是否必需	默认值	含义与说明
`model`	string	是	无	模型 ID，如 `claude\-sonnet\-4\-5\-20250929`，指定生成响应的模型。
`messages`	array	是	无	对话消息列表。每个消息包含 `role`（取值：user/assistant）和 `content`（文本/图像内容）。
`max\_tokens`	integer	是	无	最大生成 token 数，控制响应长度，防止输出过长。
`system`	string/array	否	无	系统提示词，用于定义模型的行为和角色。
`temperature`	number	否	1.0	采样温度（取值 0 到 1），控制响应随机性：高值（接近1）更具创意，低值（接近0）更确定。
`top\_p`	number	否	无	核采样（取值 0 到 1），用于控制响应多样性。
`top\_k`	integer	否	无	Top-K 采样，仅从概率最高的 K 个 token 中采样。
`stop\_sequences`	array	否	无	停止序列列表，模型生成到该序列时将停止输出。
`stream`	boolean	否	false	是否启用流式响应，启用后将实时返回增量内容。
`metadata`	object	否	无	元数据对象，可包含 `user\_id` 等字段，用于追踪请求。
`tools`	array	否	无	可用工具列表，用于启用函数调用功能。
`tool\_choice`	object	否	auto	工具选择策略，如 `\{\&\#34;type\&\#34;: \&\#34;auto\&\#34;\}` 表示让模型自动决定是否调用工具。

响应字段（Response）

字段	类型	含义与说明
`id`	string	响应 ID，唯一标识此次请求的完成结果。
`type`	string	对象类型，固定为 `message`。
`role`	string	角色，固定为 `assistant`（模型响应角色）。
`content`	array	内容块列表，每个块包含 `type` 和对应内容（如 `text` 类型对应文本内容）。
`model`	string	此次请求使用的模型 ID。
`stop\_reason`	string	停止原因，取值包括：`end\_turn`（正常结束）、`max\_tokens`（达到最大token数）、`stop\_sequence`（触发停止序列）、`tool\_use`（调用工具）。
`stop\_sequence`	string	触发停止的序列（如适用，无则返回空）。
`usage`	object	使用统计，包含 `input\_tokens`（输入token数）和 `output\_tokens`（输出token数）。

快速开始

安装 Anthropic SDK

使用 Python 语言开发时，通过以下 pip 命令安装 Anthropic SDK：

pip install anthropic

接口调用示例

请将示例中的 \<MODELVERSE\_API\_KEY\> 替换为您自己的 API Key，$MODELVERSE\_API\_KEY 建议使用环境变量传递，避免硬编码。

1. Python 非流式调用

import anthropic

client = anthropic.Anthropic(
    api_key="<MODELVERSE_API_KEY>",
    base_url="https://api.modelverse.cn"
)

message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, how are you?"}
    ]
)

print(message.content[0].text)

2. Python 流式调用

import anthropic

client = anthropic.Anthropic(
    api_key="<MODELVERSE_API_KEY>",
    base_url="https://api.modelverse.cn"
)

with client.messages.stream(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Write a short story about AI."}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

3. curl 非流式调用

curl https://api.modelverse.cn/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $MODELVERSE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ]
  }'

4. curl 流式调用

curl https://api.modelverse.cn/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $MODELVERSE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ]
  }'

多模态支持

Claude 兼容接口支持图像输入，可通过 URL 方式 或 base64 编码方式 传递图像，适用于图像识别、图文问答等场景。

方式1：使用 URL 传递图像

import anthropic

client = anthropic.Anthropic(
    api_key="<MODELVERSE_API_KEY>",
    base_url="https://api.modelverse.cn"
)

# 使用 URL 传递图像
message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://umodelverse-inference.cn-wlcb.ufileos.com/ucloud-maxcot.jpg"
                    }
                },
                {
                    "type": "text",
                    "text": "What's in this image?"
                }
            ]
        }
    ]
)

print(message.content[0].text)

方式2：使用 base64 编码传递图像

import anthropic
import base64

client = anthropic.Anthropic(
    api_key="<MODELVERSE_API_KEY>",
    base_url="https://api.modelverse.cn"
)

# 使用 base64 编码图像
with open("image.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "What's in this image?"
                }
            ]
        }
    ]
)

print(message.content[0].text)

工具调用（Function Calling）

通过配置 tools 字段，可启用模型的工具调用功能，让模型根据用户需求自动调用指定工具（如查询天气、调用API等）。

import anthropic

client = anthropic.Anthropic(
    api_key="<MODELVERSE_API_KEY>",
    base_url="https://api.modelverse.cn"
)

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    }
]

message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    tools=tools,
    messages=[
        {"role": "user", "content": "What's the weather like in Beijing?"}
    ]
)

print(message.content)

注意事项

接口仅支持 Claude 系列模型，其他模型需使用对应兼容端点，避免调用失败。
API Key 建议通过环境变量传递，严禁在代码、文档中硬编码真实 Key，防止泄露。
多模态输入时，图像 URL 需可公开访问，base64 编码需确保格式正确（无多余空格、换行）。
流式响应与非流式响应的使用场景：需实时展示输出（如聊天界面）用流式，需完整结果（如批量处理）用非流式。
工具调用时，需确保 tools 字段的 input\_schema 格式正确，否则模型无法正常调用工具。
详细参数、异常处理及高级用法，请参考 Anthropic 官方 API 文档。