Aholo API

Appearance

查询任务状态 ​

根据 taskId 查询任务执行状态和结果。

基本信息 ​

项目值
方法GET
路径/v2/aholo/task/status
认证签名认证（appkey + timestamp + sign）

Request ​

Query Param ​

参数必须类型说明
appkey✅string商家 appkey
timestamp✅string时间戳（毫秒）
sign✅string签名值
appuid❌string第三方用户 ID
taskId✅string任务 ID

签名计算 ​

sign = md5(appsecret + appkey + appuid + timestamp)

如果不需要 appuid：

sign = md5(appsecret + appkey + timestamp)

Example ​

bash
curl -X GET 'https://openapi.kujiale.com/v2/aholo/task/status?appkey=YOUR_APPKEY&timestamp=1485878400000&sign=YOUR_SIGN&taskId=TASK_ID_XXX'
python
import hashlib
import time
import requests

appkey = "YOUR_APPKEY"
appsecret = "YOUR_APPSECRET"
task_id = "TASK_ID_XXX"

timestamp = str(int(time.time() * 1000))
sign_str = appsecret + appkey + timestamp
sign = hashlib.md5(sign_str.encode()).hexdigest()

url = "https://openapi.kujiale.com/v2/aholo/task/status"
params = {
    "appkey": appkey,
    "timestamp": timestamp,
    "sign": sign,
    "taskId": task_id
}

response = requests.get(url, params=params)
print(response.json())

Response ​

处理中（status = 1） ​

json
{
  "c": "0",
  "d": {
    "taskId": "TASK_ID_XXX",
    "status": 1,
    "progress": 50,
    "message": "正在生成3D场景..."
  }
}

完成（status = 3） ​

json
{
  "c": "0",
  "d": {
    "taskId": "TASK_ID_XXX",
    "status": 3,
    "progress": 100,
    "result": {
      "plyPath": "https://holo-cos.aholo3d.cn/.../model.ply",
      "spzPath": "https://holo-cos.aholo3d.cn/.../model.spz",
      "sogPath": "https://holo-cos.aholo3d.cn/.../model.sog"
    }
  }
}

失败（status = 4） ​

json
{
  "c": "0",
  "d": {
    "taskId": "TASK_ID_XXX",
    "status": 4,
    "message": "生成失败: 图片质量问题"
  }
}

字段说明 ​

字段类型说明
taskIdstring任务 ID
statusint任务状态：1处理中, 2部分完成, 3完成, 4失败
progressint进度百分比（0-100）
messagestring状态描述信息
resultobject生成结果（完成时）
result.plyPathstringPLY 文件 URL
result.spzPathstringSPZ 文件 URL（推荐）
result.sogPathstringSOG 文件 URL（推荐用于 Web）

任务状态枚举 ​

Status含义是否终态
0排队中，任务还未被提交否
1结束排队，等待被执行，任务已被提交否
2执行中否
3成功是
4失败是
5取消是
6超时是
7被拒绝是
8预处理中否

轮询建议 ​

  • 间隔：3-5 秒
  • 生成项目：约 30-90 秒
  • 重建项目：约 2-5 分钟
  • 超时：建议 10 分钟，超时后可重试

推荐格式

下载结果时，推荐使用：

  • .spz - 压缩格式，体积小 5-10 倍
  • .sog - 超压缩格式，适合 Web 展示

错误处理 ​

当 status = 4 时，可从 message 中获取失败原因：

  • "图片质量问题" - 建议更换更高质量的图片
  • "模型生成失败" - 可重试一次
  • "超时" - 资源不足，可稍后重试