---
title: 訊息串
url: https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads
description: 透過每次請求僅傳送新訊息，讓長時間執行的代理獲得更快的首個權杖時間，尤其是在長對話中。
featureMetadata:
  status: beta
  betaHeader: message-threads-2026-08-12
  zdr:
    eligibility: not-eligible
    note: 訊息串的內容（對話、系統提示與工具）會保存在記憶體中，以伺服器管理的金鑰加密，絕不寫入持久性儲存空間，並在訊息串最後一次使用後 1 小時內刪除。使用此功能不會影響您使用其他具 ZDR 適用資格的功能。
  supportedModels:
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
    Claude Models on Google Cloud (Anthropic managed): beta
    Microsoft Foundry: beta
---

使用「message thread」（訊息串）時，請求會更小，而且隨著對話增長，「time to first token」（首個權杖時間）會維持較低且更穩定。訊息串在長時間的代理迴圈中最有幫助。沒有訊息串時，每一輪都會重新上傳整個對話，而 API 也會重新驗證並將其全部進行 tokenize。使用訊息串時，大部分的工作只涵蓋新的一輪。

「Message thread」（訊息串）會將對話在伺服器上保留一小段時間。您只需傳送一次完整的對話，連同您的系統提示和工具。在之後的每一輪中，您只需傳送新的訊息以及前一個回應的 `id`。API 會在呼叫模型之前重建對話。您只需在 [Messages API](https://platform.claude.com/docs/zh-TW/api/messages) 請求中加入一個參數 `thread`。回應則是一般的訊息。

<Note>
  訊息串與 Claude Managed Agents 中的 [工作階段執行緒](https://platform.claude.com/docs/zh-TW/managed-agents/session-threads)不同。
</Note>

## 訊息串的運作方式

* **建立。** 像您現在一樣傳送第一個請求，包含完整對話、`system` 和 `tools`，並加上 `"thread": {"type": "create"}`。API 會將對話（包括 Claude 的回覆）儲存在回應的 `id` 之下。
* **繼續。** 只傳送自上一個回應以來的訊息，並加上 `"thread": {"type": "continue", "previous_message_id": "<previous id>"}`。請勿在請求中包含 `system` 和 `tools`。訊息串會保留建立請求中的值。每個新回應的 `id` 用於下一輪。
* **重播。** 訊息串採盡力而為（best-effort）方式。訊息串會在最後一次請求後 5 分鐘過期，且 API 會在最後一次使用後不超過 1 小時內將其刪除。API 儲存的每個回應都會重新開始計算這 5 分鐘。如果 API 無法再繼續該訊息串，繼續請求會傳回 404 錯誤。請在新的建立請求中再次傳送完整對話，並從該回應的 `id` 繼續。SDK 訊息串輔助工具會為您執行此重播（請參閱[SDK 輔助工具的運作方式](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#sdk-helper-handles)）。在收到來自備援模型的回應之後，請參閱[搭配訊息串使用備援](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#fallbacks)。

您的應用程式仍是對話的唯一事實來源（source of truth）。請保留每則訊息的自有副本，並從一開始就建立[重播路徑](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#recover)。無論是對建立請求還是繼續請求的回應，都不會告訴您 API 是否儲存了該輪對話。您要到下一次繼續請求時才會得知。SDK 的訊息串輔助工具會在輔助物件存在期間將此副本保留在記憶體中，且不會將其儲存到其他任何地方。如果對話必須在您的程序結束後繼續存在，請保留您自己的副本。

## 透過 SDK 使用訊息串

SDK 提供一個訊息串輔助工具，可為您建構訊息串請求。使用與 Messages 請求相同的欄位建立它，然後一次傳送一輪。輔助工具會將完整對話保存在記憶體中。

此範例有兩輪。輔助工具會在第一輪建立訊息串，並在第二輪繼續它，同時為您加入 beta 標頭。頂層的 `cache_control` 是選用的。它會要求在每一輪進行提示快取（請參閱[訊息串上的提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#prompt-caching)）。若沒有它，之後的每一輪仍然只會傳送新的訊息，但除非您自行加入快取中斷點，否則不會快取任何內容。

<CodeGroup exclude="shell">
  ```python Python
  client = anthropic.Anthropic()

  # 建立 helper。此呼叫不會傳送任何請求。
  thread = client.beta.messages.thread(
      model="claude-opus-5-5",
      max_tokens=1024,
      cache_control={"type": "ephemeral"},
      system="You are a support agent for Acme. Keep replies short.",
  )

  # 第 1 輪：helper 建立一個 thread 並傳送完整對話
  thread.send({"role": "user", "content": "Hi! I have a question about an order."})

  # 第 2 輪：helper 延續該 thread，僅傳送新訊息
  second = thread.send(
      {"role": "user", "content": "How long does standard shipping usually take?"}
  )

  for block in second.content:
      if block.type == "text":
          print(block.text)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  // 建立 helper。此呼叫不會傳送任何請求。
  const thread = client.beta.messages.thread({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    cache_control: { type: "ephemeral" },
    system: "You are a support agent for Acme. Keep replies short."
  });

  // 第 1 輪：helper 建立一個 thread 並傳送完整對話
  await thread.send({ role: "user", content: "Hi! I have a question about an order." });

  // 第 2 輪：helper 延續該 thread，僅傳送新訊息
  const second = await thread.send({
    role: "user",
    content: "How long does standard shipping usually take?"
  });

  for (const block of second.content) {
    if (block.type === "text") {
      console.log(block.text);
    }
  }
  ```

  ```csharp C#
  using Anthropic.Helpers.Beta;

  AnthropicClient client = new();

  // 建立 helper。此呼叫不會傳送任何請求。
  var thread = client.Beta.Messages.Thread(
      new ThreadCreateParams
      {
          Model = Messages::Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          Messages = [],
          CacheControl = new(),
          System = "You are a support agent for Acme. Keep replies short.",
      }
  );

  // 第 1 輪：helper 建立一個 thread 並傳送完整對話
  await thread.Send(
      new BetaUserMessageParam { Content = "Hi! I have a question about an order." }
  );

  // 第 2 輪：helper 延續該 thread，僅傳送新訊息
  var second = await thread.Send(
      new BetaUserMessageParam { Content = "How long does standard shipping usually take?" }
  );

  foreach (var block in second.Content)
  {
      if (block.TryPickText(out var textBlock))
      {
          Console.WriteLine(textBlock.Text);
      }
  }
  ```

  ```go Go
  client := anthropic.NewClient()
  ctx := context.Background()

  // 建立 helper。此呼叫不會傳送任何請求。
  thread := client.Beta.Messages.NewThread(anthropic.BetaMessageThreadCreateParams{
  	Model:        anthropic.ModelClaudeOpus5_5,
  	MaxTokens:    1024,
  	CacheControl: anthropic.NewBetaCacheControlEphemeralParam(),
  	System: []anthropic.BetaTextBlockParam{
  		{Text: "You are a support agent for Acme. Keep replies short."},
  	},
  })

  // 第 1 輪：helper 建立一個 thread 並傳送完整對話
  _, err := thread.Send(ctx, anthropic.BetaMessageThreadSendParams{
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hi! I have a question about an order.")),
  	},
  })
  if err != nil {
  	panic(err)
  }

  // 第 2 輪：helper 延續該 thread，僅傳送新訊息
  second, err := thread.Send(ctx, anthropic.BetaMessageThreadSendParams{
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("How long does standard shipping usually take?")),
  	},
  })
  if err != nil {
  	panic(err)
  }

  for _, block := range second.Content {
  	if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
  		fmt.Println(textBlock.Text)
  	}
  }
  ```

  ```java Java
  var client = AnthropicOkHttpClient.fromEnv();

  // 建立 helper。此呼叫不會傳送任何請求。
  var thread = client.beta().messages().thread(
      ThreadCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024)
          .cacheControl(BetaCacheControlEphemeral.builder().build())
          .system("You are a support agent for Acme. Keep replies short.")
          .build()
  );

  // 第 1 輪：helper 建立一個 thread 並傳送完整對話
  thread.send("Hi! I have a question about an order.");

  // 第 2 輪：helper 延續該 thread，僅傳送新訊息
  var second = thread.send("How long does standard shipping usually take?");

  second.content().stream()
      .flatMap(block -> block.text().stream())
      .forEach(textBlock -> IO.println(textBlock.text()));
  ```

  ```php PHP
  $client = new Client();

  // 建立 helper。此呼叫不會傳送任何請求。
  $thread = $client->beta->messages->thread(
      maxTokens: 1024,
      model: Model::CLAUDE_OPUS_5_5,
      cacheControl: new BetaCacheControlEphemeral,
      system: 'You are a support agent for Acme. Keep replies short.',
  );

  // 第 1 輪：helper 建立一個 thread 並傳送完整對話
  $thread->send(['role' => 'user', 'content' => 'Hi! I have a question about an order.']);

  // 第 2 輪：helper 延續該 thread，僅傳送新訊息
  $second = $thread->send(['role' => 'user', 'content' => 'How long does standard shipping usually take?']);

  foreach ($second->content as $block) {
      if ($block instanceof BetaTextBlock) {
          echo $block->text, PHP_EOL;
      }
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  # 建立 helper。此呼叫不會傳送任何請求。
  thread = client.beta.messages.thread(
    model: :"claude-opus-5-5",
    max_tokens: 1024,
    cache_control: {type: "ephemeral"},
    system_: "You are a support agent for Acme. Keep replies short."
  )

  # 第 1 輪：helper 建立一個執行緒並傳送完整對話
  thread.send_message({role: "user", content: "Hi! I have a question about an order."})

  # 第 2 輪：helper 延續該執行緒，僅傳送新訊息
  second = thread.send_message({role: "user", content: "How long does standard shipping usually take?"})

  second.content.each do |block|
    puts block.text if block.type == :text
  end
  ```
</CodeGroup>

## 自行傳送 `thread` 欄位

若要自行建構訊息串請求，例如使用 cURL、CLI 或 SDK 一般的 `create` 方法，請在每個請求中加入 `thread` 欄位。

在訊息串的每個請求中傳送 `message-threads-2026-08-12` beta 標頭。

此範例在第一輪建立訊息串，並在第二輪繼續它。頂層的 `cache_control` 會要求在每一輪進行提示快取。一旦對話長度超過[最小可快取長度](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)，它就會生效。

<CodeGroup>
  ```bash cURL
  # 第 1 輪：傳送完整對話並建立 thread
  curl -sS --fail-with-body https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: message-threads-2026-08-12" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "cache_control": {"type": "ephemeral"},
      "system": "You are a support agent for Acme. Keep replies short.",
      "messages": [{"role": "user", "content": "Hi! I have a question about an order."}],
      "thread": {"type": "create"}
    }'

  # 第 2 輪：僅傳送新訊息。將 message_id 設為第 1 輪回應的 id。
  # 省略 system 與 tools：thread 會保留它們。
  curl -sS --fail-with-body https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: message-threads-2026-08-12" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "cache_control": {"type": "ephemeral"},
      "messages": [{"role": "user", "content": "How long does standard shipping usually take?"}],
      "thread": {"type": "continue", "previous_message_id": "'"$message_id"'"}
    }'
  ```

  ```bash CLI
  # 第 1 輪：傳送完整對話並建立 thread
  ant beta:messages create --beta message-threads-2026-08-12 <<'YAML'
  model: claude-opus-5-5
  max_tokens: 1024
  cache_control:
    type: ephemeral
  system: "You are a support agent for Acme. Keep replies short."
  messages:
    - role: user
      content: "Hi! I have a question about an order."
  thread:
    type: create
  YAML

  # 第 2 輪：僅傳送新訊息。將 message_id 設為第 1 輪回應的 id。
  # 省略 system 與 tools：thread 會保留它們。
  ant beta:messages create --beta message-threads-2026-08-12 <<YAML
  model: claude-opus-5-5
  max_tokens: 1024
  cache_control:
    type: ephemeral
  messages:
    - role: user
      content: "How long does standard shipping usually take?"
  thread:
    type: continue
    previous_message_id: $message_id
  YAML
  ```

  ```python Python
  client = anthropic.Anthropic()

  # 第 1 輪：傳送完整對話並建立 thread
  first = client.beta.messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      cache_control={"type": "ephemeral"},
      system="You are a support agent for Acme. Keep replies short.",
      messages=[{"role": "user", "content": "Hi! I have a question about an order."}],
      thread={"type": "create"},
      betas=["message-threads-2026-08-12"],
  )

  # 第 2 輪：僅傳送新訊息及第 1 輪回應的 id。
  # 省略 system 與 tools：thread 會保留它們。
  second = client.beta.messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      cache_control={"type": "ephemeral"},
      messages=[
          {"role": "user", "content": "How long does standard shipping usually take?"}
      ],
      thread={"type": "continue", "previous_message_id": first.id},
      betas=["message-threads-2026-08-12"],
  )

  for block in second.content:
      if block.type == "text":
          print(block.text)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  // 第 1 輪：傳送完整對話並建立 thread（討論串）
  const first = await client.beta.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    cache_control: { type: "ephemeral" },
    system: "You are a support agent for Acme. Keep replies short.",
    messages: [{ role: "user", content: "Hi! I have a question about an order." }],
    thread: { type: "create" },
    betas: ["message-threads-2026-08-12"]
  });

  // 第 2 輪：僅傳送新訊息及第 1 輪回應的 id。
  // 省略 system 與 tools：thread 會保留它們。
  const second = await client.beta.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    cache_control: { type: "ephemeral" },
    messages: [{ role: "user", content: "How long does standard shipping usually take?" }],
    thread: { type: "continue", previous_message_id: first.id },
    betas: ["message-threads-2026-08-12"]
  });

  for (const block of second.content) {
    if (block.type === "text") {
      console.log(block.text);
    }
  }
  ```

  ```csharp C#
  AnthropicClient client = new();

  // 第 1 輪：傳送完整對話並建立 thread（訊息串）
  var first = await client.Beta.Messages.Create(
      new()
      {
          Model = Messages::Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          CacheControl = new(),
          System = "You are a support agent for Acme. Keep replies short.",
          Messages =
          [
              new BetaUserMessageParam { Content = "Hi! I have a question about an order." },
          ],
          Thread = new BetaThreadCreateParams(),
          Betas = [AnthropicBeta.MessageThreads2026_08_12],
      }
  );

  // 第 2 輪：僅傳送新訊息及第 1 輪回應的 id。
  // 省略 System 與 Tools：thread 會保留它們。
  var second = await client.Beta.Messages.Create(
      new()
      {
          Model = Messages::Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          CacheControl = new(),
          Messages =
          [
              new BetaUserMessageParam { Content = "How long does standard shipping usually take?" },
          ],
          Thread = new BetaThreadContinueParams(first.ID),
          Betas = [AnthropicBeta.MessageThreads2026_08_12],
      }
  );

  foreach (var block in second.Content)
  {
      if (block.TryPickText(out var textBlock))
      {
          Console.WriteLine(textBlock.Text);
      }
  }
  ```

  ```go Go
  client := anthropic.NewClient()
  ctx := context.Background()

  // 第 1 輪：傳送完整對話並建立 thread
  threadCreate := anthropic.NewBetaThreadCreateParams()
  first, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
  	Model:        anthropic.ModelClaudeOpus5_5,
  	MaxTokens:    1024,
  	CacheControl: anthropic.NewBetaCacheControlEphemeralParam(),
  	System: []anthropic.BetaTextBlockParam{
  		{Text: "You are a support agent for Acme. Keep replies short."},
  	},
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hi! I have a question about an order.")),
  	},
  	Thread: anthropic.BetaMessageThreadParamUnion{OfCreate: &threadCreate},
  	Betas:  []anthropic.AnthropicBeta{anthropic.AnthropicBetaMessageThreads2026_08_12},
  })
  if err != nil {
  	panic(err)
  }

  // 第 2 輪：僅傳送新訊息及第 1 輪回應的 id。
  // 省略 System 與 Tools：thread 會保留它們。
  second, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
  	Model:        anthropic.ModelClaudeOpus5_5,
  	MaxTokens:    1024,
  	CacheControl: anthropic.NewBetaCacheControlEphemeralParam(),
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("How long does standard shipping usually take?")),
  	},
  	Thread: anthropic.BetaMessageThreadParamOfContinue(first.ID),
  	Betas:  []anthropic.AnthropicBeta{anthropic.AnthropicBetaMessageThreads2026_08_12},
  })
  if err != nil {
  	panic(err)
  }

  for _, block := range second.Content {
  	if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
  		fmt.Println(textBlock.Text)
  	}
  }
  ```

  ```java Java
  var client = AnthropicOkHttpClient.fromEnv();

  // 第 1 輪：傳送完整對話並建立 thread（討論串）
  var first = client.beta().messages().create(
      MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024)
          .cacheControl(BetaCacheControlEphemeral.builder().build())
          .system("You are a support agent for Acme. Keep replies short.")
          .addUserMessage("Hi! I have a question about an order.")
          .thread(BetaThreadCreateParams.builder().build())
          .addBeta(AnthropicBeta.MESSAGE_THREADS_2026_08_12)
          .build()
  );

  // 第 2 輪：僅傳送新訊息及第 1 輪回應的 id。
  // 省略 system 與 tools：thread 會保留它們。
  var second = client.beta().messages().create(
      MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024)
          .cacheControl(BetaCacheControlEphemeral.builder().build())
          .addUserMessage("How long does standard shipping usually take?")
          .continueThread(first.id())
          .addBeta(AnthropicBeta.MESSAGE_THREADS_2026_08_12)
          .build()
  );

  second.content().stream()
      .flatMap(block -> block.text().stream())
      .forEach(textBlock -> IO.println(textBlock.text()));
  ```

  ```php PHP
  $client = new Client();

  // 第 1 輪：傳送完整對話並建立 thread
  $first = $client->beta->messages->create(
      model: Model::CLAUDE_OPUS_5_5,
      maxTokens: 1024,
      cacheControl: new BetaCacheControlEphemeral,
      system: 'You are a support agent for Acme. Keep replies short.',
      messages: [
          ['role' => 'user', 'content' => 'Hi! I have a question about an order.'],
      ],
      thread: BetaThreadCreateParams::with(),
      betas: ['message-threads-2026-08-12'],
  );

  // 第 2 輪：僅傳送新訊息及第 1 輪回應的 id。
  // 省略 system 與 tools：thread 會保留它們。
  $second = $client->beta->messages->create(
      model: Model::CLAUDE_OPUS_5_5,
      maxTokens: 1024,
      cacheControl: new BetaCacheControlEphemeral,
      messages: [
          ['role' => 'user', 'content' => 'How long does standard shipping usually take?'],
      ],
      thread: BetaThreadContinueParams::with(previousMessageID: $first->id),
      betas: ['message-threads-2026-08-12'],
  );

  foreach ($second->content as $block) {
      if ($block instanceof BetaTextBlock) {
          echo $block->text, PHP_EOL;
      }
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  # 第 1 輪：傳送完整對話並建立討論串
  first = client.beta.messages.create(
    model: :"claude-opus-5-5",
    max_tokens: 1024,
    cache_control: {type: "ephemeral"},
    system_: "You are a support agent for Acme. Keep replies short.",
    messages: [{role: "user", content: "Hi! I have a question about an order."}],
    thread: {type: "create"},
    betas: ["message-threads-2026-08-12"]
  )

  # 第 2 輪：僅傳送新訊息及第 1 輪回應的 id。
  # 省略 system_ 和 tools：討論串會保留它們。
  second = client.beta.messages.create(
    model: :"claude-opus-5-5",
    max_tokens: 1024,
    cache_control: {type: "ephemeral"},
    messages: [{role: "user", content: "How long does standard shipping usually take?"}],
    thread: {type: "continue", previous_message_id: first.id},
    betas: ["message-threads-2026-08-12"]
  )

  second.content.each do |block|
    puts block.text if block.type == :text
  end
  ```
</CodeGroup>

## 每個請求要傳送的內容

| 群組   | 欄位                                                                                                                                                                     | 規則                                                                                          |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| 僅限建立 | `system`、`tools`                                                                                                                                                       | 僅在建立請求中傳送它們，連同其上的任何 `cache_control` 中斷點。在繼續請求中傳送其中任何一個（即使是 `null`）都會傳回 400 錯誤。              |
| 固定   | `model`、`tool_choice`、`thinking`、`mcp_servers`（每個伺服器的授權權杖除外）、`context_management`、`output_config`、`container` 中的 `skills`、頂層的 `cache_control`，以及 `anthropic-beta` 值的集合 | 在訊息串的每個請求中傳送它們，且值與建立請求中的相同。不同的值會傳回代碼為 `thread_fingerprint_mismatch` 的 400 錯誤，且錯誤訊息會指出不同的欄位。 |
| 自由   | `max_tokens`、`stop_sequences`、`stream`、`metadata`、`service_tier`，以及本頁未提及的其他欄位                                                                                          | 這些可以在每一輪之間變更。                                                                               |

API 不會儲存 MCP 伺服器 URL、MCP 授權權杖或容器 `id`。請在每個使用它們的請求中傳送 `mcp_servers` 和 `container`。MCP 授權權杖可以在請求之間變更。

SDK 訊息串輔助工具會為您在繼續請求中省略 `system` 和 `tools`，並在每一輪再次傳送固定欄位。

如果您使用[伺服器端備援](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback#server-side-fallback)，請在訊息串的每個請求中都傳送 `fallbacks` 欄位，或全都不傳送。請參閱[搭配訊息串使用備援](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#fallbacks)。

若要變更僅限建立或固定的欄位，請開始新的訊息串：在建立請求中以新的值傳送完整的對話。

在 Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5、Claude Sonnet 5.5 和 Claude Haiku 5.5 上，變更 `system` 或 `tools` 會使對話中已有的 `thinking` 和 `redacted_thinking` 區塊失效，且建立請求可能會傳回 400 錯誤。若要避免這種情況，請在您傳送的對話中省略所有 `thinking` 和 `redacted_thinking` 區塊。模型隨後會在沒有先前推理的情況下作答。請參閱[哪些變更算是編輯](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking#what-counts-as-an-edit)、[未設定 `prefix_mismatch_behavior` 時](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking#enforcement)和[API 如何處理無效區塊](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking#mismatch-behavior)。

在繼續請求中只傳送新的訊息。API 不會將它們與已有的訊息進行比對。您再次傳送的訊息可能會在對話中出現兩次，或者請求可能會傳回錯誤。例如，以前一個回應開頭的繼續請求會傳回錯誤。

新訊息通常以 `user` 訊息開頭：您的下一個使用者輪次，或回應上一個回應中 `tool_use` 的 `tool_result` 區塊。如果回應以 [`stop_reason: "pause_turn"`](https://platform.claude.com/docs/zh-TW/build-with-claude/handling-stop-reasons#pause-turn) 停止，請使用從該回應的 `id` 發出、且 `messages` 清單為空（`"messages": []`）的繼續請求來恢復它。如果該請求傳回 404 錯誤，請在新的建立請求中重播完整對話，包括已暫停的回應。在該輪暫停期間，請勿傳送新的 `user` 訊息：API 會拒絕它。使用 SDK 訊息串輔助工具時，請在不帶任何訊息的情況下呼叫 `send()` (go, csharp: `Send()`; ruby: `send_message()`)：輔助工具會傳送此請求，並在發生 404 錯誤時重播。

訊息串是僅能附加的，且每個回應 `id` 只能被繼續一次。請一律從訊息串的最新回應 `id` 繼續。若要編輯或分支較早的訊息，請使用建立請求開始新的訊息串。若要以摘要取代較早的輪次，請參閱[壓縮對話](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#compaction)。

## 訊息串上的提示快取

訊息串不會為您快取提示。[提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)的運作方式與沒有訊息串時相同：由您選擇快取中斷點的位置。

若要快取每一輪，請在訊息串的每個請求中傳送頂層的 `cache_control`，如前面的範例所示。API 會將其套用到每個請求 `messages` 中最後一個可快取的區塊。接著，每一輪都會從快取讀取較早的對話，並將新的一輪寫入快取。頂層的 `cache_control` 是固定欄位：請在每個請求中傳送相同的值。

您也可以自行在區塊上放置 `cache_control` 中斷點：

* 您在建立請求中傳送的中斷點，如果位於 `tools`、`system` 上，或位於最後一個訊息區塊之前的訊息區塊上，則在之後的每一輪中都會持續生效。位於請求 `messages` 最後一個區塊上的中斷點，會在該請求上寫入快取。若要快取每個新的輪次，請在每個請求上傳送中斷點。沒有中斷點的請求仍可能從快取中讀取部分對話。
* 中斷點傳送後便無法移動或移除，因為繼續請求無法再次傳送較早的訊息。
* 帶有 `thread` 的請求最多可攜帶 4 個 `cache_control` 中斷點。頂層的 `cache_control` 算作一個。建立請求中 `system` 和 `tools` 上的中斷點，在每次繼續請求時都會再次計入。較早已儲存訊息上的中斷點不計入。多出一個中斷點就會傳回代碼為 `thread_unsupported_request` 的 400 錯誤。
* 如果您自行在訊息區塊上放置中斷點，當您在新的建立請求中重播對話時，請將其從較早的訊息中移除，並在最後一個區塊上保留一個，讓請求維持在 4 個的限制之內。

## 串流

訊息串可搭配[串流](https://platform.claude.com/docs/zh-TW/build-with-claude/streaming)使用。回應 `id` 會在 `message_start` 事件中送達，但請在收到 `message_stop` 事件之後才從它繼續。較早送出的繼續請求可能會傳回 404 錯誤。

如果繼續請求的串流在 `message_stop` 之前中斷，請再次傳送相同的繼續請求。如果該請求傳回 `thread_already_continued` 或 `thread_continue_in_flight` 錯誤，請在新的建立請求中重播完整的對話。

您的連線可能在伺服器仍在生成回應時中斷，或在伺服器儲存回應之後中斷。這就是 API 可能拒絕重試的原因。重播永遠是安全的。

SDK 訊息串輔助工具在串流中斷後不會重試繼續請求。請參閱[SDK 輔助工具的運作方式](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#sdk-helper-handles)。

## 當訊息串無法繼續時進行復原

當 API 無法繼續訊息串時，繼續請求會傳回 404 錯誤，且 `error.details.error_code` 設為 `thread_not_found`。回應不會說明原因。原因包括以下幾種：

* 訊息串已過期。
* API 提供了前一輪，但沒有儲存它。例如，API 不會儲存以被 `max_tokens` 截斷的工具呼叫結尾的回應。
* 前一個回應是由備援模型撰寫的。請參閱[搭配訊息串使用備援](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#fallbacks)。
* 前一個回應仍在生成中。
* 請求來自不同的組織或工作區。
* 請求來自與建立訊息串者不同的使用者或服務帳戶。使用[工作區金鑰（舊版）](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#key-types)建立的訊息串會綁定該金鑰，因此請在整個訊息串中使用相同的金鑰。
* 新的訊息加入了已儲存的對話無法接受的內容。例如，在原本沒有圖片的對話中加入第一張圖片可能會傳回此錯誤。

若要復原，請從您自己的副本中，在新的建立請求中傳送完整對話，並附上 `system` 和 `tools`。SDK 訊息串輔助工具會自行傳送一次此建立請求，並在傳送時省略先前輪次的 `cache_control` 中斷點。如果您副本中的先前訊息帶有 `cache_control` 中斷點，請先將其移除（請參閱[訊息串上的提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#prompt-caching)）。然後從新回應的 `id` 繼續。如果先前的回應是由備援模型撰寫的，請參閱[搭配訊息串使用備援](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#fallbacks)。若要排除擁有權方面的原因，請對訊息串的每個請求使用相同的 API 金鑰和工作區。在 Claude Platform on AWS 上，請使用建立該訊息串的 IAM 角色或 IAM 使用者的憑證，為該訊息串的每個請求簽署。

對不存在之模型的請求也會傳回 404 錯誤，因此請在重播之前檢查 `error.details.error_code`。

如果在您重播後，繼續請求仍立即傳回 404 錯誤，API 可能無法儲存該對話，例如非常大的對話。請在不使用 `thread` 的情況下傳送。當您在建立 SDK 訊息串輔助工具時將 `unsupported_request_behavior` (typescript, java, php: `unsupportedRequestBehavior`; go, csharp: `UnsupportedRequestBehavior`) 設為 `continue_unthreaded` (ruby: `:continue_unthreaded`; java: `CONTINUE_UNTHREADED`; csharp: `ContinueUnthreaded`; go: `BetaMessageThreadUnsupportedRequestBehaviorContinueUnthreaded`) 時，它就會這麼做。否則它會在每一輪都進行重播。

### 拒絕之後

當回應帶有 `stop_reason: "refusal"` 時，請勿繼續該訊息串。API 可能已經保存了被拒絕的那一輪，而繼續請求無法將其移除。請使用省略或改寫導致拒絕之那一輪的建立請求來開始新的訊息串。請參閱[拒絕與備援](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback)。SDK 訊息串輔助工具會為您執行此操作：它不會保留被拒絕的那一輪，且其下一輪會開始新的訊息串。

### 搭配訊息串使用備援

[伺服器端備援](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback#server-side-fallback)可在 Claude API 上搭配訊息串使用。請在建立訊息串時決定：在訊息串的每個請求中都傳送 `fallbacks`，或全都不傳送。`fallbacks` 的值可以在請求之間變更。新增或移除 `fallbacks` 的繼續請求會傳回代碼為 `thread_fingerprint_mismatch` 的 400 錯誤。

訊息串只保留一個模型，因此 API 不會儲存由備援模型撰寫的輪次。您會照常收到回應，但無法從其 `id` 繼續。在每個回應之後，請遵循以下步驟：

1. 如果 `stop_reason` 為 `"refusal"`，請依照[拒絕之後](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#after-a-refusal)的說明進行。

2. 否則，請在 `usage.iterations` 中尋找 `fallback_message` 項目。在串流中，請從最後的 `message_delta` 事件讀取。如果沒有該項目，請照常繼續該訊息串。

3. 如果有，表示該回應是由備援模型撰寫的。請在新的建立請求中傳送完整對話，包括該回應以及您的下一則訊息。請在該請求上保留 `server-side-fallback-2026-07-01` beta 標頭。從以下兩種請求中擇一：

   * **再次傳送相同的請求。** 保持 `model`、`fallbacks` 及其他參數不變。如果由您請求的模型回答，API 會儲存新的訊息串。如果由備援模型回答，回應中會再次出現 `fallback_message` 項目，且 API 不會儲存它，因此請在下一輪重複此步驟。[黏性路由](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback#sticky-routing)可能會將這些請求直接傳送至備援模型，因此每一輪都可能需要傳送完整對話。SDK 訊息串輔助工具即以此方式運作。
   * **在備援模型上開始新的訊息串。** 將 `model` 設為該 `fallback_message` 項目中的 `model`，省略 `fallbacks`，並使用此模型接受的參數。API 會立即儲存此訊息串，且它會持續使用備援模型。備援嘗試執行時所用的設定可能與您傳送的不同，因此 API 可能會拒絕從您第一個請求複製過來的值。

4. 使用該請求的回應回到步驟 1。當回應沒有 `fallback_message` 項目時，從其 `id` 繼續新的訊息串。

[黏性路由](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback#sticky-routing)會在請求發生備援後開始（建立請求，或不含 `thread` 的請求）。在大約一小時內，它可能會將同一對話中後續包含 `fallbacks` 的建立請求直接傳送至備援模型，而不嘗試您請求的模型。API 不會儲存這些輪次中的任何一輪，且每一輪獲得回答都會重新開始計算這一小時。繼續請求永遠不會啟動此路由，也永遠不會使用它。如果您的組織或工作區使用零資料保留或客戶管理的加密金鑰，則黏性路由不適用。

## 壓縮對話

訊息串是僅能附加的，因此您無法以摘要取代其較早的輪次。若要壓縮對話，請從摘要開始新的訊息串。請在您的程式碼中撰寫摘要，並在新的建立請求中將其作為一般訊息傳送，連同 `system` 和 `tools`。[隨需壓縮](https://platform.claude.com/docs/zh-TW/build-with-claude/compaction-on-demand)無法搭配訊息串使用（請參閱[訊息串不支援的功能](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#unsupported)）。

## SDK 輔助工具的運作方式

輔助工具為您做的事：

* 在每個使用該訊息串的請求中加入 `message-threads-2026-08-12` beta 標頭。
* 在第一輪建立訊息串，之後繼續該訊息串，只傳送新訊息，並省略 `system` 和 `tools`。
* 當繼續請求傳回 `thread_not_found`、`thread_already_continued` 或 `thread_continue_in_flight` 時，在新的建立請求中重播一次完整對話。
* 當您不帶任何訊息呼叫 `send()` (go, csharp: `Send()`; ruby: `send_message()`) 時，恢復 `pause_turn` 回應。
* 在拒絕之後開始新的訊息串。您會照常收到 `stop_reason: "refusal"` 回應，但輔助工具不會保留該輪：它會收回您提供給該次呼叫的訊息。您透過 `thread.append(...)` (csharp, go: `thread.Append(...)`; php: `$thread->append(...)`) 加入的訊息，或在建立輔助工具時提供的訊息，會保持暫存狀態。您的下一輪會在新的建立請求中，將它們連同被拒絕那一輪之前的對話一起傳送。請傳送改寫過的訊息；或者，如果是某則暫存訊息導致了拒絕，請從不含該訊息的 params 開始新的訊息串。
* 在收到來自備援模型的回應後傳送新的建立請求。當回應在 `usage.iterations` 中有 `fallback_message` 項目時，輔助工具會保留該回應，並在下一輪於新的建立請求中傳送完整對話。它不會等待 404 錯誤。該請求會保留您設定的 `model` 和 `fallbacks`。
* 每當再次傳送先前各輪時（例如在重播中或在分支的第一輪中），省略其 `cache_control` 中斷點。您最新的訊息、`system`、`tools` 以及頂層的 `cache_control` 會依您提供的內容送出。

您需要自行處理的事：

* **備援。** 當 API 持續由備援模型回答時，輔助工具會在每一輪都於新的建立請求中傳送完整對話，因為 API 不會儲存這些輪次中的任何一輪。在收到您所請求模型的回應後，它會回到使用繼續請求。若要改為將對話移至備援模型，請從 params 開始一個新的訊息串，使用該 `model` 且不含 `fallbacks`，如[搭配訊息串使用備援](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#fallbacks)中所述。
* **中斷的串流。** 如果串流在回應途中結束，輔助工具會保留已完成的區塊以及任何已抵達的文字，而下一輪會在新的建立請求中傳送完整對話。輔助工具不會自行重試：若要改為重新傳送被中斷的那一輪，請不帶任何訊息呼叫 `send()` (go, csharp: `Send()`; ruby: `send_message()`)。如果保留的部分以工具呼叫結尾，請在您的下一則訊息中回應它們。如果您在串流顯示 `stop_reason: "refusal"` 之後停止讀取，輔助工具會將該輪視為拒絕。
* **其他錯誤。** `thread_fingerprint_mismatch` 和 `thread_unsupported_request` 錯誤會傳遞到您的程式碼。若要在發生 `thread_unsupported_request` 錯誤後不使用 `thread` 繼續進行，請在建立輔助工具時將 `unsupported_request_behavior` (typescript, java, php: `unsupportedRequestBehavior`; go, csharp: `UnsupportedRequestBehavior`) 設為 `continue_unthreaded` (ruby: `:continue_unthreaded`; java: `CONTINUE_UNTHREADED`; csharp: `ContinueUnthreaded`; go: `BetaMessageThreadUnsupportedRequestBehaviorContinueUnthreaded`)。使用該設定時，若重播後的第一個繼續請求再次傳回 `thread_not_found`，輔助工具也會停止使用 `thread`。API 可能無法儲存該對話。若未使用該設定，輔助工具會在每一輪都進行重播。自行建立訊息串的工具執行器預設會使用該設定。

SDK 的 beta 工具執行器預設也會使用訊息串，您可以在建立執行器時將其關閉。

### 其他輔助方法

| 若要執行此操作          | 請使用                                                                                                                                                                                                                                                                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 串流一輪對話           | `thread.stream(...)` (csharp: `thread.SendStreaming(...)`; go: `thread.SendStreaming(ctx, params)`; java: `thread.sendStreaming(...)`; php: `$thread->sendStream(...)`)                                                                                                                                                              |
| 串流輪次的完成回應        | `stream.get_final_message()` (typescript: `stream.finalMessage()`; csharp: `thread.LastMessage`; go: `thread.LastMessage()`; java: `thread.lastMessage()`; php: `$thread->lastMessage()`; ruby: `stream.accumulated_message`)                                                                                                        |
| 完整對話             | `thread.messages` (csharp: `thread.Messages`; go: `thread.Messages()`; java: `thread.messages()`; php: `$thread->messages()`)                                                                                                                                                                                                        |
| 下一輪要從其繼續的回應 `id` | `thread.previous_message_id` (typescript: `thread.previousMessageId`; csharp: `thread.PreviousMessageID`; go: `thread.PreviousMessageID()`; java: `thread.previousMessageId()`; php: `$thread->previousMessageId()`)                                                                                                                 |
| 新增訊息但不傳送         | `thread.append(...)` (csharp, go: `thread.Append(...)`; php: `$thread->append(...)`)                                                                                                                                                                                                                                                 |
| 變更後續輪次的欄位        | `thread.update(...)` (csharp: `thread.Update(p => p with { ... })`; go: `thread.Params.MaxTokens = ...`; java: `thread.update(b -> ...)`; php: `$thread->update([...])`)                                                                                                                                                             |
| 複製訊息串            | `thread.fork()` (csharp, go: `thread.Fork()`; php: `$thread->fork()`; ruby: `thread.fork`)                                                                                                                                                                                                                                           |
| 用於開始新訊息串的欄位與對話   | `thread.params` (csharp, go: `thread.Params`; java: `thread.params()`; php: `$thread->params()`)                                                                                                                                                                                                                                     |
| 此訊息串上的工具執行器      | `thread.tool_runner()` (typescript, java: `thread.toolRunner()`; csharp: `thread.ToolRunner(tools)`; go: `thread.NewToolRunner(tools)`; php: `$thread->toolRunner()`; ruby: `thread.tool_runner`)                                                                                                                                    |
| 不使用訊息串的工具執行器     | `tool_runner(..., thread=False)` (typescript: `toolRunner({ ..., thread: false })`; csharp: `ToolRunner(parameters, tools, thread: false)`; go: `BetaToolRunnerParams{DisableThread: true}`; java: `ToolRunnerCreateParams.builder().thread(false)`; php: `toolRunner(..., thread: false)`; ruby: `tool_runner(..., thread: false)`) |

**串流。** 輔助工具會在串流到達 `message_stop` 時記錄回應，因此請將串流讀取到結尾。如果您提早停止讀取，請結束串流，讓訊息串可供下一輪使用：

* Python：離開 `with` 區塊。
* TypeScript：離開迴圈或呼叫 `abort()`。
* Go：呼叫 `Close`。
* Java 和 Ruby：呼叫 `close()`。
* C#：處置列舉器。離開 `await foreach` 即會執行此操作。
* PHP：呼叫 `close()`。

在 C# 中，請求會在您開始讀取串流時送出。

在 C#、Go、Java 和 PHP 中，發生拒絕後，`thread.LastMessage` (go: `thread.LastMessage()`; java: `thread.lastMessage()`; php: `$thread->lastMessage()`) 仍會傳回上一輪的回應，若是第一輪則不傳回任何內容。請從串流的事件中讀取拒絕。

**變更欄位。** 更新不會傳送任何內容，並會套用到之後的每一輪。一旦訊息串有了回應，輔助工具就會拒絕變更 `system` 或 `tools` 的輪次，而 API 會拒絕對任何其他固定欄位的變更（請參閱[每個請求要傳送的內容](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#what-to-send)）。若要變更這些欄位之一，請從 params 開始新的訊息串，或分叉訊息串並在分叉的第一輪之前更新它。

**分叉。** 分叉會複製對話、欄位和請求選項，且不會傳送任何內容。它的第一輪會在新的建立請求中傳送完整的對話，之後兩個訊息串便彼此獨立。分叉一律從整個對話開始，而不是從較早的回應開始。

**Params。** params 包含輔助工具的欄位以及完整對話。將它們傳遞給建立輔助工具的方法即可開始新的訊息串，例如使用不同的 `system`（請參閱[每個請求要傳送的內容](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#what-to-send)），或將 `messages` 截短以捨棄後續輪次。從 params 開始的訊息串會依您提供的方式傳送每則訊息，包括 `cache_control` 中斷點，因此請保持在 4 個的上限之內（請參閱[訊息串上的提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#prompt-caching)）。除了 Ruby 之外，params 不包含請求選項，因此請再次傳遞這些選項。

**結構化輸出。** 請在建立輔助工具時提供輸出格式。後續輪次無法變更它。取得解析結果的方式取決於 SDK：

* Python 和 TypeScript：呼叫 `thread.parse(...)`。
* C#：使用 `client.Beta.Messages.Thread<T>(...)` 建立輔助工具。
* Go：`Send` 會反序列化至 `Params.OutputConfig.Format.Schema` 所指向的結構。
* Java：使用 `thread(...)` 和 `outputConfig(MyClass.class)` 建立輔助工具。
* PHP：當 `outputConfig` 指定模型類別時，`send()` 會在文字區塊上設定 `parsed`。
* Ruby：將 `output_config: {format: MyModel}` 傳遞給 `thread(...)`，然後讀取 `reply.parsed_output`。

## 錯誤

API 會在模型執行之前傳回此表中的錯誤。請求不會使用任何權杖，且訊息串及其到期時間不會改變。400 錯誤的 `error.type` 為 `invalid_request_error`，404 錯誤的則為 `not_found_error`。

| 狀態  | `error_code`                  | 意義                                                         | 處理方式                                  |
| --- | ----------------------------- | ---------------------------------------------------------- | ------------------------------------- |
| 404 | `thread_not_found`            | API 無法繼續訊息串。                                               | 在新的建立請求中傳送完整的對話。                      |
| 400 | `thread_fingerprint_mismatch` | 某個固定欄位與訊息串所儲存的值不同。錯誤訊息會指出這些欄位。                             | 保持固定欄位不變，或開始新的訊息串以變更欄位。               |
| 400 | `thread_already_continued`    | 每個回應 `id` 只能被繼續一次。                                         | 從訊息串的最新回應 `id` 繼續。如果您的用戶端從未收到該回應，請重播。 |
| 400 | `thread_continue_in_flight`   | 從此回應 `id` 發出的另一個繼續請求仍在執行中。這通常是您自己較早的嘗試。                    | 讓它完成並從其回應 `id` 繼續，或重播。                |
| 400 | `thread_unsupported_request`  | 請求使用了訊息串不支援的功能或組織設定。若有提供，`error.details.unsupported` 會指出它。 | 從請求中移除該功能，或在不使用 `thread` 的情況下傳送完整的對話。 |

某些訊息串請求的 400 錯誤不帶有 `error_code`，例如沒有 `previous_message_id` 的繼續請求，或包含 `system` 或 `tools` 的繼續請求。

以下範例顯示錯誤主體：

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "thread: a maximum of 4 blocks with cache_control may be provided when `thread` is set. Found 5.",
    "details": {
      "error_code": "thread_unsupported_request",
      "unsupported": ["cache_control"]
    }
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}
```

## 訊息串不支援的功能

訊息串不支援以下功能：

* [Message Batches](https://platform.claude.com/docs/zh-TW/build-with-claude/batch-processing)。包含 `thread` 的請求項目會在批次結果中以 `invalid_request_error` 結束。
* [權杖計數](https://platform.claude.com/docs/zh-TW/build-with-claude/token-counting)。包含 `thread` 的權杖計數請求會傳回 400 錯誤。請改為計算完整的對話，連同 `system` 和 `tools`。
* [壓縮](https://platform.claude.com/docs/zh-TW/build-with-claude/compaction)。[隨需壓縮](https://platform.claude.com/docs/zh-TW/build-with-claude/compaction-on-demand)無法搭配訊息串使用。包含 `thread` 的請求如果設定了 `compaction` 參數，或搭配 `compact-2026-09-04` beta 標頭傳送 `compaction` 區塊，就會傳回 400 錯誤。請參閱[壓縮對話](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#compaction)。
* [上下文編輯](https://platform.claude.com/docs/zh-TW/build-with-claude/context-editing)，但搭配 `keep: "all"` 的 `clear_thinking_20251015` 除外。
* 已啟用 [HIPAA 就緒](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention#hipaa-readiness)的組織。
* 已開啟[推論掛鉤](https://platform.claude.com/docs/zh-TW/manage-claude/inference-hooks)的組織。

API 會以 400 錯誤和代碼 `thread_unsupported_request` 拒絕大多數訊息串不支援的請求。當 `error.details.unsupported` 存在時，它會包含以下其中一個值：

| 值                    | 意義                                                                                                                                     |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `context_management` | 請求使用了訊息串不支援的上下文管理或壓縮。                                                                                                                  |
| `cache_control`      | 請求有超過 4 個 `cache_control` 中斷點。請參閱[訊息串上的提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#prompt-caching)。 |
| `fallbacks`          | 請求設定了 `fallbacks`，而您的組織無法搭配訊息串使用 `fallbacks`。                                                                                          |
| `hipaa`              | 您的組織已啟用 HIPAA 就緒。                                                                                                                      |
| `inference_hooks`    | 您的組織已開啟推論掛鉤。                                                                                                                           |

API 可能會在此清單中新增值。如果您收到無法辨識的值，請在不使用 `thread` 的情況下傳送完整的對話。符合其中多個條件的請求所收到的錯誤只會指出其中一個。

## 限制

* 沒有用於列出、讀取或刪除訊息串的 API。
* 訊息串可在 Claude API、[Claude Platform on AWS](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws)、 Claude Models on Google Cloud (Anthropic managed)、以及 [Claude in Microsoft Foundry](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-microsoft-foundry) 上使用。

## 定價與速率限制

訊息串不會改變定價或[速率限制](https://platform.claude.com/docs/zh-TW/api/rate-limits)。

## 資料保留

訊息串不符合 ZDR 資格。使用此功能不會影響您使用其他符合 ZDR 資格的功能。API 會將訊息串保存在記憶體中，並以伺服器管理的金鑰加密，絕不會將其寫入持久性儲存空間，且會在最後一次使用後不超過 1 小時內將其刪除。

訊息串保存 API 傳送給模型的對話、建立請求中的 `system` 和 `tools`，以及固定欄位的指紋，用於檢查之後的請求。它以參照方式保存檔案，因此在您使用訊息串期間，請讓對話所使用的每個檔案保持可用。

如需所有功能的 ZDR 資格，請參閱 [API 與資料保留](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention)。

## 另請參閱

* [提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)
* [串流](https://platform.claude.com/docs/zh-TW/build-with-claude/streaming)
* [錯誤](https://platform.claude.com/docs/zh-TW/api/errors)

## 可用性

訊息串在所有模型上處於 Beta 階段。

### API 支援

#### [Messages API](https://platform.claude.com/docs/zh-TW/build-with-claude/working-with-messages)

* 可用性：可用

| 狀態   | 雲端平台                                                                                                                                                                                                                                                                                                                                                                                            |
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Beta | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-microsoft-foundry) |

### 必要的 Beta 標頭

[Beta 標頭概覽](https://platform.claude.com/docs/zh-TW/api/beta-headers)

Beta 標頭可讓您在實驗性功能與新模型能力成為標準 API 的一部分之前搶先存取。

* `message-threads-2026-08-12`

### 資料處理

[資料處理概覽](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention#feature-eligibility)

| 項目   | 零資料保留                                                                                                                                                                                                | HIPAA |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| 狀態   | 不符合資格                                                                                                                                                                                                | 不符合資格 |
| 詳細資訊 | 訊息串的內容（對話、系統提示與工具）會保存在記憶體中，以伺服器管理的金鑰加密，絕不寫入持久性儲存空間，並在訊息串最後一次使用後 1 小時內刪除。使用此功能不會影響您使用其他具 ZDR 適用資格的功能。 [深入了解](https://platform.claude.com/docs/zh-TW/build-with-claude/message-threads#data-retention) | —     |

適用端點：

* `/v1/messages` 搭配 `thread`