跳转到主要内容
本文说明如何用 Anthropic 原生 Messages API 调用 Claude（经 API易 网关转 AWS Bedrock），以及 output_config.effort（努力档位）和 thinking（自适应思考）的正确用法。 基础的通道、计费与接入信息请先看 Claude API 基础说明。
适用模型：Claude Opus 4.8 / 4.7 / 4.6、Sonnet 4.6 等。本文以 Opus 4.8 为例。

​
请求的基本结构

​
Endpoint 与请求头

POST https://api.apiyi.com/v1/messages
Header值说明
content-typeapplication/json固定
anthropic-version2023-06-01Anthropic 原生版本头，必填
x-api-keyyour-apiyi-keyAnthropic 原生鉴权方式
经 API易 转 Bedrock 时，客户端仍用 Anthropic 原生格式（x-api-key + /v1/messages），网关内部负责翻译成 Bedrock 的 bedrock-2023-05-31。你不需要写 anthropic_version: bedrock-2023-05-31。

​
最小请求体

{
  "model": "claude-opus-4-8",
  "max_tokens": 16000,
  "messages": [
    { "role": "user", "content": "你的问题" }
  ]
}

​
effort 努力档位

effort 控制 Claude 愿意花多少 token 来产出结果，在「彻底程度」和「速度/成本」之间权衡。它影响全部 token 消耗：正文、工具调用、以及扩展思考。
关键规则
  1. effort 必须放在顶层独立的 output_config 对象里，不能放进 thinking 里 —— 放错会直接 ValidationException / 400。
  2. 无需 beta 头。effort 现已对所有支持的模型开放，不再需要 anthropic-beta: effort-2025-11-24。
  3. 默认值是 high；设成 "high" 与完全不传 effort 行为一致。

​
带 effort 的请求体

{
  "model": "claude-opus-4-8",
  "max_tokens": 16000,
  "output_config": {
    "effort": "medium"
  },
  "messages": [
    { "role": "user", "content": "分析微服务与单体架构的取舍" }
  ]
}

​
档位一览

档位说明典型场景
low最省。显著节省 token，能力略降。简单任务、高并发、子 agent
medium平衡。中等 token 节省。多数 agentic 工作流的折中默认
high默认值。高能力。复杂推理、难编码、对质量敏感的任务
xhigh长程扩展能力，介于 high 和 max 之间。长时编码 / agentic 任务（超 30 分钟）
max无约束的最强能力。真正前沿的难题，最深推理
Opus 4.8 推荐：编码 / agentic 用 xhigh 起步，其它智力敏感任务用 high，只有在 eval 验证过质量不掉的前提下才下调到 medium / low。跑 xhigh / max 时把 max_tokens 设大（64k 起步），给模型留足思考 + 输出空间。

​
thinking 自适应思考

Opus 4.7 / 4.8 用自适应思考：由模型自己决定何时思考、思考多少，配合 effort 控制深度。 
{
  "model": "claude-opus-4-8",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive",
    "display": "summarized"
  },
  "output_config": {
    "effort": "xhigh"
  },
  "messages": [
    { "role": "user", "content": "一步步定位这个生产环境 Bug 的根因" }
  ]
}
  • thinking.type: "adaptive" —— 开启自适应思考（不传则不思考）。
  • thinking.display: "summarized" —— 让响应里返回思考摘要块；不需要展示可删掉。
  • effort 与思考的关系：high / xhigh / max 几乎总会深度思考；low / medium 在简单题上可能跳过思考。
Opus 4.7 / 4.8 不支持 thinking.type: "enabled" + budget_tokens（会 400）。请改用 adaptive + effort。

​
解析响应

响应的 content 是一个块数组，按 type 区分： 
for block in data["content"]:
    if block["type"] == "thinking":
        print("[思考摘要]", block["thinking"])
    elif block["type"] == "text":
        print("[回答]", block["text"])
token 用量在 usage 字段： 
{
  "usage": {
    "input_tokens": 164,
    "output_tokens": 11056,
    "service_tier": "standard"
  }
}
若 stop_reason 为 max_tokens，说明输出被 max_tokens 截断（高 effort 下思考容易吃满），此时正文可能为空 —— 把 max_tokens 调大即可。

​
完整可运行示例

import os
import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("APIYI_API_KEY")
BASE_URL = "https://api.apiyi.com"

resp = requests.post(
    f"{BASE_URL}/v1/messages",
    headers={
        "content-type": "application/json",
        "anthropic-version": "2023-06-01",
        "x-api-key": API_KEY,
    },
    json={
        "model": "claude-opus-4-8",
        "max_tokens": 16000,
        "thinking": {"type": "adaptive", "display": "summarized"},
        "output_config": {"effort": "xhigh"},
        "messages": [
            {"role": "user", "content": "分析微服务与单体架构的取舍"}
        ],
    },
    timeout=300,
)

data = resp.json()
print("status:", resp.status_code, "| usage:", data.get("usage"))
for block in data.get("content", []):
    if block.get("type") == "thinking":
        print("\n[思考摘要]\n", block.get("thinking", ""))
    elif block.get("type") == "text":
        print("\n[回答]\n", block.get("text", ""))

curl https://api.apiyi.com/v1/messages \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: your-apiyi-key" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 16000,
    "thinking": { "type": "adaptive" },
    "output_config": { "effort": "xhigh" },
    "messages": [{ "role": "user", "content": "分析微服务与单体架构的取舍" }]
  }'

​
经 Bedrock 时的注意事项

项说明
output_config必须放行。网关若有 delete output_config 覆盖规则，effort 会被静默吞掉（返回 200 但无效）。
effort 位置顶层 output_config 内，不能放进 thinking。
beta 头effort 不需要；adaptive thinking 也不需要。
temperature / top_pOpus 4.7 / 4.8 配自适应思考时应使用默认采样；网关通常会为这两个模型剥离这两个参数，属正常，客户端不必设置。
非法 effort 值Bedrock 对未知值宽容降级（返回 200），不报 400。所以不能用「invalid 是否报错」判断是否透传 —— 要看不同档位的 token 是否拉开差距。

​
参考

  • Anthropic — Effort 文档：platform.claude.com/docs/en/build-with-claude/effort
  • AWS Bedrock — Adaptive thinking：docs.aws.amazon.com/bedrock/latest/userguide/claude-messages-adaptive-thinking.html
  • AWS Bedrock — Claude Opus 4.8：docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-opus-4-8.html