DEVELOPERS

RelayMe Agent API：工作流接入指南

透過 HTTP API 發現工作流、讀取輸入結構、預估費用並提交非同步執行。使用同一個 runId 查詢結果，將圖片與影片工作流接入你的應用。

內容核對 2026-09-20

從官方契約開始

以下發現介面無需 API Key；實際工作流與生成請求需要帳號權限與 Bearer 認證。

執行流程

發現工作流並檢查輸入結構
帶入輸入，預估並確認費用
用穩定的幂等鍵提交一次執行
依回應間隔查詢，取得終態與輸出

1. 取得帳號可用的工作流

登入後在開發者頁面建立 API Key，僅保存在服務端。以下範例中的 Key、工作流 ID 和節點 ID 都是需要替換的值。

export RELAYME_BASE_URL="https://api.relayme.ai"
export RELAYME_API_KEY="<your-api-key>"

curl "$RELAYME_BASE_URL/api/ai-tools/v1/workflows" \
  -H "Authorization: Bearer $RELAYME_API_KEY"

2. 讀取輸入與輸出結構

# Replace 123 with a workflow ID returned for your account.
export WORKFLOW_ID="123"
curl "$RELAYME_BASE_URL/api/ai-tools/v1/workflows/$WORKFLOW_ID/schema" \
  -H "Authorization: Bearer $RELAYME_API_KEY"

按 inputSchema 提供 inputs。先檢查 unsupportedNodes；瀏覽器專用工具節點不一定支援服務端執行。outputs 的鍵對應 outputSchema。

3. 預估本次費用

# Replace text-1 with an input node ID from your workflow schema.
curl -X POST "$RELAYME_BASE_URL/api/ai-tools/v1/workflows/$WORKFLOW_ID/estimate" \
  -H "Authorization: Bearer $RELAYME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"text-1":"A clean product photo on a white background"}}'

檢查 estimatedCost、幣種、逐節點預估與 assumptions；exact: false 代表估值仍有不確定性。選擇可接受的參數後，再提交執行。

4. 提交並保存 runId

# Create a unique key for each intended run; reuse it for retries of that run.
export RUN_KEY="product:YOUR-PRODUCT-ID:hero-image:v1"
curl -i -X POST "$RELAYME_BASE_URL/api/ai-tools/v1/workflows/$WORKFLOW_ID/runs" \
  -H "Authorization: Bearer $RELAYME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $RUN_KEY" \
  -d '{"inputs":{"text-1":"A clean product photo on a white background"}}'

首次接收回傳 HTTP 202、Location、Retry-After 與 data.runId；相同請求的幂等重試可能回傳 HTTP 200，仍應讀取 data.runId。幂等鍵應綁定一次業務操作；同一操作的網路重試重用原鍵，新操作使用新鍵。

5. 查詢狀態與結果

export RUN_ID="<runId-from-the-202-response>"
curl "$RELAYME_BASE_URL/api/ai-tools/v1/workflow-runs/$RUN_ID" \
  -H "Authorization: Bearer $RELAYME_API_KEY"

依 Retry-After 或 retryAfterSeconds 等待。QUEUED、RUNNING、CANCEL_REQUESTED 尚未終止；COMPLETED 時讀 outputs；FAILED 時查看節點錯誤；CANCELLED 時停止輪詢。也可在建立執行時配置簽名 Webhook。