結構化輸出

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

• JSON 輸出（output_config.format）：以特定的 JSON 格式取得 Claude 的回應
• 嚴格工具使用（strict: true）：保證對工具名稱和輸入進行 schema 驗證

您可以在同一個請求中獨立使用或同時使用這些功能。

為何使用結構化輸出

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

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

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

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

JSON 輸出

JSON 輸出控制 Claude 的回應格式，確保 Claude 回傳符合您 schema 的有效 JSON。當您需要以下功能時，請使用 JSON 輸出：

• 控制 Claude 的回應格式
• 從圖片或文字中擷取資料
• 產生結構化報告
• 格式化 API 回應

快速開始

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,
            },
        }
    },
)
print(next(block.text for block in response.content if block.type == "text"))

回應格式： 在回應的文字內容區塊中，符合您 schema 的有效 JSON

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

運作方式

1. 1

   定義您的 JSON schema

   建立一個 JSON schema，描述您希望 Claude 遵循的結構。此 schema 使用標準 JSON Schema 格式，但有一些限制（請參閱 JSON Schema 限制）。

2. 2

   加入 output_config.format 參數

   在您的 API 請求中加入 output_config.format 參數，並設定 type: "json_schema" 以及您的 schema 定義。

3. 3

   解析回應

   Claude 的回應是符合您 schema 的有效 JSON，會在回應的文字內容區塊中回傳。

在 SDK 中使用 JSON 輸出

SDK 提供輔助工具，讓您更輕鬆地使用 JSON 輸出，包括 schema 轉換、自動驗證，以及與熱門 schema 函式庫的整合。

使用原生 schema 定義

您可以使用您所用語言中熟悉的 schema 定義工具，而不必撰寫原始 JSON schema：

• Python： 搭配 client.messages.parse() 使用 Pydantic 模型
• TypeScript： 搭配 zodOutputFormat() 使用 Zod schema，或搭配 jsonSchemaOutputFormat() 使用具型別的 JSON Schema 字面值
• Java： 透過 outputConfig(Class<T>) 自動推導 schema 的一般 Java 類別
• Ruby： 搭配 output_config: {format: Model} 使用 Anthropic::BaseModel 類別
• PHP： 搭配 outputConfig: ['format' => MyClass::class] 使用實作 StructuredOutputModel 的類別
• C#： 搭配泛型 Create<T>() 多載使用一般 C# 類別，該多載會自動推導 schema
• Go： 在 beta API 上自動反射為 JSON schema 的 Go struct，或透過 output_config 傳遞原始 JSON schema
• CLI： 透過 output_config 傳遞原始 JSON schema

from pydantic import BaseModel
from anthropic import Anthropic


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)

SDK 專屬方法

每個 SDK 都提供輔助工具，讓使用結構化輸出更加容易。完整詳情請參閱各 SDK 頁面。

from pydantic import BaseModel
# ...
class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
# ...
response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract contact info: John Smith, john@example.com, interested in the Pro plan",
        }
    ],
    output_format=ContactInfo,
)

# 直接存取剖析後的輸出
contact = response.parsed_output
print(contact.name, contact.email)

from anthropic import transform_schema
from pydantic import TypeAdapter
# ...

# 先將 Pydantic 模型轉換為 JSON schema，再進行轉換
schema = TypeAdapter(ContactInfo).json_schema()
schema = transform_schema(schema)
# 視需要修改 schema
schema["properties"]["custom_field"] = {"type": "string"}

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "..."}],
    output_config={
        "format": {"type": "json_schema", "schema": schema},
    },
)

SDK 轉換的運作方式

Python、TypeScript、Ruby 和 PHP SDK 會自動轉換含有不支援功能的 schema。C# 和 Go SDK 在 schema 從原生型別推導時（C# 中的 Create<T>()；Go beta API 上的 struct 反射或 BetaJSONSchemaOutputFormat()）會套用相同的轉換。轉換步驟如下：

1. 移除不支援的限制條件（例如 minimum、maximum、minLength、maxLength）
2. 以限制條件資訊更新描述（例如「Must be at least 100」），當該限制條件未被結構化輸出直接支援時
3. 為所有物件加入 additionalProperties: false
4. 篩選字串格式，僅保留支援的清單
5. 依據您的原始 schema 驗證回應（包含所有限制條件）

這表示 Claude 收到的是簡化後的 schema，但您的程式碼仍會透過驗證強制執行所有限制條件。

範例： 帶有 minimum: 100 的 Pydantic 欄位在傳送的 schema 中會變成一般整數，但 SDK 會將描述更新為「Must be at least 100」，並依據原始限制條件驗證回應。

常見使用案例

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 限制

達到 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 定義聯絡支援團隊。

資料保留

使用結構化輸出時，提示和回應會以 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