指南

Task API 快速开始

创建异步 Task，并处理轮询、完成、失败与 callback。

RunAPI 使用 Task 执行异步图像、视频、音频和音乐生成。创建请求会快速返回；随后应用通过轮询观察 Task，或在它进入终态时接收 callback。

创建 Task

先在模型目录中选择模型和端点，再发送该端点要求的输入。下面的请求会启动一个 Flux 2 文生图 Task：

SHELL

curl -X POST "https://runapi.ai/api/v1/flux_2/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro-text-to-image",
    "prompt": "干净影棚背景中的产品照片"
  }'

异步请求被接受后会返回 202 Accepted 和 Task identifier：

JSON

{
  "id": "task_id",
  "status": "processing"
}

将 id 与应用记录一起保存。轮询、问题排查与 callback 对账都使用这个稳定 identifier。

轮询 Task

在同一个端点路径后追加 Task identifier：

SHELL

curl "https://runapi.ai/api/v1/flux_2/text_to_image/task_id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

status 为 processing 时继续等待。两次请求之间使用有上限的退避策略，不要无间隔持续轮询。Task 的状态变为 completed 或 failed 后即进入终态。

处理完成状态

completed 响应包含 Task id、终态 status 和端点专属的结果字段。保存应用需要的结果并停止轮询。请从该端点的 API Reference 获取准确结果结构，不要假设所有媒体端点返回相同字段。

处理失败状态

failed 响应包含 Task id、终态 status，并在可用时提供由 RunAPI 编写的 error。停止轮询，记录 identifier 与错误；只有当应用确认错误属于瞬时故障时才重试。每次重试都会创建新的 Task identifier。

接收 callback

如果希望 RunAPI 把终态 payload 发送到应用，请在创建请求中加入公网可访问的 HTTPS callback_url：

JSON

{
  "model": "flux-2-pro-text-to-image",
  "prompt": "干净影棚背景中的产品照片",
  "callback_url": "https://your-domain.com/webhooks/runapi"
}

Callback body 与终态轮询响应具有相同的公开结构。处理端应快速返回成功 HTTP 响应，按 Task id 幂等处理事件；当投递延迟或 callback handler 不可用时，保留轮询作为对账方式。