# 用 SosoAPI 排程 Threads 文字同圖片帖子

Canonical URL: https://sosoapi.ai/zh-hant/docs/threads-api-publishing

由一個已審閱 Threads 帖子同一個確實已連接帳戶開始。呢個示例經 canonical Scheduled Posts 流程處理文字同已就緒圖片。Contract 已於 2026 年 10 月 20 日核對；示例包含 placeholders。

## 1. 連接同檢查目的帳戶

喺 SosoAPI 連接所需 Threads 帳戶。平台授權要有 threads_content_publish 先可以發佈。SosoAPI 呼叫者亦需要獲允許嘅 Workspace、editor 角色同 agent:publish capability 先可以排程。

寫入前讀取確實帳戶身份。用完整草稿 eligibility 檢查帳戶、內容同時間。回覆、位置或跨平台分享等額外功能，各有權限同資格要求。

- [查看平台功能對照](https://sosoapi.ai/zh-hant/docs/publishing-capabilities)

## 2. 排程一個已審閱文字帖子

先用 API 參考嘅伺服器 helper。換走所有 placeholders，再選擇帶 offset 嘅未來 ISO-8601 時間。只有執行請求先會建立真實排程；執行前確認目的帳戶、文案同時間。

TEXT 毋須媒體。同一意圖保留一個 idempotency key，存低回傳 post.id，並顯示實際狀態。唔可以將另一平台嘅 provider_payload 配上呢個帳戶。

```
await sosoPost("/studio-api/scheduled-posts/create", {
  "workspace_id": "<workspace-uuid>",
  "social_account_id": "<threads-account-uuid>",
  "caption": "A reviewed update from our team.",
  "hashtags": [],
  "media": [],
  "provider_payload": {
    "platform": "threads",
    "publish_options": {
      "post_type": "TEXT"
    }
  },
  "scheduled_at": "<future-ISO-8601-instant-with-offset>",
  "display_timezone": "Asia/Hong_Kong",
  "idempotency_key": "<stable-key-for-this-one-intent>"
});
```

- [Publishing API 參考](https://sosoapi.ai/zh-hant/docs/publishing-api-reference)

## 3. 使用已就緒登記圖片

用 sosoapi_upload_asset 上載檔案，或者用 sosoapi_import_asset_url 匯入公開圖片 URL，再讀取 sosoapi_get_asset_import_status。等到就緒後，用已登記 asset 嘅 identity 同 canonical URL。

一般 create 請求將 post_type 改為 IMAGE，並喺 media 提供已就緒圖片。以下片段取代文字示例嘅呢兩個欄位。保留文案、帳戶同排程，並為新確認意圖使用新嘅穩定 key。

- asset_id 要換成實際正整數，唔係數字字串。

- 唔好用 source URL、臨時 preview URL 或未完成匯入嘅媒體排程。

- 重用 library 圖片前，要確認使用權、Workspace 同所選內容都合適。

```
{
  "media": [{
    "kind": "image",
    "asset_id": "<ready-image-asset-id-as-number>",
    "url": "<canonical-image-asset-url>"
  }],
  "provider_payload": {
    "platform": "threads",
    "publish_options": {"post_type": "IMAGE"}
  }
}
```

## 4. 核實發佈同避免重複發送

讀取原有 Scheduled Post。回傳 ID、接受排程或建立 Threads media container，都唔係已發佈證據。要檢查最終 publish outcome 同可用平台 ID／permalink。

Threads 仲處理緊或回應未確認時，繼續跟進同一帖子。收唔到回應唔可以用另一個 key 再 create。重新連接帳戶亦唔會證明未確認寫入已失敗。

Threads 文字發佈可能包含不可逆嘅平台步驟。要跟伺服器允許嘅操作同 reconciliation；失敗或延遲觀察唔代表可以重發。呢度冇固定發帖速度保證。

- [用 Claude Code 或 Codex 審閱](https://sosoapi.ai/zh-hant/docs/claude-code-codex-social-publishing)

- [Publishing API 參考](https://sosoapi.ai/zh-hant/docs/publishing-api-reference)