DEVELOPERS

AI 工作流 API：圖片與影片生成接入指南

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

內容核對 2026-09-30

從官方契約開始

以下發現介面無需 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。

在你的 AI 代理中使用 RelayMe

登入後在開發者頁面建立 API Key。建立 Key 不扣積分，但生成與執行工作流會扣積分，帳戶需要有足夠餘額，否則請求會被拒絕。
下載 Agent Skill 套件並解壓：共 5 個檔案夾，每個檔案夾是一個 Skill，內含 SKILL.md。把它們放到你的代理讀取 Skills 的目錄（依各代理的說明）。
在代理的執行環境中設定 RELAYME_API_KEY，僅保存在密鑰存放處或服務端，不要寫進提示詞。
第一條提示詞建議直接生成一張圖，例如： 用 relayme-creative 以 Nano Banana 生成一張 1K、1:1 的白色陶瓷杯商品圖，淺灰背景；輪詢任務直到完成，給我圖片連結。 這一步會按該模型單價扣積分。

curl -LO https://api.relayme.ai/api/ai-tools/v1/skills.zip
unzip skills.zip -d relayme-skills
ls relayme-skills
# relayme-agent  relayme-chat  relayme-creative  relayme-tasks  relayme-workflows
# each folder contains SKILL.md

export RELAYME_API_KEY="<your-api-key>"

哪些調用會扣積分

工具名稱與 function-tools.json一致。

工具	用途	扣積分？
`relayme_generate_image`	直接生成圖片	扣積分：按圖片模型的每張單價
`relayme_generate_video`	直接生成影片	扣積分：按影片模型的每秒單價
`relayme_chat`	文字對話	扣積分：按所選文字模型計費
`relayme_run_workflow`	執行已保存的工作流	扣積分：執行中的每個生成節點各自計費
`relayme_estimate_workflow`	預估工作流費用	不扣
`relayme_list_models` `relayme_list_workflows` `relayme_get_workflow` `relayme_get_workflow_schema`	發現模型與工作流、讀取輸入結構	不扣
`relayme_get_task` `relayme_list_tasks` `relayme_get_workflow_run` `relayme_list_workflow_runs`	查詢任務與執行狀態	不扣
`relayme_validate_workflow` `relayme_create_workflow` `relayme_update_workflow` `relayme_delete_workflow`	校驗、創建、更新、刪除工作流	不扣
`relayme_cancel_workflow_run`	取消執行	取消本身不扣；已交給模型提供方的調用仍可能完成並計費

API 不做什麼

瀏覽器端工具節點（圖片裁剪、影片首幀與尾幀）不能在服務端執行，會列在 unsupportedNodes 中；依賴它們的工作流無法透過 API 完整執行。
預估不是最終價格：依賴上游生成結果的節點可能用佔位值估算（exact: false），實際費用以執行後的扣費為準。
新帳號沒有已保存的工作流：先在工作台保存一條，或用 API 創建，工作流列表才會有內容。
直接的圖片／影片生成沒有幂等保證；逾時後先查任務列表，不要盲目重送。
目前沒有 MCP server，也沒有 Claude 或 ChatGPT connector；代理透過 HTTP API 與上面的 Agent Skills 接入。