結構化輸出

「Structured outputs」（結構化輸出）會限制 Claude 的回應遵循特定的 schema（結構描述），確保輸出有效且可解析，以供下游處理。結構化輸出提供兩項互補的功能：

• JSON 輸出（output_config.format）：以特定 JSON 格式取得 Claude 的回應，例如從圖片或文字中擷取資料、產生結構化報告，或格式化 API 回應。本頁介紹 JSON 輸出。
• 嚴格工具使用（strict: true）：保證對工具名稱和輸入進行 schema 驗證。請參閱嚴格工具使用。

您可以獨立使用這些功能，也可以在同一個請求中一起使用。

為何使用結構化輸出

若沒有結構化輸出，Claude 可能會產生格式錯誤的 JSON 回應或無效的工具輸入，進而破壞您的應用程式。即使經過仔細的提示設計，您仍可能遇到：

• 因無效 JSON 語法導致的解析錯誤
• 缺少必要欄位
• 資料型別不一致
• 需要錯誤處理和重試的 schema 違規

結構化輸出透過「constrained decoding」（受限解碼）保證回應符合 schema：

• 永遠有效： 不再有 JSON.parse() 錯誤
• 型別安全： 保證欄位型別和必要欄位
• 可靠： 不需要因 schema 違規而重試

運作方式

1. 1

   定義您的 schema

   以 JSON schema 或您所用語言中的型別來描述您想要的結構。該 schema 遵循 JSON Schema，但有一些限制。

2. 2

   在 output_config.format 中傳送

   請求會在 output_config.format 中攜帶 schema，並設定 type: "json_schema"。SDK 輔助工具會為您設定這些內容。

3. 3

   讀取回應

   Claude 會在回應的文字內容區塊中傳回符合您 schema 的有效 JSON。SDK 輔助工具會將其解析為您的型別。

使用方式

from pydantic import BaseModel
# ...


class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
    demo_requested: bool


client = Anthropic()

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@example.com) is interested in our Enterprise plan "
                "and wants to schedule a demo for next Tuesday at 2pm."
            ),
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)

name='John Smith' email='john@example.com' plan_interest='Enterprise' demo_requested=True

SDK 轉換的運作方式

大多數 SDK 輔助工具會轉換使用了不支援功能的 schema。轉換步驟如下：

1. 移除不支援的限制條件（例如 minimum、maximum、minLength、maxLength）
2. 更新描述，將每個不支援的限制條件加入欄位的描述中（例如 {minimum: 100}）
3. 為所有物件新增 additionalProperties: false
4. 篩選字串格式，僅保留支援的清單
5. 驗證回應，若輔助工具會驗證回應，則依據您原始的 schema 及其所有限制條件進行驗證

Claude 收到的是簡化後的 schema，但會驗證回應的輔助工具仍會在您的程式碼中強制執行每一項限制條件。

範例： 具有 minimum: 100 的欄位在傳送的 schema 中會變成一般整數，而 SDK 會將 {minimum: 100} 加入該欄位的描述中。會驗證回應的輔助工具仍會依據 minimum: 100 檢查回應。

使用原始 JSON schema

若要使用來自檔案、OpenAPI 規格，或在執行時期建構的 JSON schema，請將其傳入 output_config.format。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@example.com) is interested in our Enterprise plan "
                "and wants to schedule a demo for next Tuesday at 2pm."
            ),
        }
    ],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan_interest": {"type": "string"},
                    "demo_requested": {"type": "boolean"},
                },
                "required": ["name", "email", "plan_interest", "demo_requested"],
                "additionalProperties": False,
            },
        }
    },
)
text = next(block.text for block in response.content if block.type == "text")
contact = json.loads(text)
print(contact)

{'name': 'John Smith', 'email': 'john@example.com', 'plan_interest': 'Enterprise', 'demo_requested': True}

常見使用案例

from pydantic import BaseModel


class Invoice(BaseModel):
    invoice_number: str
    date: str
    total_amount: float
    line_items: list[dict]
    customer_name: str


client = anthropic.Anthropic()
invoice_text = "Invoice #12345, Date: 2024-01-15, Total: $500.00"

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=4096,
    output_format=Invoice,
    messages=[
        {"role": "user", "content": f"Extract invoice data from: {invoice_text}"}
    ],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class Classification(BaseModel):
    category: str
    confidence: float
    tags: list[str]
    sentiment: str


