如何调用 Claude Opus 5 API：从首个请求到生产部署

Claude Opus 5 API 快速了解

最重要的判断原则是：Claude Opus 5 现在已经可以通过 EvoLink 调用；具体参数兼容性、计费和运行表现，仍应以 EvoLink 当前契约和真实账户请求为准。

为什么通过统一 API 使用 Claude Opus 5

调用一个新模型并不难。难的是发布热度过去之后，应用仍能灵活选择模型，而不是被一次接入绑定。

如果团队只使用 Claude，并且必须立即获得每一个 Anthropic 原生功能，直接接入 Anthropic 可能更合适。如果应用需要在多个模型之间选择、控制成本、保留 fallback，或者避免在产品代码中散落不同供应商的接入逻辑，统一 API 网关的价值会更明显。

因此，EvoLink 的价值不是让每个请求都使用 Opus 5，而是把模型选择留在路由层：

应用任务
  -> 路由策略
  -> 选定模型
  -> Messages API 请求
  -> 核验实际模型与用量
  -> 记录质量与成本
  -> 提升、重试、回退或回滚

这套架构能带来四项具体价值：

1. 统一接入面。 应用通过同一个有文档记录的 endpoint 发送 Claude Messages 风格请求。
2. 模型选择可配置。 业务逻辑只描述 routine_coding 或 architecture_escalation 之类的任务，配置层决定当前使用哪个模型。
3. Fallback 可测量。 重试或切换模型会成为明确的运行事件，不会悄悄污染 benchmark。
4. 迁移更灵活。 下一次模型升级主要是路由与评测决策，不需要同时重写 prompt、业务代码和用户设置。

第一次调用 Claude Opus 5 API

1. 修改生产代码前，先确认账户权限

EvoLink 路由已经可用。修改生产流量前，应确认自己的账户可以调用，并且完整应用链路符合预期：

• EvoLink 账户中已经列出 claude-opus-5。
• 最小请求返回 HTTP 200。
• response.model 指向预期模型。
• usage 记录和扣费金额符合 EvoLink 当前价格入口的说明。
• streaming、tool use 等必要功能在同一路由上可以正常运行。

如果账户没有显示该路由，或者必要功能测试失败，应保留现有模型作为 fallback，先解决账户权限或兼容性问题，再开始放量。

2. 只在服务端保存 API key

创建 EvoLink API key，并通过服务端环境变量加载：

export EVOLINK_API_KEY="your_api_key_here"

3. 发送最小请求

可以按照 EvoLink Claude Messages API 的结构发送最小请求：

curl --request POST \
  --url https://direct.evolink.ai/v1/messages \
  --header "Authorization: Bearer $EVOLINK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "claude-opus-5",
    "max_tokens": 4096,
    "messages": [
      {
        "role": "user",
        "content": "Review this service architecture and identify the three highest-risk failure points."
      }
    ]
  }'

第一次请求先不要加入可选参数。小请求更容易单独验证鉴权、路由可用性和基础请求结构，避免 effort、tools、streaming 或缓存引入额外故障点。

4. 不要只看 HTTP 状态码，还要核验实际响应

HTTP 请求成功只能证明 endpoint 返回了结果，不能证明目标模型确实处理了请求，也不能证明这条数据可以纳入 Opus 5 评测。

至少应该记录：

• response.model
• response.stop_reason
• 输入和输出用量
• 请求延迟
• 可用时记录 request ID
• 应用内部的 task ID
• 重试和 fallback 次数

type Usage = {
  input_tokens: number
  output_tokens: number
  cache_creation_input_tokens?: number
  cache_read_input_tokens?: number
}

type TextBlock = {
  type: 'text'
  text: string
}

type MessageResponse = {
  id: string
  model: string
  stop_reason: string | null
  content: TextBlock[]
  usage: Usage
}

const RETRYABLE_STATUS = new Set([429, 500, 503, 524])

