SDK 概览

Aholo 提供三种语言的官方 SDK，封装了鉴权、分块上传、任务轮询等细节，让你无需手写 HTTP 即可快速接入。

GitHub：manycoretech/aholo-spatial-sdk

能力矩阵

能力	TypeScript	Java	Python
通用上传（Asset）	✅	✅	✅
世界（World）	✅	✅	✅
Lux3D	✅	✅	✅
渲染云（RenderCloud）	—	—	—

渲染云暂无 SDK 封装，请直接参考 API Reference 中的渲染云接口文档。

版本说明： Lux3D SDK 当前最新为 v1.7.0（TypeScript / Java / Python），新增多模态生图，四视图支持文案，多格式导出增加 STL/3MF；生成版本为 G1 / G1-Turbo。World 为 v1.3.0；Asset、core 仍为 v1.2.0。MCP 为 @manycore/aholo-sdk-mcp@1.7.0。

快速安装

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.3.0</version>
</dependency>
<dependency>
  <groupId>com.manycoreapis</groupId>
  <artifactId>aholo-sdk-lux3d</artifactId>
  <version>1.7.0</version>
</dependency>

# 按需安装，选你用到的包
pip install manycore-aholo-sdk-asset
pip install manycore-aholo-sdk-world
pip install manycore-aholo-sdk-lux3d

包列表

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

包名	PyPI
`manycore-aholo-sdk-asset`
`manycore-aholo-sdk-world`
`manycore-aholo-sdk-lux3d`
`manycore-aholo-sdk-core`

鉴权

所有 SDK 均通过以下方式读取 API Key：

推荐： 环境变量（SDK 自动读取 AHOLO_API_KEY）

export AHOLO_API_KEY=your_api_key_here

也可在代码中显式传入，见各语言详细文档。

安全提示

请勿将 API Key 硬编码到源代码、安装包或公开仓库中。

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`	失败
`6`	已取消

图生/文生 3D 支持 zip / glb / ply；材质迁移支持 zip / glb / usdz / obj zip / fbx zip；多格式导出支持 usdz / obj zip / fbx zip / stl / 3mf。

tasks.waitFor(taskId) 在 status === 3 时返回；status === 4 或 6 时抛出轮询失败错误。

详细文档

GitHub README 仅作安装说明。若与本文冲突，以本文为准。源码与可运行示例见 GitHub。

能力矩阵​

快速安装​

包列表​

TypeScript / Node.js​

Java​

Python​

鉴权​

区域​

异步任务与状态​

World 任务状态​

Lux3D 任务状态​

详细文档​