# Claude Sonnet 5.5 API (https://wanapi.app/zh-tw/docs/claude-sonnet-5-5)





本文件介紹 **Claude Sonnet 5.5** 及其專屬的 Messages 參數。請在 `POST https://api.wanapi.app/v1/messages` 中使用 `claude-sonnet-5-5`。[比較 Claude 模型](/zh-tw/docs/claude-api)。

## 模型設定 [#模型設定]

| 設定                     | Claude Sonnet 5.5   |
| ---------------------- | ------------------- |
| 模型 ID                  | `claude-sonnet-5-5` |
| 上下文視窗                  | 1M Token            |
| 同步輸出上限                 | 128000 Token，包含思考用量 |
| 思考模式                   | 自適應或 between\_tools |
| 預設 effort              | `high`              |
| 強制工具呼叫（`any` / `tool`） | 不支援                 |

## 連線並傳送請求 [#連線並傳送請求]

在 [API 金鑰設定](/zh-tw/settings/apikeys)建立金鑰。一把 API 金鑰即可存取所有模型與分組。請將它保存在伺服器環境的 `WAN_API_KEY` 中。傳送 `anthropic-version: 2023-06-01`；只有功能需要時才加入 `anthropic-beta`。

```bash
curl https://api.wanapi.app/v1/messages \
  -H "x-api-key: $WAN_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Explain the purpose of a database index in three sentences."}]
  }'
```

```python
import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["WAN_API_KEY"],
    base_url="https://api.wanapi.app",
)
message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain the purpose of a database index in three sentences."}],
)
print("".join(block.text for block in message.content if block.type == "text"))
```

## 目前 API 支援範圍 [#目前-api-支援範圍]

下表說明此模型的原生介面規格。Wan API 目前透過相容層轉送請求。**請將 `max_tokens` 設為正整數**：網關目前會將 `0` 替換為生成額度，因此此處無法用它僅預熱快取而不生成內容。

目前網關不會轉送 `diagnostics`、`compaction`、`fallbacks`、`fallback_credit_token` 或 `thread`。目前的通道設定也會過濾 `speed`、`service_tier` 與 `inference_geo`。下方仍記載這些欄位，以說明模型的原生規格，但目前尚無法透過此連線使用。回應成功不代表被忽略的欄位已生效。需要這些欄位的 Beta 功能也有相同限制。

## 參數 [#參數]

