AHOLO World Open API (OpenAPI 3.0.3, info.version=1.0.0)

This file is auto-generated alongside openapi.en.yaml / openapi.en.json on every build. If docs conflict, the OpenAPI spec is authoritative.

Documentation home:
- https://labs.aholo.ai/api-docs/en/

Machine-readable API specs (aggregate):
- OpenAPI YAML (all services): https://labs.aholo.ai/api-docs/openapi.en.yaml
- OpenAPI JSON (all services): https://labs.aholo.ai/api-docs/openapi.en.json

Machine-readable API specs (per service):
- asset service (upload credentials & OUS):
  - YAML: https://labs.aholo.ai/api-docs/specifications/services/asset/openapi.en.yaml
  - JSON: https://labs.aholo.ai/api-docs/specifications/services/asset/openapi.en.json
- world (reconstruction, generation):
  - YAML: https://labs.aholo.ai/api-docs/specifications/services/world/openapi.en.yaml
  - JSON: https://labs.aholo.ai/api-docs/specifications/services/world/openapi.en.json
- lux3d service:
  - YAML: https://labs.aholo.ai/api-docs/specifications/services/lux3d/openapi.en.yaml
  - JSON: https://labs.aholo.ai/api-docs/specifications/services/lux3d/openapi.en.json
- rendercloud service:
  - YAML: https://labs.aholo.ai/api-docs/specifications/services/rendercloud/openapi.en.yaml
  - JSON: https://labs.aholo.ai/api-docs/specifications/services/rendercloud/openapi.en.json
- spatial understanding (SpatialLM tasks):
  - YAML: https://labs.aholo.ai/api-docs/specifications/services/spatialunderstanding/openapi.en.yaml
  - JSON: https://labs.aholo.ai/api-docs/specifications/services/spatialunderstanding/openapi.en.json

OpenAPI info (one-line summary):
- AHOLO OpenAPI documentation focused on world reconstruction and world generation (Spatial Gen): start 3D Gaussian Splatting (3DGS) world reconstruction from images or videos, or generate worlds from text and/or images, then poll details and paginate lists by worldId. Send Authorization as required (see each operation’s security definitions). The default gateway is under Servers. The sidebar groups operations by service (Asset, World, Lux3D, Render Cloud), then by tags within each service. Spatial understanding is a tag inside World, not its own service.

Servers (matches openapi.en.yaml):
  - https://api.aholo.ai (Aholo Open Platform HTTPS entry (International))

Sidebar Tags (matches openapi.en.yaml):
  - Asset
  - World
  - Lux3D
  - RenderCloudOpenUSDGuide
  - RenderCloud
  - SpatialUnderstanding

Aggregated operationId index (see openapi.en.yaml for full details):
  - closeRenderCloudRealtimeStream  (DELETE /global/rendercloud/v1/streams/{sessionId})
  - createArticulationAnimationTaskGlobal  (POST /global/lux3d/v1/articulation-animation/task/create)
  - createHumanoidAnimationRetargetTask  (POST /global/lux3d/v1/animations/retarget/task/create)
  - createHumanoidAutoRigTask  (POST /global/lux3d/v1/animations/rig/task/create)
  - createImageToFourViewTaskGlobal  (POST /global/lux3d/v1/generate/image-to-four-view/task/create)
  - createImgTo3dTaskGlobal  (POST /global/lux3d/v1/generate/img-to-3d/task/create)
  - createMaterialTransferTaskGlobal  (POST /global/lux3d/v1/generate/material-transfer/task/create)
  - createMeshUploadAndProcessTask  (POST /global/rendercloud/v1/mesh-upload-process/task/create)
  - createMultiFormatExportTaskGlobal  (POST /global/lux3d/v1/multi-format-export/task/create)
  - createMultimodalToImageTaskGlobal  (POST /global/lux3d/v1/generate/multimodal-to-image/task/create)
  - createPartSplitTaskGlobal  (POST /global/lux3d/v1/part-split/task/create)
  - createRenderCloudRealtimeStream  (POST /global/rendercloud/v1/streams)
  - createSpatialUnderstandingTask  (POST /global/spatial-understanding/v1/tasks)
  - createTextTo3dTaskGlobal  (POST /global/lux3d/v1/generate/text-to-3d/task/create)
  - createWorld  (POST /global/world/v1/reconstructions)
  - generateWorld  (POST /global/world/v1/generations)
  - getMySpatialUnderstandingTaskList  (POST /global/spatial-understanding/v1/tasks/list)
  - getMyWorldList  (POST /global/world/v1/list)
  - getRenderCloudInstanceInAholo  (GET /global/rendercloud/v1/mesh-upload-process/task/get)
  - getSpatialUnderstandingTaskDetail  (GET /global/spatial-understanding/v1/tasks/{taskId})
  - getTaskGlobal  (GET /global/lux3d/v1/generate/task/get)
  - getUploadToken  (GET /global/asset/v1/token)
  - getWorldDetail  (GET /global/world/v1/{worldId})
  - listTasksGlobal  (GET /global/lux3d/v1/generate/task/list)
  - ousCosBlockUploadInit  (POST /ous/api/v2/block/upload/init)
  - ousCosBlockUploadPart  (POST /ous/api/v2/block/upload/part)
  - ousCosSingleUpload  (POST /ous/api/v2/single/upload)
  - ousCosUploadStatus  (GET /ous/api/v2/upload/status)
  - pushRenderCloudRealtimeStreamUpdate  (POST /global/rendercloud/v1/streams/{sessionId}:push)
  - runRenderCloudOfflineJob  (POST /global/rendercloud/v1/jobs)

