內容 API

內容 API 提供建立、排程、檢查與取消社群媒體發佈作業，以及上傳媒體所需的端點。

---

📌 端點

方法	路徑	說明	必要權限範圍
POST	/v1/brand/contents/uploads	為圖片和影片上傳生成預簽署的 PUT URL	publishing:create 或 *
POST	/v1/brand/contents	提交立即或排程貼文 (202 Accepted)	publishing:create 或 *
GET	/v1/brand/contents	列出品牌內容，並提供分頁和狀態篩選	publishing:read 或 *
GET	/v1/brand/contents/{content_id}	檢索內容詳細資訊和發布作業結果	publishing:read 或 *
DELETE	/v1/brand/contents/{content_id}/cancel	在處理開始前取消排程貼文	publishing:delete 或 *

---

1. 媒體上傳預簽署 URL (POST /v1/brand/contents/uploads)

若要在貼文中附加媒體，請先取得預先簽署的上傳 URL，再透過 HTTP PUT 將二進位檔案直接上傳到 S3/R2 儲存空間。

支援的媒體格式

• 圖片 (最大 20MB，URL 有效期 300 秒): image/jpeg、image/png、image/webp、image/gif
• 影片 (最大 500MB，URL 有效期 600 秒): video/mp4、video/quicktime (.mov)、video/webm

請求範例

curl -X POST "https://api.ankk.app/v1/brand/contents/uploads" \
  -H "Authorization: Bearer spk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "launch-banner.png",
    "content_type": "image/png",
    "size": 1420500
  }'

回應範例 (200 OK)

{
  "upload_url": "https://storage.ankk.app/sns-posts/original/brand_.../launch-banner.png?X-Amz-Signature=...",
  "asset_ref": "https://cdn.ankk.app/sns-posts/original/brand_.../launch-banner.png",
  "method": "PUT",
  "object_key": "sns-posts/original/brand_.../launch-banner.png",
  "content_type": "image/png",
  "size": 1420500,
  "expires_in_seconds": 300
}

透過 PUT 上傳二進位檔案

curl -X PUT "<upload_url>" \
  -H "Content-Type: image/png" \
  --data-binary "@/path/to/launch-banner.png"

---

2. 發佈內容 (POST /v1/brand/contents)

提交文字與已上傳的 asset_ref 來建立發佈作業。

請求主體欄位

欄位	類型	必要性	說明
connection_id	string	必要	目標 SNS 連線 ID (連線 API)
idempotency_key	string	必要	客戶端生成的唯一金鑰，防止重複提交
text	string	選填	貼文主體文字
media	array	選填	包含 url 或 asset_ref 的媒體物件陣列
scheduled_for	string	選填	用於排程的 ISO 8601 時間戳記；省略時會立即發佈
thread_posts	array	選填	用於 Threads 對話鏈接的額外貼文
provider_settings	object	選填	平台特定設定 (例如 YouTube 類別)

請求範例 (立即貼文)

curl -X POST "https://api.ankk.app/v1/brand/contents" \
  -H "Authorization: Bearer spk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_01jm8x9k2example",
    "idempotency_key": "launch-2026-001",
    "text": "Excited to launch our new product today! 🚀\nhttps://ankk.app",
    "media": [
      {
        "url": "https://cdn.ankk.app/sns-posts/original/brand_.../launch-banner.png"
      }
    ]
  }'

回應範例 (202 Accepted)

{
  "content_id": "content_01jm8za2example",
  "status": "scheduled",
  "publish_job_id": "job_01jm8za2jobexample",
  "connection_id": "conn_01jm8x9k2example",
  "idempotency_key": "launch-2026-001"
}

---

3. 列出與檢查內容

列出內容 (GET /v1/brand/contents)

curl -X GET "https://api.ankk.app/v1/brand/contents?status=published&limit=20" \
  -H "Authorization: Bearer spk_live_xxxxxxxx"

取得內容詳細資訊 (GET /v1/brand/contents/{content_id})

curl -X GET "https://api.ankk.app/v1/brand/contents/content_01jm8za2example" \
  -H "Authorization: Bearer spk_live_xxxxxxxx"

---

4. 取消排程貼文 (DELETE /v1/brand/contents/{content_id}/cancel)

在 scheduled 貼文開始執行前將其取消。

curl -X DELETE "https://api.ankk.app/v1/brand/contents/content_01jm8za2example/cancel" \
  -H "Authorization: Bearer spk_live_xxxxxxxx"

---

🔗 相關文件

• 連線 API
• Webhook
• 佇列與發佈狀態指南
• SNS 功能參考
• 錯誤處理