HTTP API

The studio talks to Aholo only through these routes. They live under /api/aholo/*, run on the server, and call the official SDKs with either the server key or the caller's x-aholo-api-key header. Any client can use them the same way.创作台只通过这些接口与 Aholo 通信。它们位于 /api/aholo/* 下,在服务端运行,使用服务端密钥或调用方的 x-aholo-api-key 请求头调用官方 SDK。任何客户端都可以用同样的方式调用它们。

Authentication认证

Header请求头Meaning含义
x-aholo-api-keyAn Aholo key. Takes precedence over AHOLO_API_KEY on the server.Aholo 密钥,优先于服务端的 AHOLO_API_KEY。
x-aholo-regioncom (api.aholo.ai, default) or cn (api.aholo.cn). Falls back to AHOLO_REGION.com(api.aholo.ai,默认)或 cn(api.aholo.cn)。未提供时回退到 AHOLO_REGION。

With no key from either source, routes answer without calling Aholo and say so in executionMode.两种来源都没有密钥时,接口不调用 Aholo 直接返回响应,并在 executionMode 中注明。

executionModeexecutionModeMeaning含义
LIVE_AHOLO_CLOUD_SDKA real SDK call was made with a key使用密钥发起了真实的 SDK 调用
INSTANT_STAGE_BLUEPRINTNo key: a preview response for a Lux3D method无密钥:Lux3D 方法返回预览响应
VERIFIED_MANYCORE_CDN_PRESETNo key: a world request answered with a hosted world无密钥:用托管世界响应世界请求

Routes接口

Route接口Does作用
GET /api/aholo/statusSDK versions, whether a key is present and where it came from (header, env, none), region, and preset countsSDK 版本、是否有密钥及其来源(header、env、none)、区域,以及预设数量
POST /api/aholo/lux3dStarts any of the ten Lux3D methods; returns a task ID启动十个 Lux3D 方法中的任意一个,返回任务 ID
GET /api/aholo/tasks?taskId= retrieves one Lux3D task; with no query, lists the 15 most recent带 ?taskId= 时查询单个 Lux3D 任务;不带查询参数时列出最近的 15 个任务
POST /api/aholo/worldStarts a SpatialGen generation or an Aholo Reality reconstruction启动 SpatialGen 世界生成或 Aholo Reality 重建
GET /api/aholo/world?worldId= retrieves one world; with no query, returns the hosted presets and your 10 latest worlds带 ?worldId= 时查询单个世界;不带查询参数时返回托管预设和你最近的 10 个世界
POST /api/aholo/directorTurns a brief into an ordered MCP tool plan and a stage mutation把一段描述转成按顺序排列的 MCP 工具计划,以及一次舞台变更
GET /api/aholo/asset?url= streams a result file from an allowlisted Aholo host带 ?url=,从白名单内的 Aholo 主机流式传输结果文件

POST /api/aholo/lux3d

The body names an operation plus that method's fields. Operations: textTo3d, imgTo3d, imageToFourView, multimodalToImage, partSplit, articulationAnimation, humanoidAutoRig, humanoidAnimationRetarget, materialTransfer, multiFormatExport.请求体包含 operation 以及该方法对应的字段。可用的 operation:textTo3d、imgTo3d、imageToFourView、multimodalToImage、partSplit、articulationAnimation、humanoidAutoRig、humanoidAnimationRetarget、materialTransfer、multiFormatExport。

request
curl -X POST http://localhost:3010/api/aholo/lux3d \
  -H 'content-type: application/json' \
  -H 'x-aholo-api-key: <your key>' \
  -d '{"operation":"textTo3d","prompt":"A brass desk lamp","version":"G1-Turbo"}'
response
{
  "ok": true,
  "executionMode": "LIVE_AHOLO_CLOUD_SDK",
  "sdkMethod": "lux3d.textTo3d.create",
  "taskId": 8353472,
  "status": 1
}

Fields by operation各 operation 的字段

Operation操作Fields字段
textTo3dprompt, version (G1 or G1-Turbo)prompt、version(G1 或 G1-Turbo)
imgTo3dimg, version, faceCount (10k to 300k, default 200k), enablePbrimg、version、faceCount(10k 至 300k,默认 200k)、enablePbr
imageToFourViewimg and/or promptimg 和/或 prompt
multimodalToImageprompt and/or imgprompt 和/或 img
partSplitglbUrl
articulationAnimationglbUrl, prompt
humanoidAutoRigmodelUrl
humanoidAnimationRetargetrigModelUrl, animationIds (1 to 10), animationOutputMode (default combined), outFormat (default glb)rigModelUrl、animationIds(1 至 10 个)、animationOutputMode(默认 combined)、outFormat(默认 glb)
materialTransfermeshUrl, img (reference image); version is fixed to v3.0-standardmeshUrl、img(参考图);version 固定为 v3.0-standard
multiFormatExportmodelUrl, outputFormat: any of usdz, fbx_zip, obj_zip, stl, 3mfmodelUrl、outputFormat:可选 usdz、fbx_zip、obj_zip、stl、3mf

POST /api/aholo/world

generate
{ "action": "generate", "prompt": "A cozy Scandinavian coffee bar ...", "imageUrl": "https://..." }
reconstruct
{
  "action": "reconstruct",
  "resources": [{ "url": "https://.../walkthrough.mp4", "type": "video" }],
  "scene": "space",            // or "model"
  "taskQuality": "normal",     // low | normal | high
  "useMask": false
}

GET /api/aholo/asset

Lux3D result files live on hosts that do not send CORS headers, so the studio loads them through this proxy. It is deliberately narrow:Lux3D 结果文件所在的主机不返回 CORS 响应头,所以创作台通过这个代理加载它们。代理的放行范围刻意收得很窄:

Rule规则Value取值
Scheme协议https only, no credentials in the URL, port 443仅限 https,URL 中不得携带凭据,端口 443
Hosts主机holo-cos.aholo3d.cn, and kujiale.com, myqcloud.com, aholo.ai, aholo.cn with their subdomainsholo-cos.aholo3d.cn,以及 kujiale.com、myqcloud.com、aholo.ai、aholo.cn 及其子域名
Redirects重定向At most 3, and every hop is checked against the same allowlist最多 3 次,每一跳都按同一份白名单校验
Limits限制60 s timeout, 120 MB per file (declared and streamed)超时 60 s,单个文件上限 120 MB(声明大小和实际传输量都会检查)

See the source in src/app/api/aholo/asset/route.ts. Status and key handling are in src/lib/aholo-server.ts; for the deploy settings, read Self-hosting.源码见 src/app/api/aholo/asset/route.ts。状态与密钥处理在 src/lib/aholo-server.ts 中;部署设置请阅读自托管与部署。

Keys never reach the browser from the server. A key the user pastes is sent only to Holorra's own routes, which pass it to the Aholo SDK for that one request and do not store it.服务端的密钥永远不会发送到浏览器。用户粘贴的密钥只会发往 Holorra 自己的接口,接口仅在该次请求中把它交给 Aholo SDK,不做保存。