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.aholo.cn |
通用上传(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, type WorldResourceItem, type WorldResourceType } from '@manycore/aholo-sdk-world';
const world = createWorldClient({ region: 'cn' });
重建 resources 使用 WorldResourceItem,type 为 WorldResourceType(image | video | insv)。生成 resources 使用 GenerateWorldResourceItem(仅 image,至多 1 条)。v1.3.0 起支持 Insta360 全景 type: 'insv'。
3DGS 重建(从视频 / 图像)
const { worldId } = await world.reconstructions.create({
name: '客厅',
resources: [{ url: 'https://cdn.example.com/room.mp4', type: 'video' }], // type: 'video' | 'image' | 'insv'
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' 或省略,.jpg/.jpeg/.png/.webp)。普通视频用 type: 'video'(.mp4/.mov);Insta360 全景用 type: 'insv'(.insv)。URL 扩展名须与 type 一致。
Insta360 示例:
const { worldId } = await world.reconstructions.create({
name: '全景客厅',
resources: [{ url: 'https://cdn.example.com/room.insv', type: 'insv' }],
taskQuality: 'high',
scene: 'space',
});
3DGS 生成(从文字描述)
生成接口 resources 仅支持图片(type: 'image',至多 1 张,扩展名 .jpg/.jpeg/.png/.webp),不支持 video / insv。
const { worldId } = await world.generations.create({
name: '森林小屋',
prompt: '森林中的现代风格小木屋',
// resources: [{ url: 'https://cdn.example.com/ref.jpg', type: 'image' }], // 可选,至多 1 张
});
const detail = await world.waitFor(worldId);
查询世界详情
const detail = await world.retrieve(worldId);
console.log(detail.status);