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>'

const options = {method: 'GET', headers: {'ailabapi-api-key': '<api-key>'}};

fetch('https://api.aihairstyle.cn/common/query-async-task-result', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aihairstyle.cn/common/query-async-task-result",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "ailabapi-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aihairstyle.cn/common/query-async-task-result"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("ailabapi-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.aihairstyle.cn/common/query-async-task-result")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["ailabapi-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "request_id": "<string>",
  "log_id": "<string>",
  "error_code": 123,
  "error_msg": "<string>",
  "error_detail": {
    "status_code": 123,
    "code": "<string>",
    "code_message": "<string>",
    "message": "<string>"
  },
  "result": [
    "<string>"
  ]
}

{
  "request_id": "<string>",
  "log_id": "<string>",
  "error_code": 123,
  "error_msg": "<string>",
  "error_detail": {
    "status_code": 123,
    "code": "<string>",
    "code_message": "<string>",
    "message": "<string>"
  }
}

{
  "request_id": "<string>",
  "log_id": "<string>",
  "error_code": 123,
  "error_msg": "<string>",
  "error_detail": {
    "status_code": 123,
    "code": "<string>",
    "code_message": "<string>",
    "message": "<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_status`	integer	任务状态：0=排队中，1=处理中，2=已完成，-1=失败
`result`	array	任务结果数组（仅在 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

Show child attributes

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

Query Async Task Results

curl --request GET \
  --url https://api.aihairstyle.cn/common/query-async-task-result \
  --header 'ailabapi-api-key: <api-key>'

const options = {method: 'GET', headers: {'ailabapi-api-key': '<api-key>'}};

fetch('https://api.aihairstyle.cn/common/query-async-task-result', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aihairstyle.cn/common/query-async-task-result",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "ailabapi-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aihairstyle.cn/common/query-async-task-result"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("ailabapi-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.aihairstyle.cn/common/query-async-task-result")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["ailabapi-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "request_id": "<string>",
  "log_id": "<string>",
  "error_code": 123,
  "error_msg": "<string>",
  "error_detail": {
    "status_code": 123,
    "code": "<string>",
    "code_message": "<string>",
    "message": "<string>"
  },
  "result": [
    "<string>"
  ]
}

{
  "request_id": "<string>",
  "log_id": "<string>",
  "error_code": 123,
  "error_msg": "<string>",
  "error_detail": {
    "status_code": 123,
    "code": "<string>",
    "code_message": "<string>",
    "message": "<string>"
  }
}

{
  "request_id": "<string>",
  "log_id": "<string>",
  "error_code": 123,
  "error_msg": "<string>",
  "error_detail": {
    "status_code": 123,
    "code": "<string>",
    "code_message": "<string>",
    "message": "<string>"
  }
}

开始使用

产品介绍

开发指南

API参考

其他

异步任务查询 API

请求

请求头

请求体参数

固定字段

异步任务查询 API

功能特点

应用场景

任务状态说明

响应示例

任务排队中

任务处理中

任务已完成

任务失败

错误响应

响应字段说明

最佳实践

1. 轮询查询

2. 带进度显示的查询

3. 错误处理和重试

注意事项

相关链接

Authorizations

Query Parameters

Response

​请求

​请求头

​请求体参数

​固定字段

​异步任务查询 API

​功能特点

​应用场景

​任务状态说明

​响应示例

​任务排队中

​任务处理中

​任务已完成

​任务失败

​错误响应

​响应字段说明

​最佳实践

​1. 轮询查询

​2. 带进度显示的查询

​3. 错误处理和重试

​注意事项

​相关链接

Authorizations

Query Parameters

Response

请求

请求头

请求体参数

固定字段

异步任务查询 API

功能特点

应用场景

任务状态说明

响应示例

任务排队中

任务处理中

任务已完成

任务失败

错误响应

响应字段说明

最佳实践

1. 轮询查询

2. 带进度显示的查询

3. 错误处理和重试

注意事项

相关链接