Xikapi 接入文档

Messages API 完整指南 ​

Messages API 是 Anthropic Claude 的核心生成接口，适合文本生成、多轮对话、图像理解、工具调用、流式输出和结构化结果生成等场景。

在 Xikapi 中，请使用 Anthropic 兼容路径，并将请求域名替换为：

text
https://xikapi.com

常用请求地址：

text
https://xikapi.com/v1/messages

为什么使用 Messages API ​

Messages API 使用清晰的 system、messages、tools 等字段组织请求，适合把 Claude 接入到聊天助手、知识库问答、业务系统和自动化流程中。

它的常见优势包括：

  • 支持多轮消息上下文
  • 支持图像输入
  • 支持工具调用
  • 支持流式输出
  • 可通过 system 参数设置稳定角色和边界
  • 请求结构适合服务端统一封装

基础文本生成 ​

bash
curl https://xikapi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $XIKAPI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Explain in three sentences what Claude is best suited for"
      }
    ]
  }'

JavaScript：

javascript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.XIKAPI_API_KEY,
  baseURL: "https://xikapi.com",
});

const message = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "Introduce the Claude Messages API" }
  ],
});

console.log(message.content);

Python：

python
from anthropic import Anthropic

client = Anthropic(
    api_key="YOUR_XIKAPI_API_KEY",
    base_url="https://xikapi.com",
)

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Introduce the Claude Messages API"}
    ],
)

print(message.content)

system 参数 ​

Claude 的系统级指令放在顶层 system 字段中，不放在 messages 数组里。

json
{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "system": "You are a precise technical documentation assistant. Keep answers concise and accurate.",
  "messages": [
    {
      "role": "user",
      "content": "Explain why API keys should not be stored in frontend code"
    }
  ]
}

messages 数组 ​

messages 用来传入用户和助手的上下文。常见角色包括 user 和 assistant。

json
[
  { "role": "user", "content": "My system needs knowledge-base Q&A" },
  { "role": "assistant", "content": "You can split documents, retrieve relevant chunks, and use Claude to generate answers." },
  { "role": "user", "content": "What are good document chunking practices?" }
]

多轮对话 ​

服务端通常需要保存历史消息，并在下一轮请求中把必要上下文重新传给 Claude。

json
{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "messages": [
    { "role": "user", "content": "Summarize this contract" },
    { "role": "assistant", "content": "This contract mainly covers scope of services, fees, and breach clauses." },
    { "role": "user", "content": "Focus on payment risks" }
  ]
}

max_tokens ​

max_tokens 控制单次响应最多生成多少 token。生产环境建议显式设置，避免输出过长导致成本不可控。

场景建议
简短客服回复256 - 512
普通问答512 - 1024
长文档总结1024 - 4096
复杂分析按模型能力和业务预算设置

temperature ​

temperature 用于控制输出随机性。值越低，输出越稳定；值越高，表达越发散。

json
{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "temperature": 0.2,
  "messages": [
    { "role": "user", "content": "Classify this text as complaint, inquiry, or praise" }
  ]
}

stop_sequences ​

stop_sequences 用来指定停止生成的字符串，适合模板化输出或需要截断边界的场景。

json
{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "stop_sequences": ["</answer>"],
  "messages": [
    { "role": "user", "content": "Wrap the answer in <answer> tags" }
  ]
}

图像输入 ​

Claude 支持把图片作为用户消息内容的一部分，常见任务包括截图分析、票据识别、图表理解和图片问答。

json
{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "BASE64_IMAGE_DATA"
          }
        },
        {
          "type": "text",
          "text": "Analyze the main content of this image"
        }
      ]
    }
  ]
}

工具调用 ​

工具调用让 Claude 在需要外部信息或业务动作时返回 tool_use，由你的服务端执行工具，再把工具结果返回给 Claude。

json
{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_order_status",
      "description": "Check order status",
      "input_schema": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "string",
            "description": "Order ID"
          }
        },
        "required": ["order_id"]
      }
    }
  ],
  "messages": [
    { "role": "user", "content": "Check the status of order A1001" }
  ]
}

流式输出 ​

设置 stream: true 可以让服务端逐步接收输出，适合前端实时展示。

bash
curl https://xikapi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $XIKAPI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "Write a short article about API integration"
      }
    ]
  }'

错误处理 ​

常见错误包括：

状态码含义排查方向
400请求参数错误检查 JSON、模型名、字段类型
401鉴权失败检查 API Key 是否正确
403权限不足检查模型权限或账户权限
413请求过大压缩图片、裁剪上下文、拆分文档
429触发限流降低并发、增加重试、检查额度
500/503服务异常稍后重试，记录请求 ID

接入建议 ​

  • API Key 只放在服务端
  • 生产环境显式设置 max_tokens
  • 多轮对话只保留必要历史
  • 图像和长文档任务注意请求体大小
  • 工具调用结果必须经过权限校验
  • 所有 Anthropic 兼容请求地址统一使用 https://xikapi.com/v1/...