Claude 高级能力接入说明

Xima AI 支持通过 OpenAI-compatible Chat Completions 和 Anthropic native Messages 调用 Claude 模型。普通对话可以沿用 OpenAI SDK；如果需要 Claude 原生 thinking、prompt cache、tool result、图片内容块等能力，建议使用 Anthropic native Messages。

接入信息

项目	值
控制台	`https://console.xima.ai/`
OpenAI-compatible Base URL	`https://console.xima.ai/v1`
OpenAI-compatible Endpoint	`POST /v1/chat/completions`
Anthropic native Endpoint	`POST /v1/messages`
认证方式	`Authorization: Bearer <XIMA_API_KEY>`

建议先配置环境变量：

bash

export XIMA_API_KEY="sk-替换为你的APIKey"
export XIMA_BASE_URL="https://console.xima.ai"
export XIMA_CLAUDE_MODEL="xima/claude-sonnet-4-6"

模型选择

模型 ID	建议用途
`xima/claude-haiku-4-5-20251001`	低成本、高并发、轻量问答、分类、摘要、简单提取
`xima/claude-sonnet-4-6`	默认推荐；通用问答、代码、复杂摘要、工具调用、稳定生产任务
`xima/claude-opus-4-6`	高复杂度推理、代码审查、Agent 任务
`xima/claude-opus-4-7`	高复杂度推理、长任务、多步骤规划
`xima/claude-opus-4-8`	高难度分析、复杂代码和高级 Agent 场景

首次接入建议使用 xima/claude-sonnet-4-6。如果业务对成本更敏感，可以切到 Haiku；如果需要更强推理能力，再切到 Opus 系列。

入口选择

入口	适合场景	注意事项
OpenAI-compatible Chat Completions	已有 OpenAI SDK、OpenAI Chat 消息结构或兼容 OpenAI 的业务框架	不要直接传 Claude 原生 `thinking`、`cache_control`、`tool_result` 等字段
Anthropic native Messages	已有 Anthropic Messages 消息结构，或需要 Claude 原生 thinking、prompt cache、tool result、图片内容块	可以覆盖普通对话、流式输出、工具调用、图片、长上下文和 Claude 原生能力

能力选择速查：

需求	OpenAI-compatible 写法	Anthropic native 写法	建议
普通文本	`messages[].content` 字符串	`messages[].content` 字符串或内容块	按现有 SDK 选择
流式输出	`stream: true`	`stream: true`	按现有 SDK 选择
工具调用	`tools`、`tool_calls`	`tools`、`tool_use`	不要混用字段
工具结果闭环	`role: "tool"` + `tool_call_id`	`type: "tool_result"`	按协议回传工具结果
图片输入	`image_url` 内容块	`image` + `source` 内容块	按协议填写图片块
Claude thinking	可用 `reasoning_effort` 做轻量适配	原生 `thinking`	需要 Claude 原生证据时用 `/v1/messages`
Prompt cache	不建议在 Chat 示例里传 `cache_control`	原生 `cache_control`	需要缓存时用 `/v1/messages`

文本调用

OpenAI-compatible

bash

curl -sS "$XIMA_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$XIMA_CLAUDE_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "用三句话介绍 Xima AI 的 Claude 模型接入方式。"
      }
    ],
    "max_tokens": 512
  }'

成功时通常从 choices[0].message.content 读取回答，并从 usage 中查看 token 使用量。

Anthropic native

bash

curl -sS "$XIMA_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "'"$XIMA_CLAUDE_MODEL"'",
    "max_tokens": 512,
    "messages": [
      {
        "role": "user",
        "content": "用三句话介绍 Xima AI 的 Claude 模型接入方式。"
      }
    ]
  }'

SDK 示例

Python OpenAI SDK

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XIMA_API_KEY"],
    base_url="https://console.xima.ai/v1",
)

response = client.chat.completions.create(
    model=os.environ.get("XIMA_CLAUDE_MODEL", "xima/claude-sonnet-4-6"),
    messages=[
        {"role": "user", "content": "请用中文总结三条接入注意事项。"}
    ],
    max_tokens=512,
)

print(response.choices[0].message.content)
print(response.usage)

Node.js OpenAI SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XIMA_API_KEY,
  baseURL: "https://console.xima.ai/v1"
});

const response = await client.chat.completions.create({
  model: process.env.XIMA_CLAUDE_MODEL || "xima/claude-sonnet-4-6",
  messages: [
    { role: "user", content: "请用中文总结三条接入注意事项。" }
  ],
  max_tokens: 512
});

