> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Threads API

> 使用 Threads API 發布內容的選項

<Info>
  Threads 發布時，Meta 會透過其伺服器端的爬蟲從你的 URL 擷取媒體。
  如果你看到 Ayrshare 錯誤代碼 379 — 特別是在同一次發布中同時出現 Instagram 錯誤 440 或 138 — 請參閱 [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked)。
</Info>

## 發布到 Threads

使用 Threads API 發布含連結與圖片的基本貼文，JSON 範例：

```json Threads Post theme={"system"}
{
  "post": "The best Threads post ever #best #awesome https://www.threads.net", // empty string is allowed
  "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  "platforms": ["threads"]
}
```

Threads API 有以下需求與限制：

<ul class="custom-bullets">
  <li>
    除非貼文中已包含圖片或影片，否則 Threads 會自動預覽貼文中的連結。
    上述範例會顯示圖片，若移除圖片，就會改為顯示連結預覽。
  </li>

  <li>Threads 個人檔案在任何連續 24 小時內，最多可透過 API 發布 250 則貼文。</li>
  <li>Threads 每則貼文只允許 1 個 hashtag。</li>
  <li>被 @提及的 Threads 使用者會收到通知。</li>
  <li>貼文最多 500 個字元。</li>

  <li>
    支援多圖/多影片貼文，會以輪播形式發布。單一貼文最多可包含 20 個
    影片與圖片。
  </li>

  <li>
    Threads 不支援透過 API 刪除貼文。刪除必須在 Threads App 內手動操作。
  </li>

  <li>
    如果你的影片副檔名不是常見的影片格式（例如 mp4），請使用 `isVideo`
    參數。詳情請參閱 [/post 端點](/apis/post/post)。
  </li>

  <li>
    Threads 也支援發送不含貼文文字的媒體。如果你不想包含貼文文字，
    請傳送空字串 `post: ""`。
  </li>

  <li>
    更多資訊請參閱 [Threads 媒體指南](/media-guidelines/threads) 與 [Threads
    授權](/dashboard/connect-social-accounts/threads)。
  </li>
</ul>

## Threads 選項

你可以透過 `threadsOptions` 參數為貼文設定額外的選項。

```json Threads Options theme={"system"}
{
  "threadsOptions": {
    "allowCountries": ["US", "CA"],
    "thread": true,
    "threadNumber": true,
    "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"] // used when sending as a thread of threads
  }
}
```

Threads 選項為可選欄位，用來控制貼文的呈現方式。

