状态与轮询

状态说明

状态	是否终态	说明
submitted	否	任务已提交，正在进入队列
queued	否	任务已进入队列，等待执行
in_progress	否	图片正在生成
succeeded	是	生成成功，可读取 result.data
failed	是	生成失败，可读取 error

只有 succeeded 和 failed 是终态。

推荐轮询策略

• 每隔 2～5 秒查询一次。
• 对 HTTP 429 和 503 使用指数退避。
• 对 400、401、403、404 和 409，先修正请求或权限，不要无限重试。
• 设置符合业务场景的总超时时间；客户端超时不代表服务端任务自动取消。

async function waitForImageTask(baseURL, token, taskId) {
  while (true) {
    await new Promise((resolve) => setTimeout(resolve, 3000));
    const response = await fetch(
      `${baseURL}/v1/images/generations/tasks/${encodeURIComponent(taskId)}`,
      { headers: { Authorization: `Bearer ${token}` } },
    );
    if (!response.ok) throw new Error(await response.text());

    const task = (await response.json()).data;
    if (task.status === 'succeeded') return task.result.data;
    if (task.status === 'failed') {
      throw new Error(`${task.error.code}: ${task.error.message}`);
    }
  }
}

常见接口错误

HTTP	错误码	说明
400	invalid_image_request	请求体或图片参数不正确
400	invalid_async_request	异步控制参数不正确
401	—	Token 无效或缺失
403	insufficient_user_quota 等	余额不足或模型/分组权限不可用
404	image_async_task_not_found	任务不存在或当前用户无权查看
409	idempotency_conflict	相同幂等键对应不同请求
413	invalid_image_request	请求体过大
429	user_queue_limit_exceeded	当前用户待处理任务达到上限
429	global_queue_capacity_exceeded	服务任务较多，请稍后重试
503	image_async_disabled	异步服务暂时不可用
503	storage_unavailable	结果存储暂时不可用
410	result_expired	任务结果已过期