如何使用 Claude Sonnet 5.5 API

TL;DR

Claude Sonnet 5.5 是一個適合範圍明確的程式開發、文件與工具使用工作流程的快速模型。Anthropic 報告其在相同標準 token 費率下，相較 Sonnet 5 輸出速度提升超過 30%。使用 CometAPI 金鑰、模型 ID claude-sonnet-5-5，先從一個小型的 Messages 或 Chat Completions 請求開始。現有代理在上線前應重新測試思考設定、工具選擇與歷史回放。

關鍵重點

• 使用 Claude Sonnet 5.5，並讓請求格式匹配所用端點。
• 先從一個短請求開始，再逐步加入影像、工具或長上下文。
• 對 Claude 特定控制使用 Messages；若既有應用採 OpenAI SDK，使用 Chat Completions。
• 在遷移現有代理迴圈前，檢視思考與工具選擇的變化。
• 在擴大流量前，對比已接受任務的品質、延遲、token 使用與快取命中率。

什麼是 Claude Sonnet 5.5？

Claude Sonnet 5.5 API 是 Anthropic 的 Sonnet 5.5 模型的可程式化介面。其設計用於軟體開發、版本庫分析、客服自動化、文件處理、影像理解、工具驅動代理，以及結構化的專業工作流程。

Anthropic 將 Sonnet 5.5 定位為 Opus 5.5 的更快速、低成本補充，屬於 Claude 5.5 家族中的第二款模型，針對範圍明確的程式撰寫、錯誤修復、文件與簡報建立，以及日常專業任務進行最佳化。開發者可在 CometAPI 中使用 claude-sonnet-5-5 存取 Claude Sonnet 5.5 API。

Anthropic 確認 1M-token 上下文視窗與 128K 的同步輸出上限。僅透過帶有 beta 標頭 output-300k-2026-03-24 的 Message Batches，才可達到 300K token 的批次輸出。閘道功能支援需與模型層級支援分別確認。

Claude Sonnet 5.5 在官方基準上的表現如何？

以下精簡比較有助於在採用 API 前辨識需要評估的工作負載。基準結果不能取代對自身提示與工具迴圈的測試。

Anthropic 的基準結果與評估註記是此比較的依據。Opus 5.5 的 Terminal-Bench 成績使用 Xhigh effort；FrontierCode 對 Sonnet 5.5 報告了 Max 與 Xhigh 的分別結果；OSWorld 為部分評估。GDPval-AA 與 AA-Briefcase 由 Artificial Analysis 在一個預發佈的 Claude Platform 環境上執行，當時存在結構化輸出錯誤，可能低估了 Sonnet 5.5 的分數；Anthropic 表示該錯誤已修復。這些結果應用於指導工作負載測試，而非保證生產結果。Humanity’s Last Exam 使用工具；Chartography 未使用。新加入的行列使用了Anthropic 發佈的分數。下方原始圖片保留；擴充表格新增了三項評估。

官方 Claude Sonnet 5.5 基準比較

Claude Sonnet 5.5 API 與 Sonnet 5 有何變更？

針對思考、工具選擇與歷史回放的變更會影響現有代理迴圈。此表僅摘要運行層面的變動，非完整功能清單。

需要檢查的破壞性變更

檢查以下五項破壞性變更：以 between_tools 取代 disabled 思考；移除強制工具選擇；保留相容的思考區塊與未變動的對話歷史；在 Claude API 與 Google Cloud 上將 computer_20251124 遷移至 computer_toolset_20260801；替換不受支援的顧問配對。Amazon Bedrock 仍接受 computer_20251124。不受支援的顧問包括 Opus 4.8、4.7、4.6，Sonnet 5、Sonnet 4.6，以及 Haiku 5.5。Opus 5.5 是受支援的替代方案之一。請按回應區塊類型解析。上線前驗證平台與閘道相容性。官方遷移指南。

其他能力與工作流程變更

使用官方功能指南檢視進度更新、每則訊息的努力設定與對話中控制。啟用 Beta 功能前先確認閘道支援。

使用 Claude Sonnet 5.5 API 前需要什麼？

• CometAPI 帳戶、API 金鑰、模型存取權與可用餘額。
• 一個帶有 cURL 的終端機；用於 SDK 範例的 Python 與 pip 或 Node.js 與 npm。
• 已選端點：/v1/messages 或 /v1/chat/completions。
• 伺服器環境中儲存 COMETAPI_KEY，以及連線至 https://api.cometapi.com 的網路權限。
• 一個短測試提示與清楚的可用輸出、完成狀態與 token 使用檢查。

如何透過 CometAPI 存取 Claude Sonnet 5.5 API？

