TypeScript SDK

Aholo OpenAPI 官方 TypeScript / Node.js SDK。

• 运行要求： Node.js ≥ 18
• GitHub： manycoretech/aholo-spatial-sdk

安装

按需安装，只装你用到的包：

npm install @manycore/aholo-sdk-asset   # 文件上传
npm install @manycore/aholo-sdk-world   # 世界重建与生成
npm install @manycore/aholo-sdk-lux3d  # Lux3D 3D 生成

鉴权

推荐： 通过环境变量设置，SDK 自动读取 AHOLO_API_KEY：

export AHOLO_API_KEY=your_api_key_here

也可在代码中显式传入：

import { createWorldClient } from '@manycore/aholo-sdk-world';

const world = createWorldClient({ apiKey: 'your_api_key_here', region: 'cn' });

安全提示

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

区域

值	说明	API 接入点
cn	中国区	https://api.aholo3d.cn
com	海外区	https://api.aholo3d.com

---

通用上传（Asset）

import { createAssetClient } from '@manycore/aholo-sdk-asset';

const asset = createAssetClient({ region: 'cn' });

上传文件

const result = await asset.uploadFile('./video.mp4');
console.log(result.url); // 公开访问 URL

上传 Buffer

import { readFileSync } from 'node:fs';

const data = readFileSync('./image.jpg');
const result = await asset.uploadBuffer(data, { filename: 'image.jpg' });

带进度回调

const result = await asset.uploadFile('./video.mp4', {
  onProgress: (uploaded, total) => {
    const pct = Math.round((uploaded / total) * 100);
    process.stdout.write(`\r上传进度: ${pct}%`);
  },
});

UploadOptions 参数

参数	类型	说明
filename	string	覆盖文件名（默认取路径 basename）
onProgress	(uploaded: number, total: number) => void	进度回调（字节）
partTimeoutMs	number	每个分块上传超时（默认 120,000 ms）
signal	AbortSignal	取消信号

UploadResult 返回值

字段	类型	说明
url	string	文件公开访问 URL
md5	string	文件 MD5

---

世界（World）

import { createWorldClient } from '@manycore/aholo-sdk-world';

const world = createWorldClient({ region: 'cn' });

3DGS 重建（从视频 / 图像）

const { worldId } = await world.reconstructions.create({
  name: '客厅',
  resources: [{ url: 'https://cdn.example.com/room.mp4', type: 'video' }],
  taskQuality: 'normal', // 'low' | 'normal' | 'high'
  scene: 'model',        // 'model' | 'space'
  useMask: false,        // optional: segment uploaded resources when true
});

const detail = await world.waitFor(worldId);
console.log(detail.assets?.splats?.urls?.plyPath); // PLY 下载 URL

图片重建要求

使用图片重建时，resources 中图片类资源须 ≥ 20 条（type: 'image' 或省略 type）。

3DGS 生成（从文字描述）

const { worldId } = await world.generations.create({
  name: '森林小屋',
  prompt: '森林中的现代风格小木屋',
});

const detail = await world.waitFor(worldId);

查询世界详情

const detail = await world.retrieve(worldId);
console.log(detail.status);

任务状态与轮询

阶段	状态值	说明
进行中	PENDING	排队中
进行中	PREPROCESSING	预处理中
进行中	RUNNING	执行中
成功终态	SUCCEEDED	成功
失败终态	FAILED	失败
失败终态	CANCELED	已取消
失败终态	TIMEOUT	超时
失败终态	REJECTED	被拒绝

world.waitFor(worldId) 轮询直至 SUCCEEDED 并返回 WorldDetail；若进入 FAILED / CANCELED / TIMEOUT / REJECTED，抛出 PollingFailedError。

查询世界列表

const list = await world.list({ pageNum: 1, pageSize: 20 });
list.result?.forEach((w) => console.log(w.worldId, w.status));

WorldDetail 返回值

