指南

快速开始

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

RunAPI 使用 Task 执行异步图像、视频、音频和音乐生成。创建请求会快速返回；随后应用通过轮询观察 Task，或接收该端点 API Reference 列出的 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 "Idempotency-Key: 8c8ba3c9-0ce0-4bbd-a9a7-bf59ab639286" \
  -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 创建端点支持可选的 Idempotency-Key 请求头，值为最长 512 个字符的不透明字符串。每个逻辑 Task 生成一个值，并将它与请求一起保存，直到确认请求是否已被接受。

如果超时或连接失败导致无法确认结果，请使用相同的 key 重发完全相同的 Task 创建请求。RunAPI 会返回原有 Task，而不是再次创建和扣费。使用同一个 key 发送不同的 Task 创建请求会返回 409 Conflict。有意创建新的 Task 时生成新的 key；不要把 X-Client-Request-Id 当作这个 key。

恢复中断的同步请求

较慢的同步端点默认会保持连接，并返回与原有行为相同的终态响应。现有集成不需要增加轮询逻辑。

如果调用方希望主动缩短连接等待时间，可以发送 Prefer: wait=N。Task 在这个显式预算结束时仍未完成，RunAPI 才返回 202 Accepted，其中包含同一个 Task id、用于恢复的不透明 Location URL，以及建议查询间隔的 Retry-After。必须原样访问 Location，不要拼接结果 URL。完成的 Task Result 会保留终态 HTTP status、允许的 headers、content type 与 body；应按 response.content_type 解码 response.body，它不一定是 JSON。

轮询 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 把该端点文档声明的 callback 事件发送到应用，请在创建请求中加入公网可访问的 HTTPS callback_url：

JSON

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

每个 callback body 都对应端点 API Reference 中的一种生命周期事件，并且不包含仅由轮询返回的 billing 明细。终态 callback 包含与终态轮询响应相同的结果字段；部分端点还会发送文档中列出的 processing callback。处理端应快速返回成功 HTTP 响应；当投递延迟或 callback handler 不可用时，保留轮询作为对账方式。

请阅读回调，了解如何创建 Callback Secret、校验签名并安全处理重试。