function isMessageResponse(value: unknown): value is MessageResponse {
  if (typeof value !== 'object' || value === null) return false

  const record = value as Record<string, unknown>
  return (
    typeof record.id === 'string' &&
    typeof record.model === 'string' &&
    Array.isArray(record.content) &&
    typeof record.usage === 'object' &&
    record.usage !== null
  )
}

async function callClaudeOpus5(prompt: string): Promise<MessageResponse> {
  const credential = process.env.EVOLINK_API_KEY
  if (!credential) throw new Error('EVOLINK_API_KEY is not configured')

  for (let attempt = 0; attempt < 3; attempt += 1) {
    const response = await fetch('https://direct.evolink.ai/v1/messages', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${credential}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'claude-opus-5',
        max_tokens: 4096,
        messages: [{ role: 'user', content: prompt }],
      }),
      signal: AbortSignal.timeout(120_000),
    })

    if (response.ok) {
      const payload: unknown = await response.json()
      if (!isMessageResponse(payload)) {
        throw new Error('Unexpected Claude Messages API response')
      }

      if (payload.model !== 'claude-opus-5') {
        throw new Error(`Unexpected response model: ${payload.model}`)
      }

      return payload
    }

    if (!RETRYABLE_STATUS.has(response.status) || attempt === 2) {
      throw new Error(`Claude request failed with HTTP ${response.status}`)
    }

    const backoffMs = 1_000 * 2 ** attempt + Math.floor(Math.random() * 250)
    await new Promise((resolve) => setTimeout(resolve, backoffMs))
  }

  throw new Error('Claude request exhausted its retry policy')
}

这只是参考实现，不能替代账户级真实测试。对于高并发服务，还应该增加结构化日志、request correlation、并发控制，以及由路由策略决定的 fallback。

Thinking、effort 和 max_tokens 如何联动

Opus 5 会改变看似熟悉的请求行为：thinking 默认开启，effort 决定模型可以投入多少计算资源。

这里有三个容易踩坑的细节：

1. max_tokens 同时覆盖 thinking 和可见输出。 如果直接沿用 Opus 4.8 关闭 thinking 时的上限，Opus 5 任务可能更早被截断。
2. Effort 不能可靠控制可见答案长度。 如果需要简短回答或固定篇幅，应该直接在 prompt 中说明。
3. 不同 API 提供方支持范围可能不同。 只有 EvoLink 当前路由文档或真实测试确认接受该字段后，才能发送 output_config.effort。

条件允许时应保持 thinking 开启。Anthropic 提醒，关闭 thinking 偶尔会使工具调用以普通文本出现，或者在可见回答中暴露类似内部 XML 的标签。

从 Claude Opus 4.8 迁移：不要把旧行为一起复制过去

更换 model ID 是最简单的一步：

- "model": "claude-opus-4-8"
+ "model": "claude-opus-5"

请求层迁移

• 不传 thinking 字段的请求，现在会默认开启 thinking。
• 原来未使用 thinking 的工作流需要重新评估 max_tokens。
• 不要同时使用“关闭 thinking”和 xhigh 或 max。
• 确认没有从 4.8 之前的配置遗留 temperature、top_p、top_k——Opus 4.8 起这些参数已被拒绝，Opus 5 行为不变。
• 如果重复 prompt 以前短到无法缓存，需要测试新的 512-token prompt cache 最低长度。
• 将 stop_reason: "refusal" 作为一种应用结果处理。

Prompt 迁移

Opus 5 更可能主动验证工作、汇报进度并委派 subagent。为旧模型设计的 prompt 可能会无意中放大这些行为。

建议从四个方面调整 prompt：

• 明确目标答案或文档长度。
• 删除无条件要求模型重复检查或额外增加 verifier 的指令。
• 对窄任务设定清晰范围。
• 除非任务确实需要独立并行工作，否则限制 subagent 委派数量。

Agent harness 迁移

不要只测试裸模型调用，要让代表性任务经过完整应用链路。至少核验：