console.log(response.choices[0].message.content);
console.log(response.usage);

如果使用 Anthropic SDK，请确保 SDK 支持把请求发送到自定义网关地址；不同 SDK 版本初始化参数可能不同。本文的 Anthropic native 示例以 HTTP 请求为准。

流式输出

长文本、聊天产品和 Agent 场景建议开启 stream。

OpenAI-compatible：

bash

curl -N "$XIMA_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$XIMA_CLAUDE_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "写一份 300 字以内的产品需求总结。"
      }
    ],
    "stream": true,
    "max_tokens": 800
  }'

Anthropic native：

bash

curl -N "$XIMA_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "'"$XIMA_CLAUDE_MODEL"'",
    "max_tokens": 800,
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "写一份 300 字以内的产品需求总结。"
      }
    ]
  }'

客户端需要按 Server-Sent Events 逐段读取返回内容。

工具调用与工具结果闭环

两种协议都支持工具定义、工具调用和工具结果回传，但字段名称不同。

能力	OpenAI-compatible	Anthropic native
工具定义	`tools[].function.parameters`	`tools[].input_schema`
模型请求工具	`choices[0].message.tool_calls`	`content[]` 中的 `type: "tool_use"`
工具结果	`role: "tool"` + `tool_call_id`	`role: "user"` 消息中放 `type: "tool_result"` + `tool_use_id`

OpenAI-compatible 工具调用示例：

bash

curl -sS "$XIMA_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$XIMA_CLAUDE_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "查询北京今天的天气，并给出穿衣建议。"
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "查询城市天气",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "description": "城市名称"
              }
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto",
    "max_tokens": 512
  }'

模型返回 tool_calls 后，业务系统执行工具，再把工具结果传回模型：

json

{
  "role": "tool",
  "tool_call_id": "call_weather_001",
  "content": "{\"city\":\"北京\",\"weather\":\"晴\",\"temperature_c\":26}"
}

Anthropic native 工具结果使用 Claude 原生内容块：

json

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_weather_001",
      "content": "{\"city\":\"北京\",\"weather\":\"晴\",\"temperature_c\":26}"
    }
  ]
}

tool_call_id 或 tool_use_id 必须与上一轮模型返回的 ID 完全一致。

图片输入

Claude 支持图片理解。OpenAI-compatible 和 Anthropic native 的图片内容块不同。

OpenAI-compatible HTTPS 图片：

bash

curl -sS "$XIMA_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$XIMA_CLAUDE_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "请描述这张图片中的主要内容。"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://httpbin.org/image/png"
            }
          }
        ]
      }
    ],
    "max_tokens": 512
  }'

OpenAI-compatible Base64 图片需要把图片放进 data URL：

json

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/png;base64,<BASE64_IMAGE>"
  }
}

Anthropic native Base64 图片：

bash

curl -sS "$XIMA_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "'"$XIMA_CLAUDE_MODEL"'",
    "max_tokens": 800,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "base64",
              "media_type": "image/png",
              "data": "<BASE64_IMAGE>"
            }
          },
          {
            "type": "text",
            "text": "请提取图片里的关键信息。"
          }
        ]
      }
    ]
  }'

不要把本地文件路径直接传给 API。请先上传为 HTTPS URL，或在业务侧读取文件后转成 Base64。

长上下文

长上下文本身不需要特殊字段；把稳定背景放在前面，把本轮问题放在后面即可。

OpenAI-compatible：

json

{
  "model": "xima/claude-sonnet-4-6",
  "messages": [
    {
      "role": "system",
      "content": "你是严谨的文档分析助手。只能根据用户提供的长文档回答。"
    },
    {
      "role": "user",
      "content": "长文档如下：\n<LONG_DOCUMENT_TEXT>\n\n请提取关键结论、风险点和待确认事项。"
    }
  ],
  "max_tokens": 1200
}

Anthropic native：

json

{
  "model": "xima/claude-sonnet-4-6",
  "max_tokens": 1200,
  "system": "你是严谨的文档分析助手。只能根据用户提供的长文档回答。",
  "messages": [
    {
      "role": "user",
      "content": "长文档如下：\n<LONG_DOCUMENT_TEXT>\n\n请提取关键结论、风险点和待确认事项。"
    }
  ]
}

长上下文会增加输入 tokens、响应时间和费用。生产接入前建议用真实业务文档做小样本验收。

Claude thinking

