跳转到主要内容
APIXO 对所有生成任务使用异步模式。这种设计符合 AI 生成耗时的特点——图像需要几秒,视频则需几分钟。

模式流程

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Submit    │────▶│  Poll or    │────▶│   Retrieve  │
│   Task      │     │  Callback   │     │   Results   │
└─────────────┘     └─────────────┘     └─────────────┘
      │                   │                   │
      ▼                   ▼                   ▼
   taskId            state check          resultUrls

步骤 1:提交任务

发送 POST 请求创建生成任务:
POST https://api.apixo.ai/api/v1/generateTask/{model}
请求:
{
  "request_type": "async",
  "input": {
    "mode": "text-to-image",
    "prompt": "A beautiful sunset over mountains"
  }
}
响应:
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_abc123xyz"
  }
}
API 会立即返回 taskId,实际生成在后台进行。

步骤 2:获取结果

你有两种方式接收结果:

方式 A:轮询(适合入门)

定期检查任务状态:
GET https://api.apixo.ai/api/v1/statusTask/{model}?taskId={taskId}
响应(进行中):
{
  "data": {
    "taskId": "task_abc123xyz",
    "state": "processing"
  }
}
响应(已完成):
{
  "data": {
    "taskId": "task_abc123xyz",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://cdn.apixo.ai/...\"]}",
    "costTime": 12500
  }
}

方式 B:Webhooks(适合生产环境)

提交时提供 callback_url
{
  "request_type": "callback",
  "callback_url": "https://your-server.com/webhook/apixo",
  "input": { ... }
}
任务完成时,APIXO 会向你的 URL 发送 POST 请求推送结果。 详见 Webhooks 实现说明。

任务状态

StateDescription
pending任务排队中,等待开始
processing任务正在处理
success任务成功完成
failed任务失败(查看 failMsg

轮询最佳实践

  1. 多数任务建议 3–5 秒 轮询一次
  2. 长任务(如视频) 使用指数退避
  3. 设置最大超时时间(例如 5 分钟)
  4. 妥善处理失败,并加入重试逻辑
const pollWithBackoff = async (taskId, maxWait = 300000) => {
  let interval = 3000; // Start at 3s
  const startTime = Date.now();
  
  while (Date.now() - startTime < maxWait) {
    const result = await checkStatus(taskId);
    
    if (result.state === 'success') return result;
    if (result.state === 'failed') throw new Error(result.failMsg);
    
    await sleep(interval);
    interval = Math.min(interval * 1.5, 30000); // Max 30s
  }
  
  throw new Error('Timeout waiting for result');
};

如何选择

ApproachBest For
Polling简单集成、客户端应用、测试
Webhooks生产服务器、实时应用、高并发场景

下一步