• 工具选择和参数
• streaming parser 行为
• timeout 和 retry 上限
• refusal 处理
• 实际返回模型
• token 和缓存用量
• 输出长度
• 真实审核者或下游检查是否接受结果

应该按工作负载逐步放量。Opus 5 可能显著改善复杂架构任务，却给常规抽取任务增加没有必要的成本。

处理工具调用、流式输出、拒绝和传输故障

EvoLink Messages API 暴露 streaming、tools、tool choice、usage 和 stop reason。生产循环应根据响应分支处理，不能假设每个 HTTP 200 都包含最终答案。

发送消息
  -> end_turn：返回答案
  -> tool_use：执行获准工具并继续
  -> refusal：执行拒绝与 fallback 策略
  -> max_tokens：将结果标记为不完整
  -> 传输错误：仅在错误可重试时重试

必须限制最大工具循环次数，校验每个工具参数，并保留足以解释失败任务的 trace。未经应用层授权和 schema 校验，绝不能直接执行模型生成的工具调用。

按类型处理故障：

Refusal 不是 HTTP 请求失败。Anthropic 将它定义为 Opus 5 的一种正常响应结果。Anthropic 原生 API 可能提供自动 fallback，但在网关请求中加入供应商特有字段前，必须先确认 EvoLink 是否有等价支持。

不要只看 token 单价，要计算“成功任务成本”

Claude Opus 5 的官方基础 token 单价与 Opus 4.8 相同，但生产团队不能仅凭标价判断哪条路由更省钱。

应该使用下面的决策指标：

成功任务成本 =
  输入 token 成本
  + 输出 token 成本
  + 重试成本
  + fallback 成本
  + 工具执行成本
  + 人工审核或修复成本

评测表至少应该包含：

不要根据一次 prompt 就给出所有任务通用的 effort 建议。每类工作负载都应该选择能达到质量门槛的最低档位，只在失败代价较高的任务上提升模型或 effort。

按工作负载路由 Sonnet、Opus 和 Fable

把模型路由保存在配置层：

type Workload =
  | 'routine_text'
  | 'everyday_coding'
  | 'complex_agent'
  | 'frontier_escalation'

const modelByWorkload: Record<Workload, string> = {
  routine_text: 'configured-low-cost-model',
  everyday_coding: 'claude-sonnet-5',
  complex_agent: 'claude-opus-5',
  frontier_escalation: 'claude-fable-5',
}

应用应该同时记录 requested model 和 returned model。如果发生 fallback，应将该 trace 从纯 Opus 5 benchmark 中排除，或者单独标记。

Claude Opus 5 上生产前检查清单

在把真实流量切换到 Opus 5 之前，逐项确认：

• EvoLink 账户已经列出 claude-opus-5。
• 最小请求返回预期的 response.model。
• Usage 和 billing 与当前路由文档一致。
• 如果产品依赖 streaming，已经完成真实流式测试。
• 每个必要工具路径都有完整请求和结果 trace。
• 应用能够区分 refusal 与 HTTP failure。
• 可重试和不可重试错误使用不同策略。
• 已经准备并实际运行过 fallback 路由。
• 使用代表性任务测试过多个 effort 档位。
• 放量门槛同时考虑任务验收率、延迟和成功任务成本。
• Model ID 保存在配置层，而不是业务逻辑中。
• 回滚条件明确。

常见问题

Claude Opus 5 API 的 model ID 是什么？

EvoLink 已经可以调用 Claude Opus 5 吗？

应该使用哪个 EvoLink endpoint？

Claude Opus 5 默认开启 thinking 吗？

Effort 应该选择哪个等级？

如何从 Claude Opus 4.8 迁移到 Opus 5？

Claude Opus 5 API 多少钱？

资料来源

• Anthropic：Introducing Claude Opus 5
• Anthropic：What's new in Claude Opus 5
• Anthropic：Prompting Claude Opus 5
• Anthropic：Migration guide
• Anthropic：Effort
• Anthropic：Refusals and fallback
• EvoLink：Claude Messages API