---
title: Task API 快速开始
url: https://runapi.ai/zh-CN/docs/guides/task-api/quickstart.md
canonical: https://runapi.ai/zh-CN/docs/guides/task-api/quickstart
locale: zh-CN
---

# Task API 快速开始

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 不可用时，保留轮询作为对账方式。