當 Claude 的行為本身很重要時，選擇 Messages API。當應用已透過同一抽象層在 Claude、GPT、Gemini、DeepSeek 或其他模型間切換時，選擇相容 OpenAI 的 API。

步驟 1：儲存 API 金鑰

在 CometAPI API 金鑰主控台建立金鑰，然後在執行環境中設定。

在 POSIX shell 設定 CometAPI 金鑰

export COMETAPI_KEY="YOUR_COMETAPI_KEY"

在 PowerShell 設定 CometAPI 金鑰

$env:COMETAPI_KEY="YOUR_COMETAPI_KEY"

步驟 2：發送第一個 Messages 請求

發送第一個與 Anthropic 相容的 Messages 請求

curl https://api.cometapi.com/v1/messages \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 2048,
    "messages": [{"role": "user", "content": "Explain exponential backoff in three bullet points."}]
  }'

在增加更多控制前，檢視 content 區塊、stop_reason 與 usage。上述 cURL 語法使用 POSIX shell。

步驟 3：使用 Anthropic Python SDK

安裝 Anthropic Python SDK

pip install anthropic

使用 Anthropic SDK 讀取文字區塊與 usage

import os
import anthropic

anthropic_client = anthropic.Anthropic(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com",
)

response = anthropic_client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Review this migration plan and list the three biggest risks."}],
)

for block in response.content:
    if block.type == "text":
        print(block.text)
print("Completion:", response.stop_reason)
print("Usage:", response.usage)

步驟 4：使用 OpenAI Python SDK

安裝 OpenAI Python SDK

pip install openai

透過相容 OpenAI 的 Chat Completions 呼叫 Sonnet 5.5

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com/v1",
)

response = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[
        {
            "role": "system",
            "content": "You are a concise software engineering assistant."
        },
        {
            "role": "user",
            "content": "Review this function and identify the highest-risk bug."
        }
    ],
)

print(response.choices[0].message.content)

當應用已使用 OpenAI SDK 介面時，此方式很實用。基礎文字整合可能只需新的 base URL、API 金鑰與模型 ID，但生產遷移仍應驗證支援的參數、回應格式、工具呼叫、串流事件、逾時與 token 計費。

步驟 5：在 Node.js 中使用 JavaScript

安裝 OpenAI Node.js SDK

npm install openai

從 Node.js ES 模組呼叫 Sonnet 5.5

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.COMETAPI_KEY,
  baseURL: "https://api.cometapi.com/v1",
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-5-5",
  messages: [
    {
      role: "user",
      content: "Create a TypeScript function that validates an email address.",
    },
  ],
});

console.log(response.choices[0].message.content);

對後端 Node.js 應用，將 COMETAPI_KEY 保留在伺服器環境中，而非傳送至瀏覽器端。

Claude Sonnet 5.5 的思考與努力等級

API 預設為高努力等級；Claude 應用與 Claude Code 預設為中等。根據已接受任務品質、延遲與 token 成本選擇努力等級。下表為編輯性起點，非官方工作負載分類。

避免將最高努力設定自動套用到每個請求。當額外推理導致更多工具呼叫與更長輸出時，代理工作負載可能變得更昂貴。按任務層級評估選擇設定。對 Xhigh 與 Max 使用自適應思考，然後與較低等級比較已接受任務品質與總成本。官方努力指引。

透過 Messages 設定努力等級

以下範例使用前述初始化的 Anthropic 客戶端。在上線前，於 CometAPI 路由測試相同控制。

設定自適應思考與高努力

response = anthropic_client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=8192,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "Audit this service migration plan."}],
)

關閉前置思考

在低、中或高努力下使用 thinking={"type": "between_tools"}。對 xhigh 或 max 使用自適應思考。between_tools 不帶有 display 或 budget_tokens 欄位，且不允許在對話中變更努力等級。

在工具迴圈中保留思考

在附加工具結果前，先回傳原始的助手內容區塊。保留的思考取決於模型、對話前綴與產生的帳戶。自 2026-08-31 00:00 UTC 起建立的帳戶，Claude API、Amazon Bedrock 與 Google Cloud 預設強制前綴綁定。不要假設每個閘道都提供相同的綁定控制。

如何串流 Claude Sonnet 5.5 回應

串流長回應

串流適用於聊天介面、程式助理與長回應，因為使用者可在生成完成前看到輸出。

透過相容 OpenAI 的 Chat Completions 串流文字

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com/v1",
)

stream = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[
        {
            "role": "user",
            "content": "Explain how a retrieval-augmented generation pipeline works."
        }
    ],
    stream=True,
)

for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

串流通常不會減少生成的總 token 數；其主要好處是感知延遲。應用亦應明確處理中斷串流、部分輸出、網路重試與取消。