feedback_text = "Great product, but the delivery was slow."
response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=Classification,
    messages=[{"role": "user", "content": f"Classify this feedback: {feedback_text}"}],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class APIResponse(BaseModel):
    status: str
    data: dict
    errors: list[dict] | None
    metadata: dict


response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=APIResponse,
    messages=[{"role": "user", "content": "Process this request: ..."}],
)

print(response.parsed_output)

嚴格工具使用

若要透過文法受限取樣對工具輸入強制執行 JSON Schema 合規性，請參閱嚴格工具使用。

同時使用兩項功能

JSON 輸出和嚴格工具使用解決不同的問題，並可協同運作：

• JSON 輸出控制 Claude 的回應格式（Claude 說什麼）
• 嚴格工具使用驗證工具參數（Claude 如何呼叫您的函式）

結合使用時，Claude 可以使用保證有效的參數呼叫工具，並且回傳結構化的 JSON 回應。這對於同時需要可靠工具呼叫和結構化最終輸出的代理工作流程非常有用。

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Help me plan a trip to Paris departing May 15, 2026",
        }
    ],
    # JSON 輸出：結構化回應格式
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "next_steps": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["summary", "next_steps"],
                "additionalProperties": False,
            },
        }
    },
    # 嚴格工具使用：保證符合規格的工具參數
    tools=[
        {
            "name": "search_flights",
            "strict": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "destination": {"type": "string"},
                    "date": {"type": "string", "format": "date"},
                },
                "required": ["destination", "date"],
                "additionalProperties": False,
            },
        }
    ],
)

print(response)

重要注意事項

文法編譯與快取

結構化輸出使用搭配已編譯文法產物的受限取樣。這會帶來一些需要注意的效能特性：

• 首次請求延遲： 第一次使用特定 schema 時，文法編譯會產生額外的延遲
• 自動快取： 已編譯的文法會自上次使用起快取 24 小時，使後續請求快上許多
• 快取失效： 若您變更以下項目，快取將會失效：
  • JSON schema 結構
  • 請求中的工具集合（同時使用結構化輸出和工具使用時）
  • 僅變更 name 或 description 欄位不會使快取失效

提示修改與 token 成本

使用結構化輸出時，Claude 會自動收到一段額外的系統提示，說明預期的輸出格式。這表示：

• 您的輸入 token 數量會略微增加
• 注入的提示會像任何其他系統提示一樣消耗您的 token
• 變更 output_config.format 參數會使該對話串的任何提示快取失效

JSON Schema 限制

結構化輸出支援標準 JSON Schema，但有一些限制。JSON 輸出和嚴格工具使用共用這些限制。

屬性順序

使用結構化輸出時，物件中的屬性會維持您在 schema 中定義的順序，但有一個重要的注意事項：必要屬性會先出現，接著才是選用屬性。

例如，給定以下 schema：

