跳转到主要内容

​
Anthropic 原生格式调用 & effort 参数用法

本文档说明如何用 Anthropic 原生 Messages API 调用 Claude(经 API易网关转 AWS Bedrock), 以及 output_config.effort(努力档位)和 thinking(自适应思考)的正确用法。
适用模型:Claude Opus 4.8 / 4.7 / 4.6、Sonnet 4.6 等。本文以 Opus 4.8 为例。

​
1. 请求的基本结构

​
Endpoint 与请求头

POST {BASE_URL}/v1/messages
Header值说明
content-typeapplication/json固定
anthropic-version2023-06-01Anthropic 原生版本头,必填
x-api-key$APIYI_API_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": "你的问题" }
  ]
}

​
2. 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 起步),给模型留足思考+输出空间。

​
3. 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" —— 让响应里返回思考摘要块;不需要展示可删掉。
  • ⚠️ Opus 4.7/4.8 不支持 thinking.type: "enabled" + budget_tokens(会 400)。请改用 adaptive + effort。
  • effort 与思考的关系:high/xhigh/max 几乎总会深度思考;low/medium 在简单题上可能跳过思考。

​
4. 解析响应

响应的 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 调大即可。

​
5. 完整可运行示例(Python)

import os
import json
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: $APIYI_API_KEY" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 16000,
    "thinking": { "type": "adaptive" },
    "output_config": { "effort": "xhigh" },
    "messages": [{ "role": "user", "content": "分析微服务与单体架构的取舍" }]
  }'

​
6. 经 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 是否拉开差距。

​
7. 参考