使用自動選擇的工具

使用 tool_choice={"type": "auto"}。驗證每個工具名稱與參數，套用授權與逾時，回傳結構化結果，並限制迭代。必要的工具執行應由應用協調層負責。

定義票單查詢工具並請求自動選擇

tools = [{
    "name": "lookup_ticket",
    "description": "Retrieve a support ticket by ID",
    "input_schema": {
        "type": "object",
        "properties": {"ticket_id": {"type": "string"}},
        "required": ["ticket_id"],
        "additionalProperties": False,
    },
}]

response = anthropic_client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    tools=tools,
    tool_choice={"type": "auto"},
    messages=[{"role": "user", "content": "Look up ticket T-123 and summarize its status."}],
)

一個 tool_use 區塊表示行動請求；這個初次呼叫不會執行它。請在伺服器上驗證請求、執行操作、附加未更動的助手內容，並送出對應的 tool_result。此範例的結構仍需應用端驗證；嚴格工具支援需在所選路由上檢查。

為重複上下文使用提示快取

當請求反覆包含相同的大型前綴（如系統政策、工具結構、版本庫索引、產品文件、可重用指示或參考手冊）時，提示快取很有用。

Sonnet 5.5 要求可快取的提示前綴至少 512 tokens。短於此長度即使設定了 cache_control 也不會快取。檢查 cache_creation_input_tokens 與 cache_read_input_tokens；兩者皆為 0 代表未使用快取。於所選閘道路線確認支援。提示快取參考。

在動態請求內容之前安排穩定上下文

Stable system instructions
Stable tools
Stable repository or knowledge context
---------------- cache boundary ----------------
Current user request
Current retrieved context

目前 CometAPI 的快取讀取費率為每百萬 tokens $0.16，相較新鮮輸入的 $1.60。快取寫入另行計費。於用量中繼資料中確認快取命中再估算節省。

快取對重用大型上下文前綴的程式代理與企業助理尤其有用。經濟性仍取決於實際命中率；經常改寫穩定前綴可能消除大部分預期效益。

使用所選端點架構傳送影像

Sonnet 5.5 接受文字與影像輸入。以下 JSON 為相容 OpenAI 的 Chat Completions 載荷；將示例影像 URL 替換為你可控制且可公開存取的影像。Messages 使用不同的影像區塊架構。

在 Chat Completions 載荷中傳送影像

{
  "model": "claude-sonnet-5-5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Find the three most important UI problems in this screenshot."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/interface.png"
          }
        }
      ]
    }
  ]
}

多模態請求的具體形狀在 Claude 原生與相容 OpenAI 的介面間可能不同，因此請按實際部署的端點使用其架構，而非假設兩者可互換。

處理保護措施與資料保留

將拒絕與降級行為記錄為明確的應用狀態。Anthropic 描述了其服務的保護措施與零資料保留可用性。在傳送生產資料前，另行驗證所用閘道的適用保留與路由安排。

Claude Sonnet 5.5 與 Sonnet 5、Opus 5.5 的比較

以下定性標籤為基於任務範圍的編輯性路由指引，非官方性能等級。請在具代表性的工作負載上驗證這些角色。不要用基準分數推斷詳細架構。

將困難任務導向升級模型

Routine task
    ↓
Claude Sonnet 5.5
    ↓
Confidence / validation failure?
    ├── No → Return result
    └── Yes → Escalate difficult case
                 ↓
              Opus-class model

此路由樣式可在降低成本的同時，保留對更強推理層級的存取以處理困難案例。

透過 CometAPI 使用 Claude Sonnet 5.5 的定價

2026-10-10 檢查：CometAPI 輸入/輸出仍為每百萬 tokens $1.60/$8，較 Anthropic 的 $2/$10 低 20%。CometAPI 快取讀/寫仍為 $0.16/$2；Anthropic 目前快取讀/寫分別為 $0.10/$2.50（5 分鐘寫入）。發佈頁仍顯示 $0.20 快取讀；本修訂使用目前的快取參考。閘道價格可獨立變動。

對代理應用而言，token 價格與任務成本之差異很重要。程式代理可能產生較少 tokens，卻仍執行多輪工具呼叫、快取讀取、程式碼檢查、重試與驗證。因此每個成功任務的成本通常比單純的輸入 token 價格更具參考價值。

估算新鮮輸入與輸出 token 的收費

Input:
100,000 / 1,000,000 × $1.60 = $0.16

Output:
5,000 / 1,000,000 × $8.00 = $0.04

Estimated model-token cost:
$0.20

工具費用、快取操作、重複的代理步驟或其他計費功能都可能改變最終成本。

