Pixapi

外观

查询任务结果 ​

提交异步图片或视频任务后，Pixapi 会返回任务 id。使用 GET /v1/tasks/{id} 查询状态、进度和最终媒体 URL。

提交方式见 异步媒体任务。

端点 ​

方法路径说明
GET/v1/tasks/{id}查询任务状态与结果

鉴权：Authorization: Bearer <API_KEY>

只能查询同一 API Key / 账户创建的任务。未知 id 返回 404。

请求 ​

bash
curl --request GET \
  --url 'https://api.pixapi.ai/v1/tasks/task_01KPQ7J7DWB7QZ3WCEK3YVPBRA' \
  --header 'Authorization: Bearer $PIXAPI_KEY'

路径参数：

字段类型必填说明
idstring是提交异步任务时返回的任务 id（例如 task_...）。

状态值 ​

状态含义
submitted已接收并排队
processing正在生成
completed成功完成，读取 result.data[].url
failed失败，读取 error

轮询直到 status 为 completed 或 failed。进行中时 result 为 null。

进行中响应 ​

json
{
  "id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA",
  "status": "processing",
  "credits_cost": 64,
  "model": "veo3.1-fast",
  "progress": 40,
  "result": null,
  "created": 1703884800
}

成功响应 ​

json
{
  "id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA",
  "status": "completed",
  "credits_cost": 64,
  "model": "veo3.1-fast",
  "progress": 100,
  "result": {
    "type": "video",
    "data": [
      {
        "url": "https://cdn.example.com/output.mp4"
      }
    ]
  },
  "created": 1703884800,
  "completed": 1703884880
}

图片任务的 result.type 为 image，data[] 同样包含公网 url。

失败响应 ​

json
{
  "id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA",
  "status": "failed",
  "credits_cost": 64,
  "model": "veo3.1-fast",
  "progress": 100,
  "error": {
    "code": 400,
    "message": "Upstream generation failed",
    "type": "api_error"
  },
  "created": 1703884800,
  "completed": 1703884820
}

响应字段 ​

字段说明
id任务 id
statussubmitted / processing / completed / failed
credits_cost任务关联积分
model提交时使用的模型 id
progress0–100 的整数进度
result成功时有值；进行中为 null
result.typeimage 或 video
result.data输出列表；主资源取 result.data[0].url
errorfailed 时出现
created创建时间（Unix 秒）
completed进入终态的时间（Unix 秒）

轮询示例 ​

js
async function waitForTask(taskId) {
  for (;;) {
    const response = await fetch(`https://api.pixapi.ai/v1/tasks/${taskId}`, {
      headers: { Authorization: `Bearer ${process.env.PIXAPI_KEY}` },
    });
    if (!response.ok) throw new Error(await response.text());
    const task = await response.json();
    if (task.status === 'completed' || task.status === 'failed') return task;
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}

const task = await waitForTask('task_01KPQ7J7DWB7QZ3WCEK3YVPBRA');
if (task.status === 'completed') {
  console.log(task.result.data[0].url);
} else {
  console.error(task.error);
}

接入建议 ​

  1. 保存异步提交响应里的任务 id。
  2. 在后端轮询 GET /v1/tasks/{id}，建议间隔 2–5 秒并做退避。
  3. 当 status 为 completed 或 failed 时停止。
  4. 将 result.data[].url（或 error）写入你自己的存储。

不要在纯浏览器端用 Pixapi API Key 做轮询。