| 參數                                | 型別／必填              | 官方限制與預設值                                                                                                                                             |
| --------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`                           | 字串，必填              | `claude-sonnet-5-5`。                                                                                                                                 |
| `max_tokens`                      | 整數，必填              | 0–128000，包含思考 Token。官方的 0 會填入提示快取而不生成輸出；請參閱「目前 API 支援範圍」。                                                                                            |
| `messages`                        | 物件陣列，必填            | 至少一則、最多 100000 則對話訊息。每則包含 `role` 與 `content`；content 可為字串或內容區塊陣列。一般對話使用 `user`/`assistant`。對話中途的 `system` 訊息須遵循官方放置規則。                               |
| `system`                          | 字串或文字區塊陣列          | 頂層指令。文字區塊可包含快取斷點。                                                                                                                                    |
| `thinking`                        | 物件                 | 預設為 `{"type":"adaptive"}`。另一種支援的模式是 `{"type":"between_tools"}`。不接受手動額度或 `disabled`。                                                                  |
| `thinking.display`                | 列舉                 | 僅限自適應模式：`omitted`（預設）或 `summarized`。省略摘要不代表停用思考。                                                                                                     |
| `thinking.block_binding`          | 物件，Beta            | 僅限自適應模式。需要 `thinking-binding-controls-2026-08-01`；請遵循官方保留思考內容的規格。                                                                                    |
| `output_config.effort`            | 列舉或 null           | `low`、`medium`、`high`、`xhigh`、`max`；預設為 `high`。Null 會沿用預設值。                                                                                          |
| `output_config.format`            | 物件或 null           | 結構化 JSON 輸出：`{"type":"json_schema","schema":{...}}`。請使用支援的 JSON Schema 子集。                                                                           |
| `stream`                          | 布林值                | 預設為 `false`；`true` 會傳回 SSE 事件。                                                                                                                       |
| `stop_sequences`                  | 字串陣列               | 官方規格會在符合字串時停止生成。上游相容性檢查未落實此行為。                                                                                                                       |
| `temperature`                     | 數值或 null           | 僅為相容性接受 1；請省略。其他非 null 值會被拒絕。                                                                                                                        |
| `top_p`                           | 數值或 null           | 僅為相容性接受 0.99–1；請省略。                                                                                                                                  |
| `top_k`                           | 不接受非 null 值        | 不支援取樣設定；請省略此屬性。                                                                                                                                      |
| `tools`                           | 物件陣列               | 用戶端工具包含 `name`、`input_schema`，以及選填的描述／嚴格性設定。伺服器工具採用其官方版本定義。                                                                                          |
| `tool_choice`                     | 物件                 | `auto`（預設）或 `none`。不接受 `any` 或指定名稱的強制 `tool`。`auto` 可包含 `disable_parallel_tool_use`。                                                                 |
| `metadata.user_id`                | 字串或 null           | 最多 512 個字元；請使用不含個人資訊的識別碼。                                                                                                                            |
| `cache_control`                   | 物件或 null           | `type: "ephemeral"`；`ttl: "5m"`（預設）或 `"1h"`。Sonnet 5.5 至少需要 512 個可快取 Token。官方 API 也支援區塊層級的快取斷點。                                                      |
| `diagnostics`                     | 物件或 null           | `previous_message_id`：最多 256 個字元的字串或 null。用於請求快取差異診斷。                                                                                                |
| `service_tier`                    | 列舉                 | `auto`（預設）或 `standard_only`。                                                                                                                         |
| `speed`                           | 列舉或 null           | 省略，或使用 `standard` / null。Sonnet 5.5 不支援 `fast`。                                                                                                      |
| `inference_geo`                   | 字串或 null           | 官方預設值來自帳號設定。僅憑請求被接受，無法確認實際處理地區。                                                                                                                      |
| `fallbacks`                       | 字串、物件陣列或 null，Beta | `"default"` 或最多三個備援項目。每個項目都必須有 `model`；可覆寫的選填欄位為 `max_tokens`、`thinking`、`output_config` 與 `speed`。請參閱下方備援規則。                                        |
| `fallback_credit_token`           | 字串、物件或 null        | 先前拒絕回應中的權杖，或 `{"token":"...","mode":"strict"}`。物件格式需要 `fallback-credit-2026-07-01`；mode 為 `strict`（預設）或 `best_effort`。不可與非 null 的 `fallbacks` 值同時使用。 |
| `container`                       | 字串、物件或 null        | 容器 ID，或包含選填 `id` 與 `skills`（最多 20 個）的容器設定。Skills 使用官方的型別、識別碼與版本欄位。                                                                                   |
| `context_management`              | 物件或 null           | 官方上下文編輯設定，包含 `edits`；null 表示省略此設定。仍須遵循個別模型的編輯相容性限制。                                                                                                  |
| `mcp_servers`                     | 物件陣列               | 官方 MCP 伺服器定義，須符合要求的 Beta 版本與伺服器驗證。空陣列測試無法確認遠端 MCP 能否執行。                                                                                              |
| `compaction`                      | 物件或 null，Beta      | `{"type":"summarize"}`，搭配 `compact-2026-09-04`；null 表示省略壓縮。啟用壓縮時，不可同時使用非 null 的 `context_management`、停止序列或結構化輸出格式。目前的簽章壓縮行為未通過測試。                    |
| `messages[].output_config.effort` | 列舉，Beta            | 系統訊息中的逐則 effort 設定；需要 `mid-conversation-output-config-2026-07-01`。只設定 effort 的系統訊息可放在任何位置；含內容的系統訊息群組須遵循官方放置規則。在 `between_tools` 模式中不可用它變更 effort。    |

## 思考與工具 [#思考與工具]

`between_tools` 只接受 `type` 屬性，以及 `low`、`medium` 或 `high` effort。請勿同時傳送 `display`、`budget_tokens` 或 `block_binding`。範例：

```json
{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "thinking": {"type": "between_tools"},
  "output_config": {"effort": "medium"},
  "messages": [{"role": "user", "content": "Explain this concept briefly."}]
}
```

不支援 assistant 預填。若要繼續 `pause_turn`，請原樣重播回傳的伺服器工具 assistant 內容。壓縮會摘要現有歷史，並非 assistant 預填。請完整保留思考區塊與簽章；除非遵循官方綁定規則，否則不要將它們移至其他模型或修改先前歷史。

在原生 Claude API 中，電腦操作需要 `computer_toolset_20260801`；`computer_20251124` 會被拒絕。此執行模型也不接受使用 `claude-opus-4-8`、`claude-opus-4-7` 或 `claude-sonnet-5` 的 Advisor 設定。

## 媒體輸入 [#媒體輸入]

圖片與 PDF 請使用可公開存取的 HTTP(S) URL，放在使用者訊息的 `content` 區塊中。檔案須由您自行託管；此整合不提供 Files API 或上傳功能。圖片輸入範例：

```json
{"role":"user","content":[
  {"type":"image","source":{"type":"url","url":"https://example.com/chart.png"}},
  {"type":"text","text":"What does this chart show?"}
]}
```

PDF 請使用 `document` 區塊。繼續對話時，請保持工具呼叫 ID、完整思考區塊與簽章不變。用戶端工具由您的應用程式執行並傳回結果；宣告工具不會執行工具。

## 價格 [#價格]

每 100 萬 Token 的美元價格

目前費率已包含各分組的倍率。價格快取最長保留 2 分鐘。

一把 API 金鑰即可存取所有模型與分組。「預設」標示自動路由順序中第一個符合條件的分組；請求依實際選用分組的費率計費。

### Claude Sonnet 5.5

`claude-sonnet-5-5`

| 計費 Token | claude · 預設 · 所有輸入長度 |
| --- | ---: |
| 輸入（未快取） | US$1 |
| 輸出 | US$5 |
| 快取讀取 | US$0.05 |
| 快取寫入 · 5 分鐘 | US$1.25 |
| 快取寫入 · 1 小時 | US$2 |

— 表示目前沒有經確認的報價，不代表免費。

只有回應中回報相應快取用量時，才適用快取費率。請勿將快取 Token 再次計入未快取輸入。

將各項計費 Token 數量乘以對應費率後加總，再除以 1,000,000。思考 Token 已包含在輸出 Token 中，不會重複計費。快取讀取、5 分鐘寫入與 1 小時寫入分別採用不同費率。按長度計價時，請先選擇適用區間，再計算請求費用。

## 回應與串流 [#回應與串流]

已完成的訊息包含 `id`、`type`、`role`、`model`、`content`、`stop_reason` 與 `usage`。請從 `content` 讀取文字區塊；第一個區塊也可能是思考內容或工具呼叫。以下僅為示例：

```json
{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [{"type": "text", "text": "A database index helps locate rows without scanning the whole table."}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 24, "output_tokens": 18}
}
```

設為 `stream: true` 可使用 SSE，並搭配 `curl -N`。請處理 `message_start`、`content_block_start`、`content_block_delta`、`content_block_stop`、`message_delta` 與 `message_stop`，以及 `ping` 和串流錯誤。請讀取最終用量，不要將每個區塊視為完整回應。

## OpenAI 相容格式 [#openai-相容格式]

同一模型 ID 也適用於 `POST /v1/chat/completions` 與 `POST /v1/responses`。請使用 `Authorization: Bearer YOUR_API_KEY`，並將 OpenAI SDK 基底 URL 設為 `https://api.wanapi.app/v1`。Chat Completions 使用 `messages`；Responses 使用 `input`。這些欄位會轉換為 Messages 格式，因此使用上述原生參數時，請選用 `/v1/messages`。