普通聊天、摘要、问答和工具调用通常不需要显式配置 thinking。如果需要 Claude 原生高级推理能力，或需要观察 thinking、signature 等原生证据，建议使用 /v1/messages。

OpenAI-compatible 可以用 reasoning_effort 做轻量适配，但它不等同于 Claude 原生 thinking：

bash

curl -sS "$XIMA_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$XIMA_CLAUDE_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "请给出一个数据库慢查询排查计划，并说明每一步判断依据。"
      }
    ],
    "reasoning_effort": "low",
    "max_tokens": 1800
  }'

Anthropic native 固定预算 thinking：

bash

curl -sS "$XIMA_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "xima/claude-sonnet-4-6",
    "max_tokens": 1600,
    "temperature": 1,
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    },
    "messages": [
      {
        "role": "user",
        "content": "请完成一个需要多步推理的排查计划。"
      }
    ]
  }'

thinking 会占用输出 token，通常会增加成本和响应时间。不同模型支持的 thinking 形态可能不同，建议用小样本验证后再上线。

Prompt cache

Prompt cache 适合长系统提示词、长文档前缀、固定工具说明等重复输入。需要 Claude prompt cache 时，建议使用 Anthropic native /v1/messages。

bash

curl -sS "$XIMA_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "xima/claude-sonnet-4-6",
    "max_tokens": 256,
    "system": [
      {
        "type": "text",
        "text": "这里放很长且多次请求保持不变的系统提示词、业务规则或文档前缀。",
        "cache_control": {
          "type": "ephemeral"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "请基于上面的规则，回答本轮用户问题。"
      }
    ]
  }'

缓存验收建议关注：

第一次请求通常看到 cache creation，后续相同前缀请求命中时才会看到 cache read。
对账时关注 usage.cache_creation_input_tokens 和 usage.cache_read_input_tokens。
缓存是否命中还取决于上游账号、组织、渠道路由和前缀是否完全稳定。

计费与用量查看

价格以模型与价格和 Xima AI 控制台「模型与定价」页面为准。
调用后可在控制台日志或用量页面查看请求记录。
对账时建议关注：model、endpoint、输入 tokens、输出 tokens、缓存写入 tokens、缓存读取 tokens、扣费金额、请求时间。
OpenAI-compatible 返回中通常查看 usage.prompt_tokens、usage.completion_tokens、usage.total_tokens。
Claude 原生返回中通常查看 usage.input_tokens、usage.output_tokens、usage.cache_creation_input_tokens、usage.cache_read_input_tokens。

常见错误

HTTP 状态	常见原因	处理方式
`401`	API Key 缺失、格式错误或已失效	检查 `Authorization: Bearer <XIMA_API_KEY>`
`403`	Key 无权限、余额不足或模型未授权	检查令牌权限、余额和模型授权范围
`404` / `503`	模型名不存在、未开通或当前没有可用渠道	确认模型名完全匹配，例如 `xima/claude-sonnet-4-6`
`429`	请求频率或并发超过限制	降低并发，按指数退避重试
`5xx`	上游或网关短时异常	记录请求时间和模型名，重试后仍失败再联系支持

生产接入建议

API Key 只放在服务端，不要暴露到浏览器、移动端或公开仓库。
每次请求设置合理的 max_tokens，避免输出过长造成不可控成本。
长输出场景优先使用 stream: true。
客户端设置超时和重试，只对网络错误、429 和 5xx 做有限次数重试。
初次上线建议灰度放量，先观察成功率、响应时间、token 使用量和扣费记录。
工具调用、多模态输入、长上下文、thinking 和 prompt cache 建议分别做小样本验收。

Claude 高级能力接入说明 ​

接入信息 ​

模型选择 ​

入口选择 ​

文本调用 ​

OpenAI-compatible ​

Anthropic native ​

SDK 示例 ​

Python OpenAI SDK ​

Node.js OpenAI SDK ​

流式输出 ​

工具调用与工具结果闭环 ​

图片输入 ​

长上下文 ​

Claude thinking ​

Prompt cache ​

计费与用量查看 ​

常见错误 ​

生产接入建议 ​

Claude 高级能力接入说明

接入信息

模型选择

入口选择

文本调用

OpenAI-compatible

Anthropic native

SDK 示例

Python OpenAI SDK

Node.js OpenAI SDK

流式输出

工具调用与工具结果闭环

图片输入

长上下文

Claude thinking

Prompt cache

计费与用量查看

常见错误

生产接入建议