文档 / 任务管理
文档 / 任务管理
GET /v1/tasks/{id} 是所有异步任务的通用查询端点，用于查询图像、音乐、视频等任务的执行状态、进度、结果和错误信息。
GET /v1/tasks/{id} 是所有异步任务的通用查询端点，用于查询图像、音乐、视频等任务的执行状态、进度、结果和错误信息。
创建异步任务后，接口会返回以 task_ 开头的任务 ID。客户端可以使用该 ID 轮询本接口，直到任务进入 completed 或 failed 终态。
使用创建任务时所属用户的 API Key：
Authorization: Bearer YOUR_API_KEY任务只能由所属用户查询。无效任务 ID、任务不存在或任务不属于当前用户时，均返回 404 task_not_found，避免泄露其他用户的任务信息。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 是 | 创建异步任务时返回的任务 ID，必须以 task_ 开头 |
本接口没有请求体。
curl 'https://api.apimax.ai/v1/tasks/task_V1StGXR8_Z5jdHi6B' \
--header 'Authorization: Bearer <token>'status | 含义 | 是否终态 |
|---|---|---|
queued | 任务已创建，正在排队 | 否 |
in_progress | 任务正在执行 | 否 |
completed | 任务执行成功，结果位于 data | 是 |
failed | 任务执行失败，原因位于 error | 是 |
建议每 2~5 秒查询一次。只要 status 不是 completed 或 failed，客户端就应继续等待。
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 任务 ID |
object | string | 图片任务为 image.generation.task，其他任务通常为 task |
type | string | 任务类型，如 image、music、video |
platform | string | 非图片任务可能返回的平台标识 |
status | string | 当前任务状态 |
progress | integer | 任务进度，范围 0~100 |
model | string | 创建任务时使用的模型 |
created / created_at | integer | 创建时间，Unix 时间戳 |
started_at | integer | 开始执行时间，部分任务返回 |
completed_at / finished_at | integer | 任务结束时间，终态任务返回 |
task_info | object | 图片任务的可取消状态和预计耗时 |
data | array/object | 任务结果，具体结构取决于任务类型 |
usage | object | 图片任务的计费与 token 使用信息 |
error | object | 失败原因，仅失败任务返回 |
不同任务类型会在公共字段基础上返回各自的结果结构。图片任务使用 created、completed_at 和 image.generation.task；音乐、视频等任务通常使用 created_at、finished_at 和通用 task 结构。
{
"id": "task_V1StGXR8_Z5jdHi6B",
"object": "image.generation.task",
"type": "image",
"status": "in_progress",
"progress": 35,
"created": 1757156493,
"model": "gpt-image-2",
"task_info": {
"can_cancel": false,
"estimated_time": 60
},
"usage": {
"billing_rule": "per_call",
"credits_reserved": 1,
"user_group": "default"
}
}task_info.estimated_time 是用于界面展示的预估秒数，不应作为客户端的硬超时时间。
{
"id": "task_V1StGXR8_Z5jdHi6B",
"object": "image.generation.task",
"type": "image",
"status": "completed",
"progress": 100,
"created": 1757156493,
"completed_at": 1757156593,
"model": "gpt-image-2",
"task_info": {
"can_cancel": false,
"estimated_time": 0
},
"data": [
{
"url": "https://cdn.example.com/images/result.png",
"url_expires_at": 1757160193
}
],
"usage": {
"billing_rule": "per_call",
"input_tokens": 12,
"output_tokens": 4160,
"total_tokens": 4172,
"user_group": "default"
}
}图片结果链接可能带有效期，请在任务完成后及时保存。
音乐、视频等任务返回通用任务结构，data 保留该任务类型的结果数据：
{
"id": "task_example123",
"object": "task",
"type": "video",
"platform": "video",
"status": "completed",
"progress": 100,
"model": "video-model",
"created_at": 1757156493,
"started_at": 1757156500,
"finished_at": 1757156593,
"data": [
{
"url": "https://cdn.example.com/videos/result.mp4"
}
]
}请根据 type 或 platform 判断任务类型，再解析对应的 data 内容。
{
"id": "task_V1StGXR8_Z5jdHi6B",
"object": "image.generation.task",
"type": "image",
"status": "failed",
"progress": 0,
"failed_at": 1757156593,
"model": "gpt-image-2",
"error": {
"code": "upstream_error",
"message": "content policy violation"
}
}error.code | 说明 |
|---|---|
task_not_found | 任务 ID 无效、任务不存在或不属于当前用户 |
upstream_error | 上游拒绝请求或返回业务错误 |
upstream_unavailable | 上游服务暂时不可用 |
storage_error | 任务结果保存失败 |
internal_error | 网关内部错误 |
completed 和 failed 都是终态，进入终态后应停止轮询。callback_url 的，可以使用回调代替持续轮询；回调内容与本查询接口的终态结构一致。