Aholo API

Appearance

完整工作流程 ​

以下是使用 Aholo API 创建 3D 项目的完整流程。

流程图 ​

mermaid
flowchart TD
    A[1. 获取上传 Token] --> B[2. 上传文件]
    B --> C[3. 创建项目]
    C --> D[4. 查询项目详情获取 taskId]
    D --> E[5. 根据 taskId 查询任务状态]
    E --> F{任务完成?}
    F -->|否| E
    F -->|是| G[6. 获取结果文件]
    G --> H[PLY / SPZ / SOG]

Step 1: 获取上传 Token ​

调用获取上传 Token 接口：

bash
curl -X GET 'https://openapi.kujiale.com/v2/aholo/upload/token?appkey=YOUR_APPKEY&timestamp=1485878400000&sign=YOUR_SIGN&appuid=user123'
json
{
  "c": "0",
  "d": {
    "ousToken": "encrypted_token",
    "globalDomain": "https://ous-cos.kujiale.com",
    "blockSize": 1048576
  }
}

Step 2: 上传文件 ​

根据文件大小选择上传方式：

小文件（< 1MB）单文件上传 ​

使用返回的 Token 上传文件：

bash
curl -X POST '{globalDomain}/ous/api/v2/single/upload' \
  -H 'ous-token-v2: {ousToken}' \
  -F 'file=@/path/to/image.jpg' \
  -F 'md5=file_md5_value'
json
{
  "c": "0",
  "d": {
    "taskId": "upload_task_id"
  }
}

大文件（≥ 1MB）分片上传 ​

分片上传需要三步：

  1. 初始化 - 获取分片任务 ID
  2. 分片上传 - 上传各个分片
  3. 查询状态 - 等待合并完成

详见 分片上传

轮询上传状态 ​

轮询直到 status 为 5（成功）：

bash
curl -X GET '{globalDomain}/ous/api/v2/upload/status' \
  -H 'ous-token-v2: {ousToken}'
json
{
  "c": "0",
  "d": {
    "status": 5,
    "url": "https://.../image.jpg",
    "uploadKey": "file_key"
  }
}

Step 3: 创建项目 ​

使用上传的资源 URL 创建 3D 项目：

bash
curl -X POST 'https://openapi.kujiale.com/v2/aholo/project/create-3d-gen?appkey=YOUR_APPKEY&timestamp=1485878400000&sign=YOUR_SIGN&appuid=user123' \
  -H 'Content-Type: application/json' \
  -d '{
    "projectName": "客厅场景",
    "prompt": "还原该空间",
    "resources": [{
      "name": "客厅.jpg",
      "type": 0,
      "url": "https://.../image.jpg"
    }]
  }'
json
{
  "c": "0",
  "d": "3FO4K4W7ID9F"
}

返回的 d 即为 projectId。

Step 4: 查询项目详情获取 taskId ​

通过 projectId 查询项目详情，获取 taskId：

bash
curl -X GET 'https://openapi.kujiale.com/v2/aholo/project/info?appkey=YOUR_APPKEY&timestamp=1485878400000&sign=YOUR_SIGN&appuid=user123&projectId=3FO4K4W7ID9F'
json
{
  "c": "0",
  "d": {
    "projectId": "3FO4K4W7ID9F",
    "name": "客厅场景",
    "task": {
      "taskId": "TASK_ID_XXX"
    }
  }
}

从 d.task.taskId 获取任务 ID。

Step 5: 根据 taskId 查询任务状态 ​

轮询任务状态直到完成：

bash
curl -X GET 'https://openapi.kujiale.com/v2/aholo/task/status?appkey=YOUR_APPKEY&timestamp=1485878400000&sign=YOUR_SIGN&appuid=user123&taskId=TASK_ID_XXX'
json
{
  "c": "0",
  "d": {
    "taskId": "TASK_ID_XXX",
    "status": 1,
    "progress": 50
  }
}
json
{
  "c": "0",
  "d": {
    "taskId": "TASK_ID_XXX",
    "status": 3,
    "result": {
      "plyPath": "https://.../model.ply",
      "spzPath": "https://.../model.spz",
      "sogPath": "https://.../model.sog"
    }
  }
}

Step 6: 使用结果文件 ​

任务完成后，你可以下载以下格式的 3D 文件：

格式说明
.ply标准 3D Gaussian Splatting 格式
.spz压缩格式，体积小 5-10 倍
.sog超压缩格式，适合 Web 展示

推荐

使用 .spz 或 .sog 格式可以获得更好的加载性能。

状态码说明 ​

上传状态 ​

Status含义终态
0草稿否
4上传中否
5上传成功✅
6上传失败✅
8手动中止✅

项目任务状态 ​

Status含义
0初始化
1处理中
2部分完成
3完成 ✅
4失败

注意

轮询间隔建议 200ms 以上，不要过于频繁请求。