<ParamField body="allowCountries" type="array of strings">
  使用國家代碼將貼文限制在特定國家可見。可用的[國家代碼](/iso-codes/country)。

  僅在 Meta 為你的帳號啟用地區限制時可用。

  更多資訊請參閱 [Threads 地區限制](/apis/post/social-networks/threads#geo-restrictions)。
</ParamField>

<ParamField body="thread" type="boolean" default={false}>
  將長貼文拆分成一系列連貫的串接貼文（thread），並可選擇加入編號與媒體。

  更多資訊請參閱 [Thread](/apis/post/social-networks/threads#thread)。
</ParamField>

<ParamField body="threadNumber" type="boolean" default={false}>
  自動在每則 thread 末尾加上 1/n 格式的編號。

  需要 `thread: true`。
</ParamField>

<ParamField body="mediaUrls" type="array of strings">
  為 thread 系列的每則貼文加入媒體物件。每則 thread 會依序加上一個媒體物件。

  若要跳過某則 thread 的媒體，請使用 `null`。若要為單一 thread 加入多個媒體，請使用包含多個 URL 的物件。

  更多資訊請參閱 [Thread 媒體](/apis/post/social-networks/threads#thread-media)。
</ParamField>

## 在 Threads 貼文中加入換行或 rich text

Threads 貼文中的換行可以使用特殊的[換行字元](/apis/post/post#line-breaks)加入。

Rich text（例如粗體或斜體）可以透過幾個 [HTML 元素](/apis/post/overview#rich-text-posts) 加到 Threads 貼文中。

## 圖片與影片的輪播

你可以將多張圖片或影片以輪播形式發布到 Threads；單一輪播中最多可包含 20 個圖片或影片。只要在 `mediaUrls` 陣列中加入更多圖片或影片，系統就會自動建立輪播。

```json theme={"system"}
"mediaUrls": ["https://url.com/image.jpg", "https://url.com/video.mp4" ...];  // Max 20 images or videos
```

影片 URL 必須以已知的副檔名（例如 mp4）結尾。

## 字元限制

更多資訊請參閱 [Threads 字元限制](/help-center/technical-support/character_limits#threads-character-limits)。

## 地區限制

你可以透過 `allowCountries` 陣列將貼文限制在特定國家可見。

```json theme={"system"}
{
  "threadsOptions": {
    "allowCountries": ["US", "CA"]
  }
}
```

<ul class="custom-bullets">
  <li>
    `allowCountries`：允許存取的國家代碼陣列。可用的[國家代碼](/iso-codes/country)。
  </li>
</ul>

<Warning>
  Threads 上的地區限制（geo-gating）只有在 Meta 為你的帳號啟用此功能時才可用。

  Meta 會依帳號驗證狀態、粉絲數或創作者身分等因素，決定哪些 Threads 帳號有資格使用地區限制。
  如果你的帳號有此資格，在建立新的 Threads 貼文時，發文編輯器中會出現地區設定（地球圖示）。

  你可以透過 [/user](/apis/user/profile-details) 端點的 `isEligibleForGeoRestrictions` 屬性檢查某個 User Profile 是否有資格使用 Threads 地區限制。
</Warning>

## Threads 提及

在貼文文字中加入 @handle 即可提及其他 Threads 使用者。例如：

```json theme={"system"}
{
  "post": "The best social media API @Ayrshare ever!",
  "mediaUrls": ["https://images.com"],
  "platforms": ["threads"]
}
```

<Warning>
  被 @提及的使用者會收到通知。請詳閱關於提及功能的[重要規則](/testing/post-verification#mentions)。
</Warning>

如果配額已達上限，會回傳錯誤訊息。

## Thread

Threads thread（又稱為 threadstorm）是 Threads 上一系列相互連接的貼文，讓你能突破單一貼文的字元限制、分享更長的內容，並在檢視時呈現為一個連續的敘事。

### 發布 Thread

Threads thread 可以透過 API 發布。thread 是被拆分成多則相互回覆並在 Threads 上關聯在一起的一組貼文。你可以讓系統自動拆分貼文，或是在貼文文字中指定 [thread 分隔](/apis/post/social-networks/threads#thread-breaks)。

```json Threads Thread theme={"system"}
{
  "threadsOptions": {
    "thread": true,        // required for threadstorm
    "threadNumber": true,  // optional to add numbers to each thread
    "mediaUrls": ["https://site.com/image1.png", "https://site.com/image2.png", ...]  // optional one media object is added to a thread in order
  }
}
```

<ul class="custom-bullets">
  <li>
    `thread: true`：依換行符號自動將貼文文字拆分成多則 thread。
  </li>

  <li>
    `threadNumber: true`：自動在每則 thread 末尾以 1/n 格式加上編號。
    例如，第 2 則（共 5 則）thread 末尾會附加 2/5。
  </li>

  <li>
    `mediaUrls: [array of urls]`：依序將每個媒體物件（圖片或影片）加到對應的 thread 上。
    每則 thread 依序只會加上一個媒體物件。
  </li>
</ul>

#### Thread 媒體

##### 跳過媒體

在陣列中使用 `null` 即可跳過某則 thread 的媒體。例如：

`["https://site.com/image1.png", null, "https://site.com/image2.png"]`

這會將 image1 放在第一則貼文、第二則貼文無圖片，image2 放在第三則貼文。

##### 多個媒體

在 `mediaUrls` 陣列中加入包含多個媒體 URL 的物件 `{}`，即可為 thread 中的單一貼文加入多個媒體物件。可使用任何唯一的物件 key。例如：

```json Threads Thread with Multiple Media URLs theme={"system"}
{
  "threadsOptions": {
    "thread": true,
    "threadNumber": true,
    "mediaUrls": [
      "https://img.ayrshare.com/random/photo-1.jpg",
      {
        "1": "https://img.ayrshare.com/random/photo-2.jpg",
        "2": "https://img.ayrshare.com/random/photo-3.jpg"
      },
      "https://img.ayrshare.com/random/photo-4.jpg"
    ]
  }
}
```

在此範例中，第一則貼文會包含 photo-1.jpg，第二則貼文會包含 photo-2.jpg 與 photo-3.jpg，第三則貼文則會包含 photo-4.jpg。

#### Thread 分隔

Ayrshare 會自動將貼文文字拆分成適合 Threads 長度（超過 500 個字元）的貼文。在建立 thread 時，我們會盡可能將完整的句子保留在同一則貼文中。如果單一句子放不下，就會在句子之間分隔；若句子非常長，就會在字詞之間分隔；極少數情況下，如果單一字詞過長，我們才會將該字詞本身拆開。

你也可以在貼文文字中手動加入段落 `\n\n` 來指定要建立一則新的 thread。如果貼文文字中含有 `\n\n`，我們就不會再自動將貼文拆分成 thread。

例如：

```json Example Threads Thread theme={"system"}
{
  "post": "This is post 1\n\nThis is post 2.",
  "platforms": ["threads"],
  "threadsOptions": {
    "thread": true
  }
}
```

會在該 thread 中產生兩則貼文。

若你想加入段落但不拆成不同的貼文，請使用 `\u2063\n\u2063\n`。

```json Threads Thread with Paragraphs theme={"system"}
{
  "post": "This is paragraph 1\u2063\n\u2063\nThis is paragraph 2.",
  "platforms": ["threads"],
  "threadsOptions": {
    "thread": true
  }
}
```

由於該貼文低於 500 個字元，因此會產生單一貼文並包含兩個段落。

### 刪除 Thread

Threads 不支援透過 API 刪除貼文。刪除必須在 Threads App 內手動操作。