API 總覽

這裡提供 Boring API 的端點、驗證方式與通用使用規範。

基底網址

https://boring.aiagent-me.com

所有 API 請求都應指向此網址。

驗證方式

API Key 驗證

除了 OAuth 回呼之外，所有 API 請求都必須在標頭附上 API Key：

boring-api-key: boring_xxxxxxxxxxxxx

取得 API Key 的步驟：

  1. 登入 Boring 控制台
  2. 前往 Settings 頁面
  3. 點擊 「Generate New API Key」
  4. 複製並妥善保存金鑰

詳情請見 API 金鑰 章節。

請求格式

Content-Type

所有請求都必須包含：

Content-Type: application/json

Request Body

請求本體需為合法 JSON：

{
  "post": {
    "accountId": "uuid-string",
    "content": {
      "text": "Post content",
      "mediaUrls": ["https://example.com/image.jpg"],
      "platform": "facebook|instagram|threads"
    },
    "target": {
      "targetType": "facebook|instagram|threads"
    }
  }
}

回應格式

成功回應

成功的回應皆會回傳 success: true：

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    // 依端點而定
  }
}

錯誤回應

錯誤時會回傳 success: false：

{
  "success": false,
  "error": "Error type",
  "message": "Detailed error message"
}

常見 HTTP 狀態碼：

完整錯誤代碼請見 錯誤代碼。

端點一覽

發佈 API

Method Endpoint 說明 驗證
POST /v2/posts 對各平台發佈內容 API Key

詳見 發佈 章節。

帳號管理

Method Endpoint 說明 驗證
GET /api/accounts 列出已連結帳號 Session
DELETE /api/accounts/{id} 解除連結 Session
POST /api/token/info 驗證權杖資訊 Session

注意：以上端點需使用控制台登入的 Session Cookie，不接受 API Key。

發佈歷史

Method Endpoint 說明 驗證
GET /api/published-posts 取得發佈紀錄 Session

查詢參數：

注意：同樣需控制台登入。

範例請求

發佈 Facebook 貼文

curl -X POST https://boring.aiagent-me.com/v2/posts \
  -H "boring-api-key: boring_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "post": {
      "accountId": "facebook-account-id",
      "content": {
        "text": "Hello Facebook!",
        "mediaUrls": ["https://example.com/photo.jpg"],
        "platform": "facebook"
      },
      "target": {
        "targetType": "facebook"
      }
    }
  }'

驗證回應狀態

{
  "success": true,
  "message": "Post published successfully",
  "data": {
    "post_id": "...",
    "platform": "facebook",
    "post_type": "photo"
  }
}

速率限制

速率限制依平台而異：

平台 限制 時間窗
Facebook 200 次 每小時
Instagram 200 次 每小時
Threads 250 次 每小時
X（Twitter） 300 次 3 小時
YouTube 10,000 units 每日（配額制）

超量時會收到：

{
  "success": false,
  "error": "RateLimitExceeded",
  "message": "Rate limit exceeded. Try again in 3600 seconds.",
  "retry_after": 3600
}

建議做法：

冪等性

目前尚未提供 idempotency key。重複發送相同請求會造成重複貼文。

建議：可使用回應中的 post_submission_id 自行實作去重邏輯。

分頁機制

目前只有發佈歷史支援分頁：

GET /api/published-posts?limit=20&offset=0

參數：

回應範例：

{
  "posts": [...],
  "total": 150,
  "limit": 20,
  "offset": 0
}

逾時設定

若請求逾時：

Webhook

目前尚未提供 Webhook。若要監控狀態，建議：

API 版本

目前版本：v2

端點格式：

POST /v2/posts

汰除政策：

SDK 支援

官方 SDK：

目前請使用常見 HTTP 函式庫：

程式範例請見 範例。

測試建議

測試帳號

請使用自己的測試帳號：

Sandbox 模式

目前 沒有 sandbox。所有呼叫都會發佈到真實帳號。

建議：

最佳實務

1. 錯誤處理

try:
    response = requests.post(API_URL, headers=headers, json=data)
    result = response.json()

    if not result.get("success"):
        log_error(result["message"])
        notify_admin(result)
        return None

    return result["data"]

except requests.exceptions.Timeout:
    log_error("Request timed out")
    # 重試邏輯

except requests.exceptions.RequestException as e:
    log_error(f"Request failed: {e}")
    # 處理網路錯誤

2. 重試機制

import time

def publish_with_retry(data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(API_URL, headers=headers, json=data)
            result = response.json()

            if result.get("success"):
                return result

            if result.get("error") == "RateLimitExceeded":
                wait_time = result.get("retry_after", 60)
                time.sleep(wait_time)
                continue

        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # 指數回退

    return None

3. 紀錄日誌

import logging

logger = logging.getLogger(__name__)

logger.info(f"Publishing to {platform}: {account_id}")
response = requests.post(API_URL, headers=headers, json=data)
logger.info(f"Response: {response.status_code} - {response.text}")

4. 安全性

5. 效能

支援服務

需要協助嗎？

下一步