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