Reference docs (Docusaurus):
- Introduction: https://labs.aholo.ai/api-docs/en/intro
- Quick Start: https://labs.aholo.ai/api-docs/en/quickstart
- Agent Skills index: https://labs.aholo.ai/api-docs/en/skills
- Skill aholo-3dgs-reconstruction: https://labs.aholo.ai/api-docs/en/skills/aholo-3dgs-reconstruction
- Skill Lux3D: https://labs.aholo.ai/api-docs/en/skills/lux3d
- Authentication: https://labs.aholo.ai/api-docs/en/authentication
- Interactive API: https://labs.aholo.ai/api-docs/en/api-reference/

Official SDKs (canonical; prefer over GitHub README):
- SDK overview: https://labs.aholo.ai/api-docs/en/sdk
- TypeScript SDK: https://labs.aholo.ai/api-docs/en/sdk/typescript
- Java SDK: https://labs.aholo.ai/api-docs/en/sdk/java
- Python SDK: https://labs.aholo.ai/api-docs/en/sdk/python

SDK source (secondary; use for runnable examples only):
- GitHub: https://github.com/manycoretech/aholo-spatial-sdk
- TS examples: https://github.com/manycoretech/aholo-spatial-sdk/tree/main/typescript/examples
- Java examples: https://github.com/manycoretech/aholo-spatial-sdk/tree/main/java/examples

SDK capability matrix:
- Asset (upload): TypeScript ✅ | Java ✅ | Python ✅
- World (3DGS recon/gen): TypeScript ✅ | Java ✅ | Python ✅
- Lux3D (image-to-four-view, image/text-to-3D, material transfer, multi-format export, part split, articulation, humanoid rig/retarget, task history): TypeScript ✅ | Java ✅ | Python ✅
- RenderCloud: no SDK; use OpenAPI directly

SDK auth (same as REST):
- Env var AHOLO_API_KEY; or pass apiKey in client config
- region cn → https://api.aholo3d.cn | com → https://api.aholo.ai

SDK install (install only what you need):
- TypeScript: npm install @manycore/aholo-sdk-asset | @manycore/aholo-sdk-world | @manycore/aholo-sdk-lux3d
- Java: com.manycoreapis:aholo-sdk-asset | aholo-sdk-world | aholo-sdk-lux3d (Maven Central)
- Python: pip install manycore-aholo-sdk-asset | manycore-aholo-sdk-world | manycore-aholo-sdk-lux3d

SDK call chains (TypeScript method names; Java is analogous):
- Upload: createAssetClient → uploadFile → result.url
- World recon: uploadFile → world.reconstructions.create → world.waitFor(worldId) → assets.splats.urls
- World gen: world.generations.create → world.waitFor(worldId)
- Lux3D generation: lux3d.imgTo3d.create({ img, version: "G1" }) → lux3d.tasks.waitFor(taskId) → outputs[n].content
- Lux3D additional APIs: multimodalToImage.create | imageToFourView.create | materialTransfer.create | multiFormatExport.create | partSplit.create | articulationAnimation.create | humanoidAutoRig.create | humanoidAnimationRetarget.create
- Lux3D task history: lux3d.tasks.list({ page, pageSize, status, startTime, endTime })

SDK constraints (agents must read):
- World/Lux3D are async: always poll after create (waitFor / tasks.waitFor)
- World status in-progress: PENDING | PREPROCESSING | RUNNING; success: SUCCEEDED; failure: FAILED | CANCELED | TIMEOUT | REJECTED
- Lux3D task status: 0 init | 1 running | 3 success | 4 failed | 6 canceled
- Lux3D generation requires version G1 or G1-Turbo; faceCount 10000–300000; outputFormat supports zip/glb/ply; aiPredictSize controls size prediction
- Image recon: ≥20 images (type=image or omit; .jpg/.jpeg/.png/.webp), or video type=video (.mp4/.mov), or Insta360 type=insv (.insv); extension must match type
- World gen: text-only, one image, or both; at most 1 image (.jpg/.jpeg/.png/.webp)
- Large uploads: SDK handles multipart; no manual OUS flow needed
- Errors: AuthenticationError | RateLimitError | BusinessError | PollingTimeoutError | PollingFailedError

Agent routing (SDK vs REST):
- App integration code → prefer SDK docs under /en/sdk/*; do not hand-write HTTP
- Field-level API details / error codes → OpenAPI or /en/api-reference/
- RenderCloud → OpenAPI only, no SDK
- If SDK docs conflict with GitHub README, /en/sdk/* wins

Authentication:
- Gateway: set Authorization header to your API key (no Bearer prefix). See openapi.en.yaml components.securitySchemes.
- Upload (OUS): use Authorization to get an upload token via GET /asset/v1/token; then use ous-token-v2 for requests to the OUS globalDomain — independent of the gateway Authorization.
- If docs conflict, openapi.en.yaml and the Authentication page are authoritative.

Agent routing hints:
- For tasks spanning multiple services, use the aggregate OpenAPI.
- For single-service tasks, prefer the per-service openapi.en.yaml.
- If aggregate and per-service specs conflict, the per-service spec wins.

Data conventions:
- Enum inputs use lowercase (except status values which use UPPER_CASE).
- createTime / updateTime in World responses are Unix millisecond timestamps.

Reliability hints:
- Use operationId to identify actions.
- Validate required fields and enum values before calling.
- Async flows: create task → poll until terminal state.
- On 429 or transient 5xx: exponential backoff with a cap.
- On 401: verify API key and retry once.

Typical call chains:
- World reconstruction: createWorld → getWorldDetail (poll until terminal).
- World generation: generateWorld → getWorldDetail (poll until terminal).
- World list: getMyWorldList → getWorldDetail.

Notes:
- Only published APIs are included.