# Claude 系列 API：模型 ID、接口选择、调用示例与常见报错

Source: https://ofox.io/zh/docs/develop/models/claude

Anthropic 的 Claude 模型，包括 Opus、Sonnet、Haiku 与 Fable 系列。推荐通过 **Anthropic 原生接口**调用，扩展思考、提示缓存、PDF 输入等能力与官方 API 一致；OpenAI 兼容接口同样可用，适合已有 OpenAI SDK 代码的项目。

## 常见任务

- [开启扩展思考](https://ofox.io/zh/docs/develop/models/claude/thinking) — thinking、budget_tokens、adaptive，以及如何读取思考内容。
- [提示缓存](https://ofox.io/zh/docs/develop/models/claude/caching) — cache_control、1 小时缓存、如何确认命中。
- [联网搜索](https://ofox.io/zh/docs/develop/models/claude/web-search) — web_search 工具，需指定 Anthropic 供应商。
- [长上下文与 PDF](https://ofox.io/zh/docs/develop/models/claude/pdf) — 1M 上下文、上传 PDF 文档。
- [报错排查](#errors) — prompt is too long、模型不存在、回答被截断。
- [在 Claude Code 中使用](https://ofox.io/zh/docs/integrations/claude-code) — 接入配置与常见问题。

## 模型
全部模型支持文本、图片与 PDF 输入，支持工具调用。完整的模型列表与实时价格请参阅[模型页](https://ofox.io/zh/models?provider=anthropic)，也可通过 [Models API](https://ofox.io/zh/docs/api/openai/models) 查询。

**常用模型 ID（调用时原样复制）**

- Claude Opus 5.5: `anthropic/claude-opus-5.5`
- Claude Sonnet 5.5: `anthropic/claude-sonnet-5.5`
- Claude Haiku 5.5: `anthropic/claude-haiku-5.5`
- Claude Fable 5.1: `anthropic/claude-fable-5.1`

模型 ID 可省略 `anthropic/` 前缀，也可使用 Anthropic 官方的写法，以下写法均指向同一模型：

| 写法 | 示例 |
|---|---|
| OfoxAI 标准写法 | `anthropic/claude-sonnet-4.6` |
| 省略前缀 | `claude-sonnet-4.6` |
| 官方写法（短横线） | `claude-sonnet-4-6` |
| 官方带日期写法 | `claude-sonnet-4-6-20260217` |

各模型可用的别名见 Models API 返回的 `aliases` 字段。响应中的 `model` 字段统一为标准写法。

## 接口选择

**要点**:使用扩展思考、提示缓存或 Claude Code 等工具时，请使用 Anthropic 原生接口。

| | Anthropic 原生接口（推荐） | OpenAI 兼容接口 |
|---|---|---|
| 地址 | `POST https://api.ofox.io/anthropic/v1/messages` | `POST https://api.ofox.io/v1/chat/completions` |
| SDK `base_url` | `https://api.ofox.io/anthropic` | `https://api.ofox.io/v1` |
| 认证 | `x-api-key: <Key>`，也接受 `Authorization: Bearer <Key>` | `Authorization: Bearer <Key>` |
| [扩展思考](https://ofox.io/zh/docs/develop/models/claude/thinking) | `thinking` 参数，返回 `thinking` 块 | `reasoning` 参数，返回 `reasoning_details` |
| [提示缓存](https://ofox.io/zh/docs/develop/models/claude/caching) | `cache_control`，usage 返回写入与读取量 | 在消息内容块中加 `cache_control`，usage 只返回读取量 |
| [PDF](https://ofox.io/zh/docs/develop/models/claude/pdf) | `document` 内容块 | `file` 内容块 |
| [联网搜索](https://ofox.io/zh/docs/develop/models/claude/web-search) | 支持（需指定 Anthropic 供应商） | 不支持 |

完整的请求参数见 [Anthropic Messages API](https://ofox.io/zh/docs/api/anthropic/messages) 与 [Chat Completions API](https://ofox.io/zh/docs/api/openai/chat-completions)。

### 供应商
Claude 模型由两个供应商提供，同一模型在不同供应商上支持的功能不同：

| 供应商 | 提供的模型 | 可用接口 | 说明 |
|---|---|---|---|
| Amazon Bedrock（`aws_bedrock`） | 全部模型 | 两种接口 | 默认供应商 |
| Anthropic（`anthropic`） | Fable 5、Opus 4.8、Opus 4.7、Sonnet 5 | 仅 Anthropic 原生接口 | 支持[联网搜索](https://ofox.io/zh/docs/develop/models/claude/web-search)，需显式指定 |

在 Anthropic 原生接口中，可通过请求头指定供应商：

```bash
-H "X-OfoxAI-Provider-Type: anthropic"
```

指定的供应商不提供该模型时返回 400，报错信息会列出可用的供应商，例如：

```text
No available channel for platform 'anthropic' on model 'anthropic/claude-sonnet-4.6'. Available platforms for this model: aws_bedrock.
```

其他指定方式见[供应商路由](https://ofox.io/zh/docs/develop/advanced/provider-routing)。

## 调用示例

**Python（Anthropic SDK）**

```python filename="claude_basic.py"
import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.ofox.io/anthropic",
    api_key=os.environ["OFOX_API_KEY"],
)

message = client.messages.create(
    model="anthropic/claude-sonnet-4.6",
    max_tokens=1024,
    system="你是一名资深后端工程师，回答简洁。",
    messages=[{"role": "user", "content": "用一句话解释什么是幂等性。"}],
)
print(message.content[0].text)
```

**cURL**

```bash filename="Terminal"
curl https://api.ofox.io/anthropic/v1/messages \
  -H "x-api-key: $OFOX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "用一句话解释什么是幂等性。"}]
  }'
```

**Python（OpenAI SDK）**

```python filename="claude_openai_sdk.py"
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.ofox.io/v1", api_key=os.environ["OFOX_API_KEY"])

resp = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "用一句话解释什么是幂等性。"}],
)
print(resp.choices[0].message.content)
```

`max_tokens` 为 Anthropic 原生接口的必填参数，取值不得超过模型的最大输出。

## 在 Claude Code 中使用
Claude Code 通过 Anthropic 原生接口调用，基础地址为 `https://api.ofox.io/anthropic`。配置步骤见 [Claude Code 配置](https://ofox.io/zh/docs/integrations/claude-code)。

**Claude Code 配置值**

- ANTHROPIC_BASE_URL: `https://api.ofox.io/anthropic`
- ANTHROPIC_AUTH_TOKEN: 粘贴你的 OfoxAI API Key

## 常见报错

**要点**:参数类错误返回 400 并说明原因；回答被截断不是报错，请检查 stop_reason。

| HTTP · type | 报错原文 | 原因 | 处理方法 |
|---|---|---|---|
| 400 `ValidationException` | `prompt is too long: 280527 tokens > 200000 maximum` | 输入超过模型上下文 | 缩短输入，或改用 1M 上下文的模型（Haiku 4.5 以外的模型） |
| 404 `model_not_found` | `Model 'anthropic/claude-sonnet-9' not found` | 模型 ID 拼写错误或模型已下线 | 从本页复制模型 ID |
| 401 `invalid_api_key` | `Invalid or expired API key` | Key 错误、已删除或已过期 | 在控制台确认 Key；原生接口检查 `x-api-key` 请求头 |
| 400 | `No available channel for platform 'anthropic' on model ...` | 指定的供应商不提供该模型 | 删除供应商指定，或改为报错信息中列出的供应商，见[供应商](#provider) |
| 200，`stop_reason: "max_tokens"` | — | 输出达到 `max_tokens` 上限，回答被截断 | 增大 `max_tokens`；开启思考时，思考也占用该额度 |

其他通用错误见[错误处理](https://ofox.io/zh/docs/develop/guides/error-handling)。

## 官方文档
- [Anthropic · 模型概览](https://docs.anthropic.com/en/docs/about-claude/models/overview)
- [Anthropic · 扩展思考](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking)
- [Anthropic · 提示缓存](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching)
- [Anthropic · PDF 支持](https://docs.anthropic.com/en/docs/build-with-claude/pdf-support)

官方文档描述的是直连 Anthropic 时的行为。在 OfoxAI 上调用时，模型 ID 与接口地址以本页为准。

## 常见问题

**Claude 的模型 ID 怎么写？**

标准写法为 anthropic/claude-sonnet-4.6，也可以省略 anthropic/ 前缀，或使用官方的 claude-sonnet-4-6、claude-sonnet-4-6-20260217 写法，均指向同一模型。

**可以用 OpenAI SDK 调用 Claude 吗？**

可以。base_url 设为 https://api.ofox.io/v1，模型 ID 填 anthropic/claude-sonnet-4.6 等。需要扩展思考或完整的缓存用量信息时，推荐使用 Anthropic 原生接口。

**Claude 怎么开启思考模式？**

原生接口传 thinking: {"type": "enabled", "budget_tokens": 2000}，budget_tokens 至少 1024 且小于 max_tokens；或传 {"type": "adaptive"} 由模型决定。OpenAI 兼容接口传 reasoning: {"max_tokens": 2000}。开启思考时不要设置 temperature。

**Claude 提示缓存没有生效怎么办？**

依次检查：是否在固定内容块上标记了 cache_control（两种接口都不会自动缓存）；内容是否达到最小可缓存长度；两次请求的前缀是否完全一致；两次请求是否间隔超过 5 分钟。

**报错 prompt is too long 怎么办？**

输入超过了模型上下文。Haiku 4.5 的上下文为 200K token，其余 Claude 模型为 1M token，可改用其他模型或缩短输入。

**Claude 支持 1M 上下文吗？需要加 beta 请求头吗？**

除 Haiku 4.5 外均支持 1M 上下文，在 OfoxAI 上无需传入 beta 请求头。

**Claude 的回答被截断了怎么办？**

查看响应的 stop_reason，若为 max_tokens，说明输出达到上限，请增大 max_tokens。开启思考时，思考内容也占用 max_tokens 的额度。

**OfoxAI 的 Claude 由哪个供应商提供？**

全部模型由 Amazon Bedrock 提供，为默认供应商；Fable 5、Opus 4.8、Opus 4.7、Sonnet 5 另有 Anthropic 供应商，仅限 Anthropic 原生接口，需通过 X-OfoxAI-Provider-Type: anthropic 请求头指定。

**Claude 能联网搜索吗？**

可以，但需指定 Anthropic 供应商，仅限 Fable 5、Opus 4.8、Opus 4.7、Sonnet 5，且仅支持 Anthropic 原生接口。在 tools 中加入 {"type": "web_search_20250305", "name": "web_search"}。

**Claude 能读取 PDF 吗？**

能。原生接口使用 document 内容块传入 base64 编码的 PDF；OpenAI 兼容接口使用 file 内容块，file_data 为 data:application/pdf;base64,... 格式。