字段	类型	说明
worldId	string	世界 ID
name	string?	名称
status	string	见上方「任务状态与轮询」
assets.splats.urls.plyPath	string?	PLY 下载 URL
assets.splats.urls.spzPath	string?	SPZ 下载 URL
assets.splats.urls.lodMetaPath	string?	LOD 元数据 URL（若已生成）
assets.imagery.panoUrl	string?	AI 生成全景图 URL（仅 Spatial Gen，全景子任务成功后）
assets.semanticsMetadata.upAxis	"Y" | "Z"?	世界上轴（Y = glTF/USD；Z = 3DGS 约定）
createTime	number?	创建时间（Unix 毫秒）
updateTime	number?	更新时间（Unix 毫秒）

---

Lux3D

import { createLux3dClient } from '@manycore/aholo-sdk-lux3d';

const lux3d = createLux3dClient({ region: 'cn' });

图像转 3D

// 从 URL
const taskId = await lux3d.imgTo3d.create({
  img: 'https://example.com/object.jpg',
  version: 'v2.0-preview', // 'v1.0-pro' | 'v2.0-preview'（默认）
});

// 从本地文件
const taskId2 = await lux3d.imgTo3d.createFromFile('./object.jpg');

const result = await lux3d.tasks.waitFor(taskId);
console.log(result.outputs[0]?.content); // 下载 URL

文字转 3D

const taskId = await lux3d.textTo3d.create({
  prompt: '带雕花腿的木椅',
  // style: 'photorealistic', // 见下方风格列表
});
const result = await lux3d.tasks.waitFor(taskId);

文字转 3D 风格： photorealistic（写实，默认）| cartoon（卡通）| anime（动漫）| hand_painted（手绘）| cyberpunk（赛博朋克）| fantasy（奇幻）| glass（玻璃）

材质迁移

const taskId = await lux3d.materialTransfer.create({
  img: 'https://example.com/material.jpg',
  meshUrl: 'https://example.com/model.glb',
});
const result = await lux3d.tasks.waitFor(taskId);

版本差异

版本	默认	输出格式	说明
v2.0-preview	✓	.zip + .glb + .usdz（3 个文件）	强化文字与纹理细节保持
v1.0-pro		.lux3d（1 个文件）	完整 PBR 材质，支持透明材质

Lux3dTaskResult 返回值

字段	类型	说明
taskId	number	任务 ID
status	0 | 1 | 3 | 4	0 初始化；1 进行中；3 成功；4 失败
outputs	TaskOutput[]	输出文件列表（outputs[n].content 为下载 URL，成功后约 2 小时内有效）

lux3d.tasks.waitFor(taskId) 在 status === 3 时返回；status === 4 时抛出 PollingFailedError。建议每 10–15 秒轮询一次。

---

错误处理

import {
  AuthenticationError,
  RateLimitError,
  BusinessError,
  PollingTimeoutError,
  PollingFailedError,
} from '@manycore/aholo-sdk-core';

try {
  const detail = await world.waitFor(worldId);
} catch (e) {
  if (e instanceof AuthenticationError) {
    console.error('API Key 无效或未设置');
  } else if (e instanceof RateLimitError) {
    console.error('请求频率超限，稍后重试');
  } else if (e instanceof BusinessError) {
    console.error('业务错误:', e.code, e.message);
  } else if (e instanceof PollingTimeoutError) {
    console.error('任务轮询超时');
  } else if (e instanceof PollingFailedError) {
    console.error('任务执行失败:', e.message);
  }
}

错误类型	说明
AuthenticationError	API Key 无效或未设置
RateLimitError	请求频率超限
BusinessError	业务错误（含 code 字段）
PollingTimeoutError	轮询等待超时
PollingFailedError	任务执行失败

更多示例

完整示例见 GitHub examples 目录：

• upload-file.mts — 上传本地文件
• world-reconstruct.mts — 3DGS 重建完整流程
• lux3d-img-to-3d.mts — 图像转 3D

---

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