Skip to main content
GET
/
common
/
query-async-task-result
Query Async Task Results
curl --request GET \
  --url https://api.aihairstyle.cn/common/query-async-task-result \
  --header 'ailabapi-api-key: <api-key>'
{
  "request_id": "<string>",
  "log_id": "<string>",
  "error_code": 123,
  "error_msg": "<string>",
  "error_detail": {
    "status_code": 123,
    "code": "<string>",
    "code_message": "<string>",
    "message": "<string>"
  },
  "task_status": 0,
  "result": [
    "<string>"
  ]
}

​
请求

  • URL: /common/query-async-task-result
  • 方法: POST

​
请求头

字段必填类型描述
ailabapi-api-key是string应用 API KEY。 获取 API KEY

​
请求体参数

​
固定字段

字段必填类型描述
task_id是string异步 API 返回的 task_id

​
异步任务查询 API

查询异步任务的处理结果，获取最终的处理结果。对于异步接口，在调用 API 后返回的结果不是真实的请求结果，您需要保存返回结果中的 task_id，然后调用此接口获取真实的请求结果。

​
功能特点

  • 任务状态查询：实时查询异步任务的处理状态
  • 结果获取：获取任务完成后的最终结果
  • 状态监控：监控任务从排队到完成的整个过程
  • 错误处理：处理任务失败的情况

​
应用场景

  • 异步处理：配合异步 API 使用，获取处理结果
  • 状态监控：实时监控任务处理进度
  • 结果获取：获取发型编辑、人脸分析等任务的最终结果
  • 错误恢复：处理任务失败后的重试逻辑

​
任务状态说明

状态码状态说明
0排队中任务已提交，正在等待处理
1处理中任务正在处理中
2已完成任务处理成功，可以获取结果
-1失败任务处理失败

​
响应示例

​
任务排队中

{
  "request_id": "123456789",
  "log_id": "987654321",
  "error_code": 0,
  "error_msg": "",
  "error_detail": {
    "status_code": 200,
    "code": "",
    "code_message": "",
    "message": ""
  },
  "task_status": 0
}

​
任务处理中

{
  "request_id": "123456789",
  "log_id": "987654321",
  "error_code": 0,
  "error_msg": "",
  "error_detail": {
    "status_code": 200,
    "code": "",
    "code_message": "",
    "message": ""
  },
  "task_status": 1
}

​
任务已完成

{
  "request_id": "123456789",
  "log_id": "987654321",
  "error_code": 0,
  "error_msg": "",
  "error_detail": {
    "status_code": 200,
    "code": "",
    "code_message": "",
    "message": ""
  },
  "task_status": 2,
  "result": [
    "https://example.com/result1.jpg",
    "https://example.com/result2.jpg",
    "https://example.com/result3.jpg",
    "https://example.com/result4.jpg"
  ]
}

​
任务失败

{
  "request_id": "123456789",
  "log_id": "987654321",
  "error_code": 0,
  "error_msg": "",
  "error_detail": {
    "status_code": 200,
    "code": "",
    "code_message": "",
    "message": ""
  },
  "task_status": -1
}

​
错误响应

{
  "request_id": "123456789",
  "log_id": "987654321",
  "error_code": 400,
  "error_msg": "Invalid task_id",
  "error_detail": {
    "status_code": 400,
    "code": "ERROR_INVALID_TASK_ID",
    "code_message": "Invalid task ID",
    "message": "The provided task_id is invalid or expired"
  }
}

​
响应字段说明

字段类型说明
task_statusinteger任务状态：0=排队中，1=处理中，2=已完成，-1=失败
resultarray任务结果数组（仅在 task_status=2 时返回）

​
最佳实践

​
1. 轮询查询

async function pollAsyncTask(taskId, maxAttempts = 100) {
  const interval = 5000; // 5秒间隔
  
  for (let i = 0; i < maxAttempts; i++) {
    try {
      const result = await queryAsyncTask(taskId);
      
      switch (result.task_status) {
        case 0:
          console.log('任务排队中...');
          break;
        case 1:
          console.log('任务处理中...');
          break;
        case 2:
          console.log('任务完成！');
          return result;
        case -1:
          throw new Error('任务处理失败');
        default:
          throw new Error('未知的任务状态');
      }
      
      // 等待后重试
      await new Promise(resolve => setTimeout(resolve, interval));
      
    } catch (error) {
      console.error('查询任务状态失败:', error);
      if (i === maxAttempts - 1) {
        throw error;
      }
    }
  }
  
  throw new Error('任务超时');
}

​
2. 带进度显示的查询

async function pollWithProgress(taskId, onProgress) {
  const maxAttempts = 100;
  const interval = 5000;
  
  for (let i = 0; i < maxAttempts; i++) {
    const result = await queryAsyncTask(taskId);
    
    // 计算进度
    let progress = 0;
    switch (result.task_status) {
      case 0:
        progress = 10;
        break;
      case 1:
        progress = 50 + (i / maxAttempts) * 40; // 50%-90%
        break;
      case 2:
        progress = 100;
        break;
      case -1:
        throw new Error('任务处理失败');
    }
    
    // 回调进度
    onProgress(progress, result.task_status);
    
    if (result.task_status === 2) {
      return result;
    }
    
    await new Promise(resolve => setTimeout(resolve, interval));
  }
  
  throw new Error('任务超时');
}

// 使用示例
pollWithProgress('task_123456789', (progress, status) => {
  console.log(`进度: ${progress}%, 状态: ${status}`);
});

​
3. 错误处理和重试

async function queryWithRetry(taskId, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const result = await queryAsyncTask(taskId);
      
      if (result.task_status === -1) {
        throw new Error('任务处理失败');
      }
      
      return result;
      
    } catch (error) {
      console.error(`第 ${i + 1} 次查询失败:`, error);
      
      if (i === maxRetries - 1) {
        throw error;
      }
      
      // 指数退避
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

​
注意事项

  • 异步任务结果有效期为 24 小时
  • 建议每 5 秒查询一次结果
  • 任务失败后无法重试，需要重新提交任务
  • 请妥善保存 task_id，避免丢失
优化建议：
  • 使用 WebSocket 或 Server-Sent Events 获取实时状态更新
  • 实现指数退避算法避免频繁请求
  • 添加超时机制防止无限等待
  • 缓存查询结果减少重复请求

​
相关链接

Authorizations

​
ailabapi-api-key
string
header
required

API Key for authentication

Query Parameters

​
task_id
string
required

The task_id returned by the asynchronous API.

Response

Success

​
request_id
string

Request ID

​
log_id
string

Log ID

​
error_code
integer

Status code (0 for success)

​
error_msg
string

Error message

​
error_detail
object
​
task_status
enum<integer>

Task status: 0=queued, 1=processing, 2=completed, -1=failed

Available options:
0,
1,
2,
-1
​
result
string[]

Array of result image URLs (when task_status=2)

Result image URL