Authentication认证
| Header请求头 | Meaning含义 |
|---|
x-aholo-api-key | An Aholo key. Takes precedence over AHOLO_API_KEY on the server.Aholo 密钥,优先于服务端的 AHOLO_API_KEY。 |
x-aholo-region | com (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 中注明。
| executionModeexecutionMode | Meaning含义 |
|---|
LIVE_AHOLO_CLOUD_SDK | A real SDK call was made with a key使用密钥发起了真实的 SDK 调用 |
INSTANT_STAGE_BLUEPRINT | No key: a preview response for a Lux3D method无密钥:Lux3D 方法返回预览响应 |
VERIFIED_MANYCORE_CDN_PRESET | No key: a world request answered with a hosted world无密钥:用托管世界响应世界请求 |
Routes接口
| Route接口 | Does作用 |
|---|
GET /api/aholo/status | SDK versions, whether a key is present and where it came from (header, env, none), region, and preset countsSDK 版本、是否有密钥及其来源(header、env、none)、区域,以及预设数量 |
POST /api/aholo/lux3d | Starts 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/world | Starts 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/director | Turns 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字段 |
|---|
textTo3d | prompt, version (G1 or G1-Turbo)prompt、version(G1 或 G1-Turbo) |
imgTo3d | img, version, faceCount (10k to 300k, default 200k), enablePbrimg、version、faceCount(10k 至 300k,默认 200k)、enablePbr |
imageToFourView | img and/or promptimg 和/或 prompt |
multimodalToImage | prompt and/or imgprompt 和/或 img |
partSplit | glbUrl |
articulationAnimation | glbUrl, prompt |
humanoidAutoRig | modelUrl |
humanoidAnimationRetarget | rigModelUrl, animationIds (1 to 10), animationOutputMode (default combined), outFormat (default glb)rigModelUrl、animationIds(1 至 10 个)、animationOutputMode(默认 combined)、outFormat(默认 glb) |
materialTransfer | meshUrl, img (reference image); version is fixed to v3.0-standardmeshUrl、img(参考图);version 固定为 v3.0-standard |
multiFormatExport | modelUrl, 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,不做保存。