跳到主要内容

快速开始

本页帮助你在拿到 API key 后，用几条 curl 命令跑通 世界重建 或 世界生成。

第一步：申请 API key​

  1. 登录 Aholo Labs

    使用 Aholo 账号打开 labs.aholo3d.cn。

  2. 创建并复制密钥

    在 API 密钥页面 按指引生成 API key，妥善保存。

    安全提示

    勿将 API key 写入前端代码、安装包或公开仓库。

第二步：设置请求头​

所有开放平台网关接口（OUS 上传域名上的请求除外）均需携带：

Authorization: <你的 API key>

不要加 Bearer 前缀。更多说明见 授权。

第三步：理解调用流程​

世界类接口均为 异步任务，推荐按以下顺序操作：

步骤做什么主要接口
1上传图片/视频，拿到可访问 URLGET /asset/v1/token，再在 globalDomain 上直传（见 API 侧栏 资产）
2创建重建或生成任务见下表
3用返回的 worldId 轮询状态与产物GET /world/v1/{worldId}
4（可选）分页查看我的任务POST /world/v1/list

在 OUS globalDomain 上调用 /ous/api/... 时使用响应中的 ousToken（Header ous-token-v2），与网关 Authorization 无关。

创建任务用哪个接口？​

能力适用场景方法
世界重建多图（≥20 张）、普通视频或 Insta360 全景（.insv）做 3DGS 重建POST /world/v1/reconstructions
世界生成文案、单图或图文组合生成空间POST /world/v1/generations

创建成功：HTTP 200，响应体为 WorldAsyncOperation，内含 worldId（用于后续 GET .../{worldId} 轮询详情与产物）。

创建失败：返回 ApiError（含 code、message、status；原业务码见 details.metaData.bizCode）。

轮询与产物​

  • 调用 GET /world/v1/{worldId}，查看 status 与可选字段 progress（0.0–1.0），直至 SUCCEEDED、FAILED 等终态。
  • 成功后，assets.splats.urls 可能包含 plyPath、spzPath；若已完成 LOD 后处理，还可能有 lodMetaPath（位于 splats.urls 下，而非 assets 顶层）。
  • AI 生成（Spatial Gen）世界在全景子任务成功后，assets.imagery.panoUrl 返回全景图下载地址。
  • 任务成功且 splat 可用时，assets.semanticsMetadata.upAxis 标明坐标系上轴（Y = glTF/USD；Z = 本服务 3DGS 约定）。
  • createTime / updateTime 为 Unix 毫秒时间戳。

重建与生成要注意什么？​

类型素材要求
重建resources[].url 须公网可访问，扩展名须与 type 一致。图片至少 20 条（type=image 或省略，.jpg/.jpeg/.png/.webp）；普通视频每条 type=video（.mp4/.mov）；Insta360 全景每条 type=insv（.insv）；后两者不触发 20 张图限制。须指定 scene（model/space）与 taskQuality（low/normal/high）；可选 useMask：true 抠图，省略或 false 不抠图
生成纯文案、单张图片或图文组合；图片至多 1 张（.jpg/.jpeg/.png/.webp）。场景上以 室内 更易拿到稳定成片；非室内 仍在 Beta，结果波动可能更大

第四步：复制示例命令​

将下面命令中的 <你的 API key>、<worldId> 和示例 URL 换成真实值。网关基址：https://api.aholo3d.cn。

获取上传凭证（可选，需先上传素材时）​

curl -X GET 'https://api.aholo3d.cn/asset/v1/token' \
  -H 'Authorization: <你的 API key>'

随后在响应 globalDomain 上按 API 资产 分组完成 ousCos* 上传，取得可访问 URL。

创建世界重建​

curl -X POST 'https://api.aholo3d.cn/world/v1/reconstructions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <你的 API key>' \
  -d '{
    "name": "客厅重建",
    "resources": [
      {
        "url": "https://cdn.example.com/input/room-001.jpg",
        "type": "image"
      }
    ],
    "taskQuality": "high",
    "scene": "space",
    "useMask": false
  }'
关于图片数量

示例只展示一条 resources 结构。真实 图片重建 须补全 ≥20 条图片资源（.jpg/.jpeg/.png/.webp），详见 API。

成功时响应示例：

{
  "worldId": "A1b2C3d4E5"
}

创建世界生成​

须至少提供 非空 prompt，或 至多 1 张图片（.jpg/.jpeg/.png/.webp，可与 prompt 组合）。

curl -X POST 'https://api.aholo3d.cn/world/v1/generations' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <你的 API key>' \
  -d '{
    "name": "客厅生成",
    "cover": "https://cdn.example.com/cover/gen-cover.jpg",
    "prompt": "现代简约风格客厅",
    "resources": [
      {
        "url": "https://cdn.example.com/input/room.jpg",
        "type": "image"
      }
    ]
  }'

查询任务状态与产物​

curl -X GET 'https://api.aholo3d.cn/world/v1/<worldId>' \
  -H 'Authorization: <你的 API key>'

分页查询我的世界​

curl -X POST 'https://api.aholo3d.cn/world/v1/list' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <你的 API key>' \
  -d '{
    "pageNum": 0,
    "pageSize": 20,
    "statusList": ["RUNNING", "SUCCEEDED"]
  }'

字段枚举、上传分片细节与错误码请查阅 API 中的 资产 与 世界 分组。若使用 Cursor 等助手自动化调用，可参考 Skills。