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。