HTTP API
透過現有的 HTTP API 驗證身分、探索工具並確認變更。
將產品 API 請求傳送至可信任的 Influence 來源網址，例如 https://influence.so。文件網域不接受產品 API 請求。使用下列完整路徑，不要附加查詢參數。
建立限定權限的 API 金鑰
在 Influence 設定中，開啟「應用程式與自動化」→「API 金鑰」。選擇需要的權限與到期時間。將僅顯示 1 次的金鑰存入機密儲存空間，命名為 PUBLISH_API_TOKEN。透過 Authorization: Bearer … 傳送，絕不可放入網址、請求主體或聊天內容。不再需要時，撤銷金鑰。
探索工具並讀取社群帳號
將 PUBLISH_API_URL 設為可信任的來源網址。以下範例假設程序已具備 PUBLISH_API_TOKEN。accountList 需要 integrations:read 權限；請依其分頁欄位取得後續頁面。
export PUBLISH_API_URL="https://influence.so"
curl "$PUBLISH_API_URL/api/v1/tools" \
-H "Authorization: Bearer $PUBLISH_API_TOKEN"
curl "$PUBLISH_API_URL/api/v1/tools/accountList/call" \
-H "Authorization: Bearer $PUBLISH_API_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"input":{}}'請求路徑
| 方法 | 路徑 | 用途 |
|---|---|---|
GET |
/api/v1/tools |
列出此憑證可用的工具。 |
POST |
/api/v1/tools/{tool}/call |
呼叫不需確認的工具，包括接續已授權的上傳。 |
POST |
/api/v1/tools/{tool}/prepare |
準備確切的寫入內容，不執行寫入。 |
POST |
/api/v1/tools/{tool}/confirm |
確認已準備的寫入操作。 |
POST |
/api/v1/media/import |
確認已準備的小型二進位圖片上傳。 |
JSON 工具請求使用 Content-Type: application/json，請求主體只能包含 input：{"input":{…}}。各工具的輸入結構，請從目前的工具目錄取得。
準備並確認操作
依工具目錄的 confirmation 欄位判斷：讀取操作通常不需確認，但成效分析重新整理雖屬讀取，仍需確認。查詢上傳分段、完成及取消上傳，會透過 /call 接續已授權的上傳。
- 將確切的業務輸入傳給
/prepare。成功回應包含status: "confirmation_required"、confirmationCapability、expiresAt、inputDigest，以及可選的summary。 - 到期前，將相同輸入傳給
/confirm。把傳回的確認憑證放入X-Publish-Confirmation，並在Idempotency-Key放入由呼叫端新產生的金鑰。 - 一併保留輸入、確認憑證與金鑰。確認過程中斷或結果不明確時，對同一請求重用全部 3 項值。不要另建準備請求來復原不確定的結果。
等冪金鑰由 16–200 個字元組成，可使用 A–Z、a–z、0–9、.、_、: 與 -。確認憑證是不透明的機密值。傳給 /call 或 /prepare 的金鑰，不會預留任何經確認的寫入操作。
傳輸確認與發布核准是分開的。發布或變更排程前，須呈現目前完整的審核內容：社群帳號、文字、設定、實際媒體預覽或連結、排定時間及時區。對符合條件的社群文字、圖片與影片審核，用戶端可透過 approval: "approved" 回報使用者當次明確核准；不得虛構同意，也不能把準備請求視為核准。Influence 會將此記錄為用戶端回報的核准。受支援的內嵌卡片或已登入的審核畫面，則會記錄各自的人工操作。
TikTok Direct 可透過審核流程接收使用者在聊天中明確選擇的設定與同意。以 campaignReview 儲存完整選項後，須先取得對更新版審核內容的當次核准，才能執行。審核卡片並非必要。一般 API／CLI 排程不消耗 AI 排程額度；另外適用的 MCP 與 Influence IQ 額度依這些流程計算，即使儲存的 AI 審核之後改在 Influence 中核准，仍然適用。其他方案及服務供應商要求仍須遵守。採取下一步前，先讀取已儲存的收據；needs_review 表示需要核對結果，不是再傳送一次。
處理錯誤與不確定結果
同時檢查 HTTP 狀態與回應主體。工具成功時傳回 {"ok":true,"toolName":"…","output":{…}}。工具失敗時傳回 {"ok":false,"toolName":"…","error":{"code":"…","message":"…","retryable":false}}，HTTP 狀態仍可能是 200。傳輸失敗則使用 {"error":{"code":"…","message":"…","retryable":false}}，不含 ok 或 toolName。
401 表示需要身分驗證，請檢查憑證是否到期或已撤銷。缺少權限時，須取得適當授權，反覆請求無法補足權限。503 可能表示服務無法使用，也可能是另一個排程請求正在更新工作區。依傳回的錯誤代碼與重試指引處理，不要自動重播發布操作。逾時不代表寫入失敗：保留確認資料，重新提交前先讀取目前狀態。已接受、已排程與已發布是不同結果。
上傳媒體
本機檔案優先使用 SDK 的 uploadMedia 或 CLI 的 media:upload。兩者都使用相同的分段上傳工具，並保留穩定的 clientKey 供重試。只有已就緒且帶有 assetId 的結果才能附加。對已授權的 HTTPS 連結，使用 mediaImport，提供 url 及可選的 name。真正的主機檔案參照使用獨立的 file 物件；公開網址不需要虛構主機檔案 ID。本機檔案路徑不是下載網址。請見媒體限制：HTTPS 影片匯入上限為 250 MiB，即使直接上傳允許更大的就緒 MP4，這項上限仍然適用。
POST /api/v1/media/import 支援現有的小型圖片傳輸方式：以確切的上傳描述物件準備 mediaImport，再將相同位元組以 application/octet-stream 傳送。帶入 X-Publish-Confirmation、Idempotency-Key，並在 X-Publish-Upload 放入經 URI 編碼的 JSON 描述物件。位元組必須符合描述的大小及 SHA-256。此傳輸方式上限為 3 MiB；較大的受支援檔案請使用上傳輔助工具。上傳絕不代表核准發布。