{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

輸出會將屬性排序為：

1. name（必要，依 schema 順序）
2. email（必要，依 schema 順序）
3. notes（選用，依 schema 順序）
4. age（選用，依 schema 順序）

這表示輸出可能如下所示：

{
  "name": "John Smith",
  "email": "john@example.com",
  "notes": "Interested in enterprise plan",
  "age": 35
}

若輸出中的屬性順序對您的應用程式很重要，請將所有屬性標記為必要，或在您的解析邏輯中考量此重新排序。

無效輸出

雖然結構化輸出在大多數情況下保證符合 schema，但在某些情境下輸出可能不符合您的 schema：

拒絕（stop_reason: "refusal"）

即使使用結構化輸出，Claude 仍會維持其安全性和有幫助的特性。若 Claude 因安全理由拒絕請求：

• 回應會有 stop_reason: "refusal"
• 您會收到 200 狀態碼
• 您會被收取所產生 token 的費用
• 輸出可能不符合您的 schema，因為拒絕訊息優先於 schema 限制

要求模型提供其思考過程或逐步推理的屬性，可能會導致 reasoning_extraction 拒絕。請改為要求簡短的說明。請參閱將推理保留在思考區塊中。

達到 token 上限（stop_reason: "max_tokens"）

若回應因達到 max_tokens 上限而被截斷：

• 回應會有 stop_reason: "max_tokens"
• 輸出可能不完整且不符合您的 schema
• 請以更高的 max_tokens 值重試，以取得完整的結構化輸出

列舉值大小寫

結構化輸出不保證字串 enum 和 const 值的大小寫：Claude 可能回傳一個僅在大小寫上與您的 schema 不同的值，通常是空格後單字的第一個字母。例如，給定以下 schema：

{
  "type": "string",
  "enum": ["Conversation Topic 1", "Conversation Topic 2", "Conversation topic 3"]
}

輸出可能包含 "Conversation Topic 3"（大寫「T」），即使該確切值不在列舉中。回應會正常完成，沒有錯誤也沒有特殊的 stop_reason。這同時適用於 JSON 輸出和嚴格工具使用。請以不區分大小寫的方式比較列舉值，並避免使用僅在大小寫上不同的列舉值。

Schema 複雜度限制

結構化輸出的運作方式是將您的 JSON schema 編譯為限制 Claude 輸出的文法。越複雜的 schema 會產生越大的文法，編譯時間也越長。為防止編譯時間過長，API 強制執行數項複雜度限制。

明確限制

以下限制適用於所有帶有 output_config.format 或 strict: true 的請求：

額外的內部限制

除了上表中的明確限制之外，已編譯文法的大小還有額外的內部限制。這些限制之所以存在，是因為 schema 複雜度無法簡化為單一維度：選用參數、聯集型別、巢狀物件和工具數量等功能會彼此交互作用，可能使已編譯的文法變得不成比例地龐大。

超出這些限制時，您會收到訊息為「Schema is too complex for compilation.」的 400 錯誤。這些錯誤表示您的 schema 合計複雜度超出了可有效率編譯的範圍，即使上表中的每項個別限制都已滿足。作為最後的防線，API 也強制執行 180 秒的編譯逾時。通過所有明確檢查但產生非常龐大已編譯文法的 schema 可能會觸及此逾時。

降低 schema 複雜度的技巧

若您觸及複雜度限制，請依序嘗試以下策略：

1. 僅將關鍵工具標記為嚴格。 若您有許多工具，請將嚴格模式保留給 schema 違規會造成實際問題的工具，而對較簡單的工具則仰賴 Claude 的自然遵循能力。

2. 減少選用參數。 盡可能將參數設為 required。每個選用參數大約會使文法狀態空間的一部分加倍。若某個參數總是有合理的預設值，請考慮將其設為必要，並讓 Claude 明確提供該預設值。

3. 簡化巢狀結構。 帶有選用欄位的深層巢狀物件會使複雜度加劇。盡可能將結構扁平化。

4. 拆分為多個請求。 若您有許多嚴格工具，請考慮將它們拆分至不同的請求或子代理中。

若有效的 schema 持續發生問題，請附上您的 schema 定義聯絡支援團隊。

從 beta 版遷移

output_format 參數已移至 output_config.format，且不再需要 beta 標頭。output_format 參數已被棄用，並將在未來移除。若仍要使用它，請新增 structured-outputs-2025-11-13 beta 標頭。若未新增，API 會傳回 400 錯誤。

Python SDK（v1.0 及更新版本）在 client.beta.messages.create() 或 count_tokens() 上不接受 output_format={...}，並會引發 TypeError。請改用 output_config。如需更新後的 API 格式，請參閱使用原始 JSON schema。

資料保留

使用結構化輸出時，提示和回應會以 ZDR 處理。然而，JSON schema 本身會基於最佳化目的，自上次使用起暫時快取最多 24 小時。除 API 回應之外，不會保留任何提示或回應資料。

結構化輸出符合 HIPAA 資格，但 JSON schema 定義中不得包含 PHI。API 會將 JSON schema 編譯為與訊息內容分開快取的文法，而這些快取的 schema 不會獲得與提示和回應相同的 PHI 保護。請勿在 schema 屬性名稱、enum 值、const 值或 pattern 正規表示式中包含 PHI。PHI 應僅出現在訊息內容（提示和回應）中，在那裡它受到 HIPAA 保護措施的保障。

關於所有功能的 ZDR 和 HIPAA 資格，請參閱 API 與資料保留。

功能相容性

可搭配使用：

• 批次處理： 以 50% 折扣大規模處理結構化輸出
• Token 計數： 無需編譯即可計算 token
• 串流： 像一般回應一樣串流結構化輸出
• 合併使用： 在同一個請求中同時使用 JSON 輸出（output_config.format）和嚴格工具使用（strict: true）

不相容：

• 引用： 引用需要將引用區塊與文字交錯，這與嚴格的 JSON schema 限制相衝突。若在啟用引用的情況下使用 output_config.format，會回傳 400 錯誤。
• 訊息預填： 與 JSON 輸出不相容

後續步驟

Compatibility