Claude · Anthropic

Claude API 接入教程：用 Tikway 调用 Anthropic Messages 协议

更新日期： 2026-10-13

接入 Claude 时，先让一个最小文本请求返回可读取的回答，再逐步增加系统提示和对话历史。本文演示 curl 请求、保存响应、过滤文本块，并识别输出截断和工具调用，适合为已有后端接入 Anthropic Messages 协议。

本例完整请求地址为 https://api.tikway.ai/v1/messages，使用 Tikway API Key 和 x-api-key 请求头。接口使用 Messages 的结构，产品按使用量计费；执行前应在模型目录确认目标模型的协议、参数和当前价格。

1. 配置环境，确认模型标识

下例采用协议文档中的 claude-sonnet-4-6。它是文档示例标识，实时可用性以目录为准；若目录指定完整 ID 或别名，原样复制，不自行增加或删除前缀。

curl 命令适用于 Bash，例如 macOS、Linux 或 WSL。需要 curl 7.76 或更新版本，响应读取脚本需要 Python 3.10 或更新版本；不安装第三方 Python 包。先在同一个终端设置 Key：

export TIKWAY_API_KEY='替换为你的 Tikway API Key'

2. 保存请求，发送并保留响应

将以下内容保存为 03-claude-request.json，也可下载配套请求 JSON：

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "请用三句话解释 API 网关在应用中的作用。"
    }
  ]
}

然后在该文件所在目录执行。这个命令会发起真实模型请求，并将普通 JSON 响应与响应头分别保存到本地；费用以账户和当前模型价格为准。

: "${TIKWAY_API_KEY:?请先设置 Tikway API Key 环境变量}"

curl --fail-with-body --silent --show-error \
  --connect-timeout 10 --max-time 60 \
  --request POST 'https://api.tikway.ai/v1/messages' \
  --header 'Content-Type: application/json' \
  --header "x-api-key: ${TIKWAY_API_KEY}" \
  --header 'anthropic-version: 2023-06-01' \
  --data-binary '@03-claude-request.json' \
  --dump-header 'claude-response.headers' \
  --output 'claude-response.json'

anthropic-version 表示协议版本，model 才选择模型。--data-binary @文件 可以保留 UTF-8 JSON，不必把长消息写成复杂的 shell 引号。--fail-with-body 使 HTTP 错误返回非零退出码，同时保留错误响应文件；先检查 curl 是否成功，再读取回答。网络失败时文件可能为空或不完整，应结合退出码判断。

响应头文件可保留 x-request-id，供排查使用。不要使用会展示完整请求头的调试输出分享 Key，也不要把包含实际对话的响应文件提交到公共仓库。

3. 从 content 数组提取文字

下面是一份人工构造的普通响应片段，用来说明多个内容块的结构，不是实际调用结果：

{
  "content": [
    {"type": "text", "text": "第一段。"},
    {"type": "text", "text": "第二段。"}
  ],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 100, "output_tokens": 40}
}

content 是数组，应读取其中 type == "text" 的块。工具调用、思考等其他块有不同字段，不能把整个数组直接转换成一句回答。

保存以下代码为 03-read-claude-response.py，或使用配套读取脚本。它只读取本地文件，不发送请求：

"""Read a saved Anthropic Messages JSON response locally; no API calls."""

import json
from pathlib import Path
import sys


def extract_text(response):
    if not isinstance(response, dict):
        raise ValueError("响应必须是 JSON 对象。")
    if response.get("error"):
        raise ValueError("响应含有 error，请结合 HTTP 状态和响应头排查。")
    blocks = response.get("content")
    if not isinstance(blocks, list):
        raise ValueError("响应没有 content 数组。")
    text = "".join(
        block["text"] for block in blocks
        if isinstance(block, dict) and block.get("type") == "text"
        and isinstance(block.get("text"), str)
    )
    if not text:
        raise ValueError(f"没有文本块；stop_reason={response.get('stop_reason', 'unknown')}")
    return text


def main():
    path = Path(sys.argv[1] if len(sys.argv) > 1 else "claude-response.json")
    response = json.loads(path.read_text(encoding="utf-8"))
    print(extract_text(response))
    reason = response.get("stop_reason")
    if reason == "max_tokens":
        print("注意：达到输出上限，回答可能被截断。", file=sys.stderr)
    elif reason == "tool_use":
        print("注意：模型请求工具调用，仍需应用处理 tool_use 块。", file=sys.stderr)


if __name__ == "__main__":
    try:
        main()
    except (OSError, ValueError, UnicodeError) as exc:
        print(f"读取失败：{exc}", file=sys.stderr)
        sys.exit(1)

读取刚保存的响应：

python 03-read-claude-response.py claude-response.json

脚本打印普通文本，并在 stop_reason == "max_tokens" 时提示可能截断；tool_use 表示仍需应用处理工具调用。没有文本块时，它会说明原因，而不会伪造空白成功回答。

4. 系统提示与多轮消息放在哪里

系统指令放在根节点 system，不要在 Messages 数组中添加 role: "system"。下面只展示需要修改的字段，助手文字为人工示例：

{
  "system": "回答要简洁，先解释概念再举例。",
  "messages": [
    {"role": "user", "content": "什么是 API？"},
    {"role": "assistant", "content": "API 是程序之间交换数据或调用功能的接口。"},
    {"role": "user", "content": "用天气查询说明。"}
  ]
}

使用时将这两个字段合入第 2 节的完整请求，并保留模型和 max_tokens。后续请求应包含所需对话历史，不能假定服务端记住上一次请求。

字段或请求头	调整依据
`max_tokens`	本例为 1024，限制输出；具体范围按型号确认。触及上限时检查 `stop_reason`。
`system`	根节点字符串或协议支持的内容块结构；本篇只演示字符串。
`temperature` / `top_p`	先核对所选型号支持情况及能否组合，再逐项添加。
`stream`	仅对支持该能力的型号设为 `true`；响应改为 SSE，普通文件读取脚本不适用。

常见错误怎么排查

现象	优先检查
鉴权失败	当前终端有 Key，且发送的是 Tikway Key 与 `x-api-key`。
模型不存在或接口不支持	从目录复制有效 ID，并确认 Anthropic 协议支持。
路径错误	完整路径为 `/v1/messages`，避免重复拼接 `/v1`。
消息结构被拒	`messages` 是非空数组；角色使用 `user` / `assistant`，系统指令在根节点。
返回 429	联合查看错误内容，区分余额不足与限流。
没有文本块	查看 `stop_reason`、错误内容及 `tool_use` 等非文本块。
JSON 文件无法读取	先检查 curl 退出码；确认没有切换成流式响应或保存到其他目录。

生产应用可以记录模型标识、响应状态、用量与请求 ID，减少排查时反复调用。运营方声明按请求型号提供调用；返回的 model 字段或模型自报身份不能单独构成独立真实性证明。

继续阅读：模型与价格 · Anthropic 协议 · 网关鉴权 · 错误码说明