2026-10-10 重新核對 CometAPI 目前的模型頁面。新鮮輸入/輸出價格未變，因此對 100,000 新鮮輸入與 5,000 輸出 tokens 的示例仍為 $0.16 + $0.04 = $0.20。此不包含快取寫入、快取讀取、工具費與重試。預算編列前重新檢查路由特定計費。

控制每個已接受任務的成本

有幾種務實方式可在不立即更換模型的情況下降低支出。首先，明確定義完成標準：

定義聚焦的回應接受格式

Return only:
1. the root cause;
2. the affected file;
3. the smallest safe fix;
4. one regression test.

其次，在發送前修剪檢索的上下文。1M-token 上下文視窗是容量上限，而非目標。第三，透過提示快取重用穩定上下文。第四，按工作負載選擇努力等級，而非對所有請求設為高。第五，衡量每個已接受任務成本：

計算每個已接受任務成本

Total API cost
÷
Number of outputs accepted without rework

較便宜的請求不一定意味著較便宜的工作流程，若其導致額外重試、校正或工具呼叫。

如何從 Sonnet 5 遷移到 Claude Sonnet 5.5 API？

1. 保留先前的生產設定以便回滾。
2. 將模型 ID 從 claude-sonnet-5 改為 claude-sonnet-5-5。
3. 套用上述思考、工具選擇與歷史的變更。
4. 重播具有代表性的請求，包括工具、影像與串流。
5. 比較已接受輸出、人工修正率、p50/p95 延遲與總任務成本。
6. 測試重試、拒絕、取消與中斷串流。
7. 從用量中繼資料驗證快取命中與輸出預算行為。
8. 釋出小流量金絲雀，僅在通過驗收門檻後擴大。

Claude Sonnet 5.5 API 錯誤疑難排解

不要對格式錯誤的請求或未變更的驗證失敗重試。重播中斷的代理執行時避免重複工具動作。

Claude Sonnet 5.5 生產最佳實務

選擇一個工作負載、定義接受門檻，並評估完整應用。記錄模型 ID、端點、努力等級、延遲、token 與快取使用、工具失敗、完成狀態與已接受任務結果。將金鑰保留在伺服器端，設定逾時、有界重試與代理迭代上限。

量測工作流程品質與可靠性

對程式代理，亦請追蹤通過的測試數、被不必要修改的檔案、回滾的修補，以及無需人工介入的成功完成。

範例：修復一個範圍明確的版本庫錯誤

提供失敗的測試、相關原始碼與預期行為。要求提供聚焦的修補與回歸檢查。接受門檻為可重現修復、通過相關測試且無不相干修改。比較總 API 與工具成本與被接受的修補。

範例：分類客服工單

檢索客戶問題與已核准的知識庫段落。要求模型分類問題、起草有證據支撐的回覆，並標記需要升級的案例。僅在其主張符合檢索資料且路由決策遵循支援政策時接受。

範例：審閱文件與螢幕截圖

提供已核准程序與相應介面的截圖。要求指出差異並附上相關段落與可見 UI 元素的參考。在修改程序前要求審閱者確認發現。

結論

Claude Sonnet 5.5 為團隊提供在程式撰寫、支援、文件與工具使用工作流程中的實用候選。從一個可運作的 CometAPI 請求開始，然後加入應用所需的控制。

遷移不僅是更換模型 ID：請檢查思考設定、自動工具選擇、回應解析與歷史回放。當你的工作負載評估顯示可接受的品質、延遲與成本平衡時推廣此模型；對未通過接受門檻的任務保留更強層級。

常見問題

團隊應如何在不中斷服務的情況下輪替 Claude Sonnet 5.5 API 金鑰？

將金鑰儲存在伺服器端的祕密管理器，讓工作程序在不嵌入應用程式碼的情況下重新載入憑證。若供應商支援重疊啟用金鑰，先引入替換金鑰、驗證小型請求、逐步切換工作程序，然後撤銷之前的金鑰。在變更期間監控驗證錯誤，避免記錄任一金鑰。

工作者重啟後，Claude Sonnet 5.5 作業如何恢復？

持久化作業識別碼、最後完成步驟、請求設定與工具執行記錄。從已驗證的檢查點恢復。在重播工具動作前，檢查其是否已完成以及是否可安全重複。僅保存對話記錄無法防止重複票單、訊息或資料庫寫入。

團隊應如何偵測 Claude Sonnet 5.5 隨時間的行為變化？

維持帶日期的評估集，包含已接受答案或接受檢查，以及 SDK 版本與請求設定。定期與在供應商、SDK、提示或路由變更後重跑。比較任務成功、修正率、延遲與總成本。若帳戶提供版本釘選，倚賴前先確認其保證；對關鍵工作流程保留回滾路由。