```bash
curl https://api.wanapi.app/v1/chat/completions \
  -H "Authorization: Bearer $WAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":256,"messages":[{"role":"user","content":"Reply with OK."}]}'
```

## 用量記錄與錯誤 [#用量記錄與錯誤]

[LLM 記錄](/zh-tw/usage)顯示最近 7 天已完成的呼叫，包含模型、輸入 Token、輸出 Token 與費用。呼叫完成後請重新整理，並依 `claude-sonnet-5-5` 篩選。圖片與影片請查看[任務記錄](/zh-tw/tasks)。

請求失敗時，請檢查 HTTP 狀態與 `error` 物件。核對金鑰、[餘額](/zh-tw/docs/balance)、模型 ID 與支援的參數組合。拒絕回應或因達到輸出上限而停止，與 HTTP 錯誤不同。若請求或串流中斷，請先查看記錄再重試：新請求可能產生另一筆費用。

## 模型參考資料 [#模型參考資料]

* [Sonnet 5.5 官方總覽](https://platform.claude.com/docs/en/models/sonnet-5-5/overview)
* [Sonnet 5.5 變更與限制](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5)
* [Messages 參數參考文件](https://platform.claude.com/docs/en/api/messages/create)
* [逐則訊息 effort](https://platform.claude.com/docs/en/build-with-claude/effort)
* [隨需壓縮](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand)
* [拒絕回應與備援](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback)
* [備援抵扣](https://platform.claude.com/docs/en/build-with-claude/fallback-credit)
