SDK 概览
Aholo 提供三种语言的官方 SDK，封装了鉴权、分块上传、任务轮询等细节，让你无需手写 HTTP 即可快速接入。
能力矩阵
| 能力 | TypeScript | Java | Python |
|---|---|---|---|
| 通用上传（Asset） | ✅ | ✅ | 🚧 |
| 世界（World） | ✅ | ✅ | 🚧 |
| Lux3D | ✅ | ✅ | 🚧 |
| 渲染云（RenderCloud） | — | — | — |
渲染云暂无 SDK 封装，请直接参考 API Reference 中的渲染云接口文档。
快速安装
- TypeScript
- Java
- Python
# 按需安装，选你用到的包
npm install @manycore/aholo-sdk-asset
npm install @manycore/aholo-sdk-world
npm install @manycore/aholo-sdk-lux3d
<!-- pom.xml，按需添加 -->
<dependency>
<groupId>com.manycoreapis</groupId>
<artifactId>aholo-sdk-asset</artifactId>
<version>1.2.0</version>
</dependency>
<dependency>
<groupId>com.manycoreapis</groupId>
<artifactId>aholo-sdk-world</artifactId>
<version>1.2.0</version>
</dependency>
<dependency>
<groupId>com.manycoreapis</groupId>
<artifactId>aholo-sdk-lux3d</artifactId>
<version>1.2.0</version>
</dependency>
Python SDK 即将发布
Python SDK 正在开发中，敬请期待。可前往 GitHub 关注进度。
包列表
TypeScript / Node.js
运行要求： Node.js ≥ 18
| 包名 | npm |
|---|---|
@manycore/aholo-sdk-asset |  |
@manycore/aholo-sdk-world |  |
@manycore/aholo-sdk-lux3d |  |
@manycore/aholo-sdk-core |  |
Java
运行要求： Java 8+，Maven ≥ 3.6（从源码构建推荐使用 JDK 17 或 21）
| Artifact | Maven Central |
|---|---|
com.manycoreapis:aholo-sdk-asset | 查看 |
com.manycoreapis:aholo-sdk-world | 查看 |
com.manycoreapis:aholo-sdk-lux3d | 查看 |
com.manycoreapis:aholo-sdk-core | 查看 |
Python（即将发布）
运行要求： Python ≥ 3.9
| 包名 | 说明 |
|---|---|
manycore-aholo-sdk-asset | 文件上传 |
manycore-aholo-sdk-world | 世界重建与生成 |
manycore-aholo-sdk-lux3d | Lux3D 生成 |
鉴权
所有 SDK 均通过以下方式读取 API Key：
推荐： 环境变量（SDK 自动读取 AHOLO_API_KEY）
export AHOLO_API_KEY=your_api_key_here
也可在代码中显式传入，见各语言详细文档。
安全提示
请勿将 API Key 硬编码到源代码、安装 包或公开仓库中。
区域
| 值 | 说明 | API 接入点 |
|---|---|---|
cn | 中国区 | https://api.aholo3d.cn |
com | 海外区 | https://api.aholo3d.com |
异步任务与状态
World 与 Lux3D 均为异步任务：创建后须轮询，直至进入终态。各语言 SDK 提供 waitFor / tasks.waitFor 封装轮询。
World 任务状态
| 阶段 | 状态值 | 说明 |
|---|---|---|
| 进行中 | PENDING | 排队中 |
| 进行中 | PREPROCESSING | 预处理中 |
| 进行中 | RUNNING | 执行中 |
| 成功终态 | SUCCEEDED | 成功，可读取 assets.splats.urls（含 lodMetaPath）、assets.imagery.panoUrl（生成）、assets.semanticsMetadata.upAxis |
| 失败终态 | FAILED | 失败 |
| 失败终态 | CANCELED | 已取消 |
| 失败终态 | TIMEOUT | 超时 |
| 失败终态 | REJECTED | 被拒绝 |
waitFor(worldId) 在 SUCCEEDED 时返回详情；遇到失败终态时抛出 PollingFailedError（Java 为 AholoException）。
Lux3D 任务状态
| 值 | 说明 |
|---|---|
0 | 初始化 |
1 | 进行中 |
3 | 成功（outputs[n].content 为下载 URL，有效期约 2 小时） |
4 | 失败 |
tasks.waitFor(taskId) 在 status === 3 时返回；status === 4 时抛出轮询失败错误。
详细文档
GitHub README 仅作安装说明。若与本文冲突，以本文为准。源码与可运行示例见 GitHub。