指南

快速开始

创建异步 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。

传入媒体输入

Media Input Field 是携带媒体 URL 的请求字段：名称以 _url 或 _urls 结尾的顶层字段（例如 image_url 或 image_urls）、video_list 每一项的 url，以及 kling_elements 每一项的 element_input_urls、element_input_video_urls 和 element_input_audio_urls。callback_url 是回调投递地址，不属于 Media Input Field。每个 Media Input Field 的值可以是公开的 HTTPS URL，也可以是 data:<mime>;base64,<data> 格式的 data URI，单个 data URI 最大 10 MB。RunAPI 会将每个 data URI 保存为一小时后过期的临时 File Upload，并在 Task 中使用该 File Upload。无法保存的 data URI 返回 422，错误码为 invalid_media_input。

GPT Image 编辑端点的 source_image_urls 只接受 HTTPS URL。向这些端点发送本地图片时，请先创建 File Upload，再传入返回的 URL。

文件超过 10 MB 时，请先通过 POST /api/v1/files 创建 File Upload，再传入返回的 URL。通过 multipart 或 URL 来源创建的 File Upload 最大支持 50 MB。File Upload URL 同样在一小时后过期，超过该时间后启动的 Task 需要重新创建 File Upload。

SHELL

# 此模型的非 PNG/JPEG 输入可能返回 409，具体取决于所选服务。
# 若被拒绝，请将 WebP/BMP/TIFF/GIF 转为 PNG/JPEG，或选择兼容服务。
# 按真实 MIME 判断，即使 URL 以 .png 结尾。拒绝发生在创建任务和扣费前。
# 这不是所有服务的格式限制。已有任务仍可查询。
curl -X POST "https://runapi.ai/api/v1/seedream/decompose_layers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedream-5-pro-layer-decomposition","image_url":"https://cdn.runapi.ai/public/samples/image.png"}'

避免重复创建 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、端点专属结果字段，以及该 Task 的 usage.cost（float USD）。保存应用需要的结果并停止轮询。请从该端点的 API Reference 获取准确结果结构，不要假设所有媒体端点返回相同字段。

创建、processing 和 failed 的 Task envelope 不包含 usage。

需要根据媒体用量完成最终结算的 Task，在最终费用落库前保持 processing。完成回调仅在结算后发送，其中的 usage.cost 与后续 Task 查询一致。缺失账务事实不会被视为零费用：Task 会保持 processing，等待账务核实。只有已确认的零费用才会返回 usage.cost: 0。

处理失败状态

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 中的一种生命周期事件。completed callback 与 completed 轮询响应共享 usage.cost；创建、processing 和 failed callback 不包含 usage。终态 callback 包含与终态轮询响应相同的结果字段；部分端点还会发送文档中列出的 processing callback。处理端应快速返回成功 HTTP 响应；当投递延迟或 callback handler 不可用时，保留轮询作为对账方式。

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

生成 Vidu Q4 视频

调用 POST /api/v1/vidu/image_to_video，传入 model: "vidu-q4-image-to-video" 和 first_frame_image_url。调用 POST /api/v1/vidu/reference_to_video，传入 model: "vidu-q4-reference-to-video"、非空白 prompt 和 1–15 个按顺序排列的 reference_image_urls。在创建路径后加上 /:id，通过 GET 查询任务。完成结果包含带视频 URL 的 videos 数组。也可以提供 callback_url 接收完成通知。

两种接口均支持整数 duration_seconds，范围为 3–16 秒，默认 5 秒。output_resolution 支持 540p、720p、1080p、2k、4k，默认 720p。audio 必须是 JSON 布尔值，默认 true，显式传入 false 可关闭生成音频。提示词最多 20,000 字符。图生视频的提示词可省略，画面比例由首帧决定。多参考视频支持 aspect_ratio，可选 16:9、9:16、1:1、4:3、3:4，默认 16:9，还可以提供最多 3 个 reference_audio_urls。

媒体必须使用公开的 HTTP(S) URL。图片支持 JPG/JPEG、PNG、WEBP，首帧图片不得超过 50 MB。每段参考音频必须是 MP3，时长为 3–12 秒，大小不得超过 50 MB。RunAPI 校验字段类型、URL 协议和参考数量。视频生成服务会异步校验远程媒体的实际格式、大小和音频时长。违规媒体可能导致任务失败，并进入既有失败与退款流程。

图生视频价格。多参考视频价格。