openapi: 3.0.3 info: title: AHOLO World Open API version: 1.0.0 description: >- 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. x-scalar-sdk-installation: - lang: TypeScript description: 'Install from npm. Full docs: https://labs.aholo.ai/api-docs/en/sdk/typescript' source: npm install @manycore/aholo-sdk-asset @manycore/aholo-sdk-world @manycore/aholo-sdk-lux3d - lang: Java description: 'Java 8+. Maven Central `com.manycoreapis:aholo-sdk-*`. Full docs: https://labs.aholo.ai/api-docs/en/sdk/java' source: |- com.manycoreapis aholo-sdk-world 1.3.0 - lang: Python description: 'Python 3.9+. PyPI `manycore-aholo-sdk-*`. Full docs: https://labs.aholo.ai/api-docs/en/sdk/python' source: pip install manycore-aholo-sdk-asset manycore-aholo-sdk-world manycore-aholo-sdk-lux3d servers: - url: https://api.aholo.ai description: Aholo Open Platform HTTPS entry (International) tags: - name: Asset description: >- After you obtain an OUS token, run `ousCos*` direct-upload steps on `globalDomain` (COS) under this tag, then use the public URL in downstream business APIs. - name: World description: 3D Gaussian Splatting world reconstruction APIs - name: Lux3D description: Asynchronous image generation, 3D generation, model processing, format export, and task-query APIs. x-displayName: Lux3D 3D Generation - name: RenderCloudOpenUSDGuide x-displayName: RenderCloud OpenUSD Format Guide description: > This documentation entry explains the OpenUSD/USDA format accepted by `usdContent`. `usdContent` must be transmitted as: ```text usdContent = Base64(UTF-8(USDA text)) ``` Files should start with `#usda 1.0` and use UTF-8 encoding. The service parses cameras, external asset references, and render settings from the scene. Unsupported Prim types or attributes are ignored; syntax errors cause the job or session to fail. ## Use Cases | Scenario | API | `usdContent` | Description | |----------|-----|--------------|-------------| | Offline render submit | `POST /global/rendercloud/v1/jobs` | Full USDA scene | Parses camera, Mesh, 3DGS, and RenderSettings, then starts offline rendering | | Realtime render creation | `POST /global/rendercloud/v1/streams` | Full USDA scene | Parses the full scene and creates a realtime rendering stream | | Realtime render patch | `POST /global/rendercloud/v1/streams/{sessionId}:push` | Patch USDA using `over` | Separately updates cameras, models, lights, and environment light | ## Recommended Top-Level Structure ```usda #usda 1.0 ( defaultPrim = "World" ) def Xform "World" { def Xform "MeshModel1" { ... } def Xform "Cameras" { def Camera "MainCamera" { ... } } def Xform "Lights" { def RectLight "KeyRect" { ... } def SphereLight "FillPoint" { ... } } } def Scope "Render" { def RenderSettings "MainRenderSettings" { custom float3 manycore:environment:giIntensity = (1, 1, 1) } } ``` Use `def` for full scenes. Use `over` for realtime patch updates. ## Stage Metadata | Field | Type | Required | Description | |-------|------|----------|-------------| | `defaultPrim` | `token` string | No | Default root Prim name, for example `"World"` | | `doc` | Triple-quoted string | No | Documentation text; retained after parsing and not used for rendering | | `upAxis` | `token` string | No | Optional documentation metadata; does not change the cloud-renderer axis | | `metersPerUnit` | Floating-point number | No | Optional documentation metadata; does not change the cloud-renderer unit | Cloud rendering is always Z-up and always treats **1 unit as 1 millimeter**. Users do not need to set `upAxis` or `metersPerUnit`; when present, these Stage fields are read only as documentation metadata and do not trigger coordinate or light-size conversion. ## Xform `def Xform` wraps models or cameras and applies transform matrices to child Prims. | Attribute | USDA Type | Required | Description | |-----------|-----------|----------|-------------| | `matrix4d xformOp:transform` | `matrix4d` | No | 4x4 transform matrix | | `uniform token[] xformOpOrder` | `token[]` | No | Recommended value: `["xformOp:transform"]` | The matrix follows the USD row-vector convention. Translation is stored in the fourth row: ```usda matrix4d xformOp:transform = ( (m00, m01, m02, m03), (m10, m11, m12, m13), (m20, m21, m22, m23), (m30, m31, m32, m33) ) ``` ## External Assets Mesh: ```usda def Mesh "myMesh" ( payload = @manycore:/mesh/{meshId}@ ) { } ``` 3D Gaussian Splatting: ```usda def ParticleField3DGaussianSplat "MyGaussianSplat" ( payload = @manycore:/mesh/{meshId}@ ) { } ``` The `assetPath` in `payload` references an uploaded asset. `meshId` is taken from the final path segment. To keep the format explicit and consistent, every example in this guide uses a target Prim path: `Mesh` uses `@manycore:/mesh/{meshId}@` and 3DGS uses `@manycore:/mesh/{meshId}@`; bare asset IDs are not used. ## Camera Full scenes use the first camera found during traversal. Realtime **camera patches** use the first `over` node containing camera attributes; this rule does not apply to model, light, or environment-light patches. | Attribute | USDA Type | Required | Description | |-----------|-----------|----------|-------------| | `token projection` | `token` | No | Projection type, for example `"perspective"` | | `float2 clippingRange` | `(near, far)` | No | Near and far clipping planes | | `float focalLength` | `float` | No | Focal length in mm | | `float focusDistance` | `float` | No | Focus distance | | `float fStop` | `float` | No | Aperture f-number | | `float horizontalAperture` | `float` | No | Horizontal aperture in mm | | `float verticalAperture` | `float` | No | Vertical aperture in mm | | `matrix4d xformOp:transform` | `matrix4d` | No | Camera pose | | `uniform token[] xformOpOrder` | `token[]` | No | Recommended value: `["xformOp:transform"]` | Example: ```usda def Camera "MainCamera" { float2 clippingRange = (0.1, 1000) float focalLength = 28 float fStop = 0 float horizontalAperture = 24.447495 float verticalAperture = 13.7517 token projection = "perspective" matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (0, 0, 8.0, 1) ) uniform token[] xformOpOrder = ["xformOp:transform"] } ``` ## RenderSettings `def RenderSettings` should be placed under `def Scope "Render"`. | Attribute | USDA Type | Required | Description | |-----------|-----------|----------|-------------| | `rel camera` | Prim path | No | Active camera path, for example `` | | `int2 resolution` | `(width, height)` | Required for offline rendering | Output resolution | Offline rendering reads the output resolution from `RenderSettings.resolution`, with Camera `resolution` supported as a compatibility fallback. Width and height must be positive, and neither side may exceed the server-side configured limit. The default limit is 4500 pixels. If multiple `RenderSettings` Prims exist, the first one is used. ## Lights and Environment Light Lights and environment light can be written to the full USDA when creating a realtime session and updated incrementally through `POST /global/rendercloud/v1/streams/{sessionId}:push` after the session reaches `ACTIVE`. `usdContent` must always be encoded as `Base64(UTF-8(USDA text))`. ### Lights The current format supports `RectLight` rectangular area lights and `SphereLight` spherical point lights. Place lights under stable, unique Prim paths in the full scene and retain their complete paths; later updates and deletions must target the same paths. Light distances and dimensions are always interpreted using the cloud renderer's fixed **1 unit = 1 millimeter, Z-up** convention, so `metersPerUnit` and `upAxis` are not required. | Prim / Attribute | Constraint | |------------------|------------| | `RectLight` | `inputs:width` and `inputs:height` must be positive; supports `inputs:color`, `inputs:intensity`, `inputs:exposure`, `inputs:specular`, and `xformOp:transform` | | `SphereLight` | `inputs:radius` must be positive; supports `inputs:color`, `inputs:intensity`, `inputs:exposure`, `inputs:specular`, and `xformOp:transform` | | `inputs:color` | Linear RGB; white when omitted | | `inputs:intensity` / `inputs:exposure` | Effective intensity is `intensity × 2^exposure` | | `inputs:normalize` | May be omitted or set to `false`; setting it to `true` is not supported | | `xformOp:transform` / `xformOpOrder` | When setting a light transform, also write `uniform token[] xformOpOrder = ["xformOp:transform"]`; otherwise the Transform is not in the USD transform stack | | `manycore:affectReflections` | `0` or `1` in `customData`; defaults to `1` | | `manycore:doubleFace` | Boolean in `customData` for `RectLight`; defaults to `false` | `DistantLight`, `DiskLight`, `DomeLight`, Spot/IES/MeshLight, light linking, projected textures, and color temperature are not supported. Non-uniform scaling of `SphereLight` is also unsupported. `inputs:normalize` may be omitted or set to `false`, but must not be set to `true`. Matrices continue to use the row-vector convention in this guide, with translation in the fourth row. ### Environment light Write environment-light intensity on the active `RenderSettings` Prim, preferably alongside the camera and resolution: ```usda custom float3 manycore:environment:giIntensity = (1.25, 1.25, 1.25) ``` `manycore:environment:giIntensity` is an absolute RGB multiplier for GI environment light. All three values must be finite positive numbers representable as 32-bit floats; a regular brightness slider should convert scalar `v` to `(v, v, v)`. Omitting the attribute preserves the scene default and does not mean `(1, 1, 1)`. This attribute is not a light color and is not affected by `metersPerUnit`, `upAxis`, or sRGB/Gamma. ### Patch rules Send patches only after the session reaches `ACTIVE`. Use `over` for updates and keep paths identical to the initialization scene; add models or lights with `def` and complete creation fields, and delete models or lights with `manycore:operation:type = "del"`. Serialize camera, model, light, and environment-light patches in user-operation order within the same session; debounce high-frequency input and flush the final value. ## Minimal Realtime Initialization Example The following compact complete scene contains one Mesh, one camera, one rectangular area light, and environment light. Extend it with additional assets or lights as needed. It deliberately omits optional `upAxis` and `metersPerUnit` metadata. ```usda #usda 1.0 ( defaultPrim = "World" ) def Xform "World" { def Xform "Model" { matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (0, 0, 0, 1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/{meshId}@ ) {} } def Xform "Cameras" { def Camera "MainCamera" { float2 clippingRange = (0.1, 5000) float focalLength = 28 float horizontalAperture = 24.447495 float verticalAperture = 13.7517 token projection = "perspective" matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (0, 0, 8, 1) ) uniform token[] xformOpOrder = ["xformOp:transform"] } } def Xform "Lights" { def RectLight "KeyRect" { color3f inputs:color = (1, 1, 1) float inputs:intensity = 4 float inputs:width = 1200 float inputs:height = 600 float inputs:specular = 1 bool inputs:normalize = false matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (1200, 600, 2400, 1) ) uniform token[] xformOpOrder = ["xformOp:transform"] } } } def Scope "Render" { def RenderSettings "MainRenderSettings" { rel camera = int2 resolution = (1024, 576) custom float3 manycore:environment:giIntensity = (1, 1, 1) } } ``` ## Realtime Rendering Initialization Example The following is a complete reference scene containing multiple Meshes, 3DGS, a camera, lights, and environment light; it is not a minimal request body. In the actual request, encode the USDA text as `Base64(UTF-8(USDA plain text))` and pass it in `usdContent`. Every example `payload` uses the canonical form with a target Prim path. ```usda #usda 1.0 ( defaultPrim = "World" ) def Xform "World" { def Xform "MainSplat" { matrix4d xformOp:transform = ( (0.000051545731,0.000085786507,0,0), (-0.000085786507,0.000051545731,0,0), (0,0,0.000100081398,0), (0.174798629761,1.721153564453,0.3,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def ParticleField3DGaussianSplat "SplatModel" ( payload = @manycore:/mesh/YYKIL7BVAJQPYPTUKU888888@ ) { } } def Xform "Model_0_JVAIX5WPTUL4" { matrix4d xformOp:transform = ( (0.001,0,0,0), (0,0.001,0,0), (0,0,0.001,0), (0.18688556,1.6863253,1.321402,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/YYWWKOJVAIX5WPTUL4888888@ ) { } } def Xform "Model_1_ZVAIPWOPTULY" { matrix4d xformOp:transform = ( (0.001,0.000000000073,0,0), (-0.000000000073,0.001,0,0), (0,0,0.001,0), (-1.6171633,0.8850137,0.46721213,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/YRNLYLZVAIPWOPTULY888888@ ) { } } def Xform "Model_2_ZVAXAG6PTUJU" { matrix4d xformOp:transform = ( (-0.00000000008,0.0018392428,0,0), (-0.0018392428,-0.00000000008,0,0), (0,0,0.00015876645,0), (-1.638599,0.9451463,0.0005,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/ZSGMVMZVAXAG6PTUJU888888@ ) { } } def Xform "Model_3_BVAII3SPTUJU" { matrix4d xformOp:transform = ( (-0.00055461276,-0.0007359958,0,0), (0.0007359958,-0.00055461276,0,0), (0,0,0.00092156667,0), (0.06702871,0.49209814,0.32490457,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/YR3NPCBVAII3SPTUJU888888@ ) { } } def Xform "Model_4_RVALFX2PTUJQ" { matrix4d xformOp:transform = ( (0.00083867055,0.00054463905,0,0), (-0.00054463905,0.00083867055,0,0), (0,0,0.001,0), (-0.7005493,0.28526813,0.037392548,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/YWMNBJRVALFX2PTUJQ888888@ ) { } } def Xform "Model_5_RVAIIECPTULA" { matrix4d xformOp:transform = ( (-0.00000000004,0.0009199465,0,0), (-0.0009199465,-0.00000000004,0,0), (0,0,0.0009199465,0), (-3.0077407,0.81905786,0.3764504,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/ZC42U2RVAIIECPTULA888888@ ) { } } def Xform "Model_6_BVAJRHAPTUKQ" { matrix4d xformOp:transform = ( (0.0010743258,0,0,0), (0,0.0010743258,0,0), (0,0,0.0010743258,0), (0.1153041,2.9576484,1.8342776,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/ZDAFHEBVAJRHAPTUKQ888888@ ) { } } def Xform "Model_7_JVAUMCKPTULM" { matrix4d xformOp:transform = ( (-0.000000000048,0.0010972692,0,0), (-0.0010972692,-0.000000000048,0,0), (0,0,0.0010972692,0), (-1.0990643,2.1746306,0.23665573,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/ZS4RG7JVAUMCKPTULM888888@ ) { } } def Xform "Model_8_ZVAX3LMPTUJU" { matrix4d xformOp:transform = ( (0.0009108356,0.00056915325,0,0), (-0.00056915325,0.0009108356,0,0), (0,0,0.0010740377,0), (-3.3463013,2.5292085,0.863,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/ZSBUJIZVAX3LMPTUJU888888@ ) { } } def Xform "Model_9_ZVAJYACPTULU" { matrix4d xformOp:transform = ( (0.0008437305,0,0,0), (0,0.0008437305,0,0), (0,0,0.0008437305,0), (0.12560691,2.9127068,0.46892435,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/ZCCN76ZVAJYACPTULU888888@ ) { } } def Xform "Model_10_JVAIHW6PTULA" { matrix4d xformOp:transform = ( (0.00061403894,0,0,0), (0,0.00061403894,0,0), (0,0,0.00061403894,0), (-1.4365238,3.085212,1.3550343,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/ZG55YXJVAIHW6PTULA888888@ ) { } } def Xform "Model_11_UTDD52GSRTL4" { matrix4d xformOp:transform = ( (0.001,0,0,0), (0,0.0009986295,-0.00005233596,0), (0,0.00005233596,0.0009986295,0), (-0.9053951,3.1488496,1.6107593,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/6DM4O3UTDD52GSRTL4888888@ ) { } } def Xform "Model_12_JVAITAAPTULE" { matrix4d xformOp:transform = ( (0.0011506461,0,0,0), (0,0.0011506461,0,0), (0,0,0.0011506461,0), (-1.6382509,2.5568164,0.444,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/Z65NBFJVAITAAPTULE888888@ ) { } } def Xform "Model_13_JVAIJG2PTULA" { matrix4d xformOp:transform = ( (0.001,0,0,0), (0,0.001,0,0), (0,0,0.001,0), (-1.0495006,3.1262092,1.0833826,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/ZMXLP3JVAIJG2PTULA888888@ ) { } } def Xform "Model_14_JVAVUWOPTULM" { matrix4d xformOp:transform = ( (-0.000000000067,0.0015338801,0,0), (-0.0011504536,-0.00000000005,0,0), (0,0,0.0011504536,0), (-3.763693,2.7723376,1.2795,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/6JVR45JVAVUWOPTULM888888@ ) { } } def Xform "Cameras" { def Camera "MainCamera" { float2 clippingRange = (0.1, 5000) float focalLength = 20.7846 float fStop = 0 float horizontalAperture = 42.6667 float verticalAperture = 24.0000 token projection = "perspective" matrix4d xformOp:transform = ( (0.7333269715309143,0.6797372698783875,-0.01374034397304058,0), (-0.0885528177022934,0.11553312093019485,0.9893485307693481,0), (0.6740845441818237,-0.7242991924285889,0.14491620659828186,0), (0.8263652324676514,-0.030662942677736282,0.8460000157356262,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] } } def Xform "Lights" { def RectLight "KeyRect" ( customData = { int manycore:affectReflections = 1 bool manycore:doubleFace = false } ) { color3f inputs:color = (1.0, 0.95, 0.90) float inputs:intensity = 4.0 float inputs:exposure = 0.0 float inputs:width = 1200 float inputs:height = 600 float inputs:specular = 1 bool inputs:normalize = false matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (1200, 600, 2400, 1) ) uniform token[] xformOpOrder = ["xformOp:transform"] } def SphereLight "FillPoint" { color3f inputs:color = (0.70, 0.80, 1.00) float inputs:intensity = 40.0 float inputs:exposure = -1.0 float inputs:radius = 80 float inputs:specular = 1 bool inputs:normalize = false matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (-500, 900, 1800, 1) ) uniform token[] xformOpOrder = ["xformOp:transform"] } } } def Scope "Render" { def RenderSettings "MainRenderSettings" { rel camera = int2 resolution = (1024, 576) custom float3 manycore:environment:giIntensity = (1.25, 1.25, 1.25) } } ``` ## Realtime Patch Realtime patches do not rebuild the full scene; they separately update cameras, models, lights, and environment light. Send them only after the session reaches `ACTIVE`, using `over` and the same Prim paths as the initialization USDA. ### Camera patch ```usda #usda 1.0 over "World" { over "Cameras" { over "MainCamera" { token projection = "perspective" float focalLength = 50 float focusDistance = 100 float horizontalAperture = 36.0 float verticalAperture = 24.0 float2 clippingRange = (0.1, 5000.0) matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, -1, 0), (10, 20, 30, 1) ) } } } ``` ### Model patch Use a stable `Xform` Prim as the model parent and reference the uploaded asset with the `payload` of either `Mesh` or `ParticleField3DGaussianSplat`. Model addition, Transform updates, and deletion must use consistent complete Prim paths; the parent `Xform` must already be known from the full scene or from a successful earlier patch. #### 3DGS model **Add a 3DGS model** with `def`, including the Transform, `xformOpOrder`, and `payload`: ```usda over "World" { def Xform "GaussianSplatModel2" { matrix4d xformOp:transform = ( (0.001, 0.0, 0.0, 0.0), (0.0, 0.0, 0.001, 0.0), (0.0, -0.001, 0.0, 0.0), (0.0, 0.0, 0.0, 1.0) ) uniform token[] xformOpOrder = ["xformOp:transform"] def ParticleField3DGaussianSplat "MyGaussianSplat2" ( payload = @manycore:/mesh/YYPZPUETQYRLIPTUKE888888@ ) { } } } ``` **Update a 3DGS model Transform** with `over` on the existing parent `Xform` and a complete row-vector matrix. An empty `over` node for the child model can be used to make the target path explicit: ```usda over "World" { over "GaussianSplatModel2" { matrix4d xformOp:transform = ( (0.001, 0.0, 0.0, 0.0), (0.0, 0.0, 0.001, 0.0), (0.0, -0.001, 0.0, 0.0), (-2.01571919623, -0.262131040274, 1.279749806075, 1.0) ) uniform token[] xformOpOrder = ["xformOp:transform"] over ParticleField3DGaussianSplat "MyGaussianSplat2" { } } } ``` **Delete a 3DGS model** by adding `manycore:operation:type = "del"` to the `ParticleField3DGaussianSplat` at the original path. Do not rename or move the model before deleting it: ```usda over "World" { over "GaussianSplatModel2" { over ParticleField3DGaussianSplat "MyGaussianSplat2" ( customData = { string manycore:operation:type = "del" } ) { } } } ``` #### Mesh model `Mesh` model patches use the same semantics as 3DGS; the `payload` target Prim is ``. **Add a Mesh model**: ```usda over "World" { def Xform "MeshModel2" { matrix4d xformOp:transform = ( (0.001, 0.0, 0.0, 0.0), (0.0, 0.0, 0.001, 0.0), (0.0, -0.001, 0.0, 0.0), (0.0, 0.0, 0.0, 1.0) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/YYPZPUETQYRLIPTUKE888888@ ) { } } } ``` **Update a Mesh model Transform**: ```usda over "World" { over "MeshModel2" { matrix4d xformOp:transform = ( (0.001, 0.0, 0.0, 0.0), (0.0, 0.0, 0.001, 0.0), (0.0, -0.001, 0.0, 0.0), (-2.01571919623, -0.262131040274, 1.279749806075, 1.0) ) uniform token[] xformOpOrder = ["xformOp:transform"] over Mesh "Geom" { } } } ``` **Delete a Mesh model**: ```usda over "World" { over "MeshModel2" { over Mesh "Geom" ( customData = { string manycore:operation:type = "del" } ) { } } } ``` Model patches share the same session-level send queue as camera, light, and environment-light patches. Update the local committed scene state only after the server succeeds and the session remains `ACTIVE`. ### Light patch When modifying a light, write only changed fields. When updating position, rotation, or scale, write the complete row-vector `matrix4d xformOp:transform` together with `uniform token[] xformOpOrder = ["xformOp:transform"]`. For example, change the color and intensity of `/World/Lights/KeyRect`: ```usda over "World" { over "Lights" { over RectLight "KeyRect" { color3f inputs:color = (1.0, 0.72, 0.50) float inputs:intensity = 8.0 } } } ``` Add a light with `def` and complete fields. Delete an existing light with the same path and `manycore:operation:type = "del"`: ```usda over "World" { over "Lights" { def SphereLight "Accent" { color3f inputs:color = (0.2, 0.4, 1.0) float inputs:intensity = 12.0 float inputs:exposure = 0.0 float inputs:radius = 50.0 float inputs:specular = 1 bool inputs:normalize = false matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (300, 400, 500, 1) ) uniform token[] xformOpOrder = ["xformOp:transform"] } over SphereLight "FillPoint" ( customData = { string manycore:operation:type = "del" } ) {} } } ``` ### Environment-light patch An environment-light patch must target the same `RenderSettings` Prim path recorded during initialization. Explicitly writing the types is recommended: ```usda #usda 1.0 over Scope "Render" { over RenderSettings "MainRenderSettings" { custom float3 manycore:environment:giIntensity = (0.8, 0.8, 0.8) } } ``` Environment-light updates use absolute replacement values: changing from `2.0` to `0.8` sends `(0.8, 0.8, 0.8)`. Do not send `0`, negative numbers, or `None`, and do not clear the environment light by deleting the attribute, deleting `RenderSettings`, or sending `manycore:operation:type = "del"`; explicitly send `(1, 1, 1)` to restore multiplier 1. ## Supported Prims | Prim Type | Support | Key Attributes / Metadata | |-----------|---------|---------------------------| | `Xform` | Supported | `xformOp:transform`, `xformOpOrder`; can be a model parent for `def` / `over` | | `Mesh` | Supported | `payload` metadata; removable through `over` and the delete marker | | `ParticleField3DGaussianSplat` | Supported | `payload` metadata; removable through `over` and the delete marker | | `Camera` | Supported | Camera parameters and pose | | `RectLight` | Supported | `inputs:color`, `inputs:intensity`, `inputs:exposure`, `inputs:width`, `inputs:height`, `inputs:specular`, `xformOp:transform` | | `SphereLight` | Supported | `inputs:color`, `inputs:intensity`, `inputs:exposure`, `inputs:radius`, `inputs:specular`, `xformOp:transform` | | `RenderSettings` | Supported | `camera`, `resolution`, `manycore:environment:giIntensity` | | `Scope` | Supported | Hierarchy container | | Other USD types | Ignored | Not used for rendering | ## Limitations | Item | Description | |------|-------------| | **Fixed units and axis** | Cloud rendering always uses 1 unit = 1 millimeter and Z-up; `metersPerUnit` and `upAxis` are not required and do not cause coordinate or size conversion when present | | **Important: Matrix convention mismatch** | The matrix convention used by frontend display may differ from cloud rendering; cloud rendering requires model and camera `xformOp:transform` matrices in USDA to use row-major / row-vector form, with translation in the 4th row | | Light transforms | `xformOp:transform` alone is not in the USD transform stack; always write `xformOpOrder` with it | | Environment-light intensity | The three `manycore:environment:giIntensity` values must be finite and positive; clearing with `0`, attribute deletion, or Prim deletion is unsupported | | Unsupported light types | `DistantLight`, `DiskLight`, `DomeLight`, Spot/IES/MeshLight, light linking, projected textures, and color temperature are not rendered | | Full USD composition | `references`, `subLayers`, `variantSets`, material networks, and similar composition features are not supported | | Multiple cameras / RenderSettings | The first one found during traversal is used | | Unknown attributes | Ignored without error | | Syntax errors | Unclosed braces or invalid attribute values cause parsing failure | | Missing asset | Rendering may fail or miss the referenced asset | x-scalar-doc-only: true - name: RenderCloud description: OpenUSD render cloud APIs x-displayName: Render Cloud - name: SpatialUnderstanding description: >- Spatial Understanding — create async tasks from indoor point clouds (`.ply`), poll details for Wall / Door / Window / Bbox text results, or paginate your tasks. x-displayName: Spatial Understanding paths: /global/asset/v1/token: get: tags: - Asset summary: Get OUS upload token description: > This endpoint returns upload credentials only; **actual upload happens on OUS `globalDomain`** (not the open-platform gateway), then continue with `ousCosSingleUpload`, `ousCosBlockUploadInit`, `ousCosBlockUploadPart`, and `ousCosUploadStatus` in the **Upload** tag. **Recommended flow:** 1. Call this endpoint to get `ousToken`, `globalDomain` (e.g. `https://ous-sg.kujiale.com`), and `blockSize`. 2. If file size **≤ `blockSize`**: call `ousCosSingleUpload`; if **> `blockSize`**: call `ousCosBlockUploadInit` then `ousCosBlockUploadPart` as needed. 3. Poll `ousCosUploadStatus` until success and you receive `url`. 4. Use the public URL in downstream APIs, e.g. `resources[].url` for **Create 3DGS world reconstruction**. operationId: getUploadToken responses: '200': description: >- On success, the body is the OUS credential (`ousToken`, `globalDomain`, `blockSize`) for direct or multipart upload on the returned COS host. content: application/json: schema: $ref: '#/components/schemas/asset_UploadTokenOuterOpen' examples: success: summary: Token retrieved description: success value: ousToken: globalDomain: https://ous-sg.kujiale.com blockSize: 1048576 '400': description: Parameter/business validation failed (`ApiError`; legacy biz code in `details.metaData.bizCode`) content: application/json: schema: $ref: '#/components/schemas/asset_ApiError' examples: paramsInvalid: summary: Parameter validation failed description: Code 10001 (PARAMS_INVALID) value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo.ai message: Invalid request parameters metaData: bizCode: '10001' '401': description: Missing or invalid `Authorization`; authentication failed (`ApiError`). content: application/json: schema: $ref: '#/components/schemas/asset_ApiError' examples: notLoggedIn: summary: Not logged in or authentication failed description: Legacy biz code 10004 (NOT_LOGGED_IN) value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo.ai message: Not logged in metaData: bizCode: '10004' security: - AuthorizationHeader: [] x-scalar-order: 5 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createAssetClient } from '@manycore/aholo-sdk-asset'; // SDK handles token, multipart upload, and polling — no need to call this endpoint directly const asset = createAssetClient({ region: 'com' }); const result = await asset.uploadFile('./video.mp4'); console.log(result.url); - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.asset.AssetClient; import com.manycoreapis.sdk.asset.UploadResult; import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; AssetClient asset = AssetClient.create(AholoClientConfig.ofRegion("com")); UploadResult result = asset.uploadFile(Paths.get("video.mp4")); System.out.println(result.url()); - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_asset import create_asset_client # SDK handles token, multipart upload, and polling — no need to call this endpoint directly asset = create_asset_client(region='com') result = asset.upload_file('./video.mp4') print(result.url) /ous/api/v2/single/upload: post: tags: - Asset summary: OUS single-file upload (≤ blockSize) description: >- Use when file size **≤** `blockSize` from the token response; see `requestBody` and `components.schemas.OusCosSingleUploadForm`. operationId: ousCosSingleUpload requestBody: description: Single-file upload request body. content: multipart/form-data: schema: $ref: '#/components/schemas/asset_OusCosSingleUploadForm' encoding: file: contentType: application/octet-stream required: true responses: '200': description: On success, `c` is `0` and `d` contains `taskId`; then poll `GET /ous/api/v2/upload/status`. content: application/json: schema: $ref: '#/components/schemas/asset_OusV2SingleUploadApiResponse' security: - OusTokenV2: [] servers: - url: https://ous-sg.kujiale.com description: '`globalDomain` returned by OUS; production is often this COS host (see the token response).' x-scalar-order: 6 /ous/api/v2/block/upload/init: post: tags: - Asset summary: OUS multipart upload — initialize description: >- Use when file size **>** `blockSize`. **Typical call**: `POST` with required fields in **URL query** (no JSON body). Example: `…/ous/api/v2/block/upload/init?md5=…&blocks=…&size=…&name=…`. operationId: ousCosBlockUploadInit parameters: - name: md5 in: query required: true schema: type: string description: File MD5, lowercase hex example: e99a18c428cb38d5f260853678922e03 - name: blocks in: query required: true schema: type: integer description: Total part count format: int64 example: 11 - name: size in: query required: true schema: type: integer description: File size in bytes format: int64 example: 5942880 - name: name in: query required: true schema: type: string description: Original file name example: photo.jpg - name: metadata in: query required: false schema: type: string description: Metadata (optional) - name: customPrefix in: query required: false schema: type: string description: Custom storage prefix (optional) - name: customFilename in: query required: false schema: type: string description: Custom file name (optional) responses: '200': description: On success, `c` is `0` and `d` contains `taskId`, `lackBlocks`, `progress`, `deduplicated`. content: application/json: schema: $ref: '#/components/schemas/asset_OusV2BlockInitApiResponse' security: - OusTokenV2: [] servers: - url: https://ous-sg.kujiale.com description: '`globalDomain` returned by OUS; production is often this COS host (see the token response).' x-scalar-order: 7 /ous/api/v2/block/upload/part: post: tags: - Asset summary: OUS multipart upload — upload one part description: Call once per part; see `OusCosBlockUploadPartForm`. operationId: ousCosBlockUploadPart requestBody: description: Single-part upload request body. content: multipart/form-data: schema: $ref: '#/components/schemas/asset_OusCosBlockUploadPartForm' encoding: file: contentType: application/octet-stream required: true responses: '200': description: On success, `c` is `0` and `d` is `null`. For the same file, limit concurrent part uploads to 2. content: application/json: schema: $ref: '#/components/schemas/asset_OusV2BlockPartApiResponse' security: - OusTokenV2: [] servers: - url: https://ous-sg.kujiale.com description: '`globalDomain` returned by OUS; production is often this COS host (see the token response).' x-scalar-order: 8 /ous/api/v2/upload/status: get: tags: - Asset summary: OUS — poll upload status description: >- Poll the upload task; `d` differs for single-file vs multipart (see `oneOf` in the response schema). Send only `ous-token-v2`, no body. Poll about every ≥200ms for ~5s total. operationId: ousCosUploadStatus responses: '200': description: >- On success, `c` is `0`; `d` is single-file or multipart status/result (`status=5` is success; see embedded fields and status table). content: application/json: schema: $ref: '#/components/schemas/asset_OusV2UploadStatusApiResponse' security: - OusTokenV2: [] servers: - url: https://ous-sg.kujiale.com description: '`globalDomain` returned by OUS; production is often this COS host (see the token response).' x-scalar-order: 9 /global/world/v1/reconstructions: post: tags: - World summary: Create 3DGS world reconstruction job description: > Creates an async 3DGS world reconstruction job. On acceptance, returns `WorldAsyncOperation` with `worldId` only (same as **Get world details** `{worldId}`). **Resource formats**: image: .jpg / .jpeg / .png / .webp; video: .mp4 / .mov; insv: .insv. **Rules**: if `resources` include images (`type=image` or omit `type`), need **≥20** image entries; for video set `type=video`; for Insta360 panoramic video set `type=insv` (neither triggers the 20-image rule). operationId: createWorld parameters: - name: x-source in: header required: false schema: type: string requestBody: description: Create-job body; when using images, meet the count rules in `CreateWorldRequest`. content: application/json: schema: $ref: '#/components/schemas/world_CreateWorldRequest' examples: createWorldWithVideo: description: 'Single video + indoor scene; `type: video`, supports .mp4 / .mov' value: name: Living room reconstruction resources: - url: https://cdn.example.com/input/room-001.mp4 type: video taskQuality: high scene: space createWorldWithImages: description: >- Multi-image: need ≥20 `image` entries (or omit `type` to count as image), supports .jpg / .jpeg / .png / .webp; example is truncated—real calls need 20+ items. value: name: Living room reconstruction resources: - url: https://cdn.example.com/in/1.jpg type: image - url: https://cdn.example.com/in/2.jpg type: image taskQuality: high scene: space createWorldWithInsv: description: 'Insta360 panoramic video; `type: insv`, supports .insv' value: name: Panoramic living room reconstruction resources: - url: https://cdn.example.com/input/room-001.insv type: insv taskQuality: high scene: space required: true responses: '200': description: 'Accepted: returns `WorldAsyncOperation` with `worldId`.' content: application/json: schema: $ref: '#/components/schemas/world_WorldAsyncOperation' examples: success: summary: Accepted for processing description: success value: worldId: A1b2C3d4E5 '400': description: >- Invalid body/parameters, insufficient credits, etc. (`ApiError`; legacy biz code in `details.metaData.bizCode`) content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: paramsInvalid: summary: Invalid parameters / body description: Code 10001 (PARAMS_INVALID) value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo.ai message: Invalid request parameters metaData: bizCode: '10001' insufficientCredits: summary: Insufficient credits description: Legacy biz code 11003; may not apply if create does not charge credits. value: code: 400 message: insufficient credits to complete task status: FAILED_PRECONDITION details: reason: BIZ_11003 domain: api.aholo.ai message: insufficient credits to complete task metaData: bizCode: '11003' taskMattingError: summary: Other task error (example) description: Legacy biz code 11004; may not occur on this path. value: code: 400 message: matting error status: FAILED_PRECONDITION details: reason: BIZ_11004 domain: api.aholo.ai message: matting error metaData: bizCode: '11004' '401': description: Missing or invalid `Authorization`; authentication failed (`ApiError`). content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: notLoggedIn: summary: Not logged in or authentication failed description: Legacy biz code 10004 (NOT_LOGGED_IN) value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo.ai message: Not logged in metaData: bizCode: '10004' '429': description: Global task concurrency or rate limit (`ApiError`) content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: taskGlobalRateLimit: summary: Global long-task concurrency limit description: Legacy biz code 11001 value: code: 429 message: task global rate limit status: RESOURCE_EXHAUSTED details: reason: BIZ_11001 domain: api.aholo.ai message: task global rate limit metaData: bizCode: '11001' security: - AuthorizationHeader: [] x-scalar-order: 10 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createWorldClient } from '@manycore/aholo-sdk-world'; const world = createWorldClient({ region: 'com' }); const { worldId } = await world.reconstructions.create({ name: 'Living room', resources: [{ url: 'https://cdn.example.com/room.mp4', type: 'video' }], taskQuality: 'normal', scene: 'model', }); const detail = await world.waitFor(worldId); console.log(detail.assets?.splats?.urls?.plyPath); - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.world.WorldClient; import com.manycoreapis.sdk.world.model.ReconstructionCreateParams; import com.manycoreapis.sdk.world.model.GenerationCreateParams; import com.manycoreapis.sdk.world.model.WorldListParams; import com.manycoreapis.sdk.world.model.WorldAsyncOperation; import com.manycoreapis.sdk.world.model.WorldDetail; import com.manycoreapis.sdk.world.model.WorldPagedList; WorldClient world = WorldClient.create(AholoClientConfig.ofRegion("com")); WorldAsyncOperation op = world.reconstructions().create( ReconstructionCreateParams.builder() .name("Living room") .addResource("https://cdn.example.com/room.mp4", "video") .taskQuality("normal") .scene("model") .build()); WorldDetail detail = world.waitFor(op.worldId()); - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_world import create_world_client world = create_world_client(region='com') op = world.reconstructions.create( name='Living room', resources=[{'url': 'https://cdn.example.com/room.mp4', 'type': 'video'}], task_quality='normal', scene='model', ) detail = world.wait_for(op['worldId']) print(detail.get('assets', {}).get('splats', {}).get('urls', {}).get('plyPath')) /global/world/v1/generations: post: tags: - World summary: Create 3DGS world generation job description: >- Creates an async 3DGS world generation job (Spatial Gen). **Indoor** scenes are more mature and stable today; non-indoor input is allowed but still **Beta** and may be materially weaker than indoor—assess risk accordingly. On acceptance returns `WorldAsyncOperation` (`worldId` only). Supports text-only, a single image, or text + image. If `resources` includes an image, at most one (image: .jpg / .jpeg / .png / .webp). operationId: generateWorld parameters: - name: x-source in: header required: false schema: type: string requestBody: description: >- Generation request body. Supports text-only, a single image, or text + image. At most one image (image: .jpg / .jpeg / .png / .webp). content: application/json: schema: $ref: '#/components/schemas/world_GenerateWorldRequest' examples: generateWorldRequest: summary: Text + image example description: generateWorldRequest value: name: Living room generation cover: https://cdn.example.com/cover/gen-cover.jpg prompt: Modern minimalist living room resources: - url: https://cdn.example.com/input/room.jpg type: image required: true responses: '200': description: 'Accepted: returns `WorldAsyncOperation` with `worldId`.' content: application/json: schema: $ref: '#/components/schemas/world_WorldAsyncOperation' examples: success: summary: Accepted for processing description: success value: worldId: B2c3D4e5F6 '400': description: Invalid body/parameters or other business errors (`ApiError`) content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: paramsInvalid: summary: Invalid parameters / body description: Code 10001 (PARAMS_INVALID) value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo.ai message: Invalid request parameters metaData: bizCode: '10001' '401': description: Missing or invalid `Authorization`; authentication failed (`ApiError`). content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: notLoggedIn: summary: Not logged in or authentication failed description: Legacy biz code 10004 (NOT_LOGGED_IN) value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo.ai message: Not logged in metaData: bizCode: '10004' security: - AuthorizationHeader: [] x-scalar-order: 15 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createWorldClient } from '@manycore/aholo-sdk-world'; const world = createWorldClient({ region: 'com' }); const { worldId } = await world.generations.create({ name: 'Forest cabin', prompt: 'A modern cabin in the forest', }); const detail = await world.waitFor(worldId); - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.world.WorldClient; import com.manycoreapis.sdk.world.model.ReconstructionCreateParams; import com.manycoreapis.sdk.world.model.GenerationCreateParams; import com.manycoreapis.sdk.world.model.WorldListParams; import com.manycoreapis.sdk.world.model.WorldAsyncOperation; import com.manycoreapis.sdk.world.model.WorldDetail; import com.manycoreapis.sdk.world.model.WorldPagedList; WorldClient world = WorldClient.create(AholoClientConfig.ofRegion("com")); WorldAsyncOperation op = world.generations().create( GenerationCreateParams.builder() .name("Forest cabin") .prompt("A modern cabin in the forest") .build()); WorldDetail detail = world.waitFor(op.worldId()); - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_world import create_world_client world = create_world_client(region='com') op = world.generations.create( name='Forest cabin', prompt='A modern cabin in the forest', ) detail = world.wait_for(op['worldId']) /global/world/v1/{worldId}: get: tags: - World summary: Get world details description: >- Get details by world id. When reconstruction succeeds, splat (ply/spz) URLs may be present; after LOD post-processing, `assets.splats.urls.lodMetaPath` has LOD chunk metadata. For AI-generated (Spatial Gen) worlds, `assets.imagery.panoUrl` returns the panorama download URL once available. operationId: getWorldDetail parameters: - name: worldId in: path description: World id (same as `WorldAsyncOperation.worldId` from create) required: true schema: type: string example: A1b2C3d4E5 responses: '200': description: On success, the body is a world detail object. content: application/json: schema: $ref: '#/components/schemas/world_WorldDetail' examples: reconstructionWorldDetail: summary: 3D reconstruction world detail description: Reconstruction succeeded with splats and coordinate metadata; no imagery. value: worldId: A1b2C3d4E5 name: Living room reconstruction cover: https://cdn.example.com/cover/world-001.jpg scene: space createTime: 1699339916000 updateTime: 1699340120000 status: SUCCEEDED progress: 1 assets: splats: urls: plyPath: https://cdn.example.com/output/world-001.ply spzPath: https://cdn.example.com/output/world-001.spz lodMetaPath: https://cdn.example.com/output/world-001-lod-meta.json semanticsMetadata: upAxis: Z generateWorldDetail: summary: AI-generated world detail description: Generation succeeded with panorama `imagery.panoUrl` and splats. value: worldId: B2c3D4e5F6 name: Modern minimalist living room cover: https://cdn.example.com/cover/world-gen-001.jpg scene: ai_gen createTime: 1699339916000 updateTime: 1699340120000 status: SUCCEEDED progress: 1 assets: imagery: panoUrl: https://cdn.example.com/output/world-gen-001-pano.jpg splats: urls: plyPath: https://cdn.example.com/output/world-gen-001.ply spzPath: https://cdn.example.com/output/world-gen-001.spz lodMetaPath: https://cdn.example.com/output/world-gen-001-lod-meta.json semanticsMetadata: upAxis: Z '400': description: Path parameter validation or other business errors (`ApiError`) content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: paramsInvalid: summary: Path parameter validation failed description: Code 10001 value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo.ai message: Invalid request parameters metaData: bizCode: '10001' '401': description: Missing or invalid `Authorization`; authentication failed (`ApiError`). content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: notLoggedIn: summary: Not logged in or authentication failed description: Legacy biz code 10004 (NOT_LOGGED_IN) value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo.ai message: Not logged in metaData: bizCode: '10004' '403': description: Access denied (`ApiError`) content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: noPermission: summary: Forbidden description: Legacy biz code 12003 value: code: 403 message: no permission status: PERMISSION_DENIED details: reason: BIZ_12003 domain: api.aholo.ai message: no permission metaData: bizCode: '12003' '404': description: World not found (`ApiError`) content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: projectNotExist: summary: World (project) not found description: Legacy biz code 12001 value: code: 404 message: project not exist status: NOT_FOUND details: reason: BIZ_12001 domain: api.aholo.ai message: project not exist metaData: bizCode: '12001' security: - AuthorizationHeader: [] x-scalar-order: 20 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createWorldClient } from '@manycore/aholo-sdk-world'; const world = createWorldClient({ region: 'com' }); const detail = await world.retrieve('A1b2C3d4E5'); console.log(detail.status); - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.world.WorldClient; import com.manycoreapis.sdk.world.model.ReconstructionCreateParams; import com.manycoreapis.sdk.world.model.GenerationCreateParams; import com.manycoreapis.sdk.world.model.WorldListParams; import com.manycoreapis.sdk.world.model.WorldAsyncOperation; import com.manycoreapis.sdk.world.model.WorldDetail; import com.manycoreapis.sdk.world.model.WorldPagedList; WorldClient world = WorldClient.create(AholoClientConfig.ofRegion("com")); WorldDetail detail = world.retrieve("A1b2C3d4E5"); detail.status().ifPresent(System.out::println); - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_world import create_world_client world = create_world_client(region='com') detail = world.retrieve('A1b2C3d4E5') print(detail.get('status')) /global/world/v1/list: post: tags: - World summary: Paginated list of my worlds description: Paginated list of 3DGS worlds for the current account. operationId: getMyWorldList requestBody: description: Pagination and filters. content: application/json: schema: $ref: '#/components/schemas/world_WorldListQueryRequest' examples: listWorldRequest: description: 'Example: first page, 20 per page, filter RUNNING and SUCCEEDED.' value: pageNum: 0 pageSize: 20 statusList: - RUNNING - SUCCEEDED required: true responses: '200': description: On success, the body is a paged list (`pageNum`, `pageSize`, rows, etc.). content: application/json: schema: $ref: '#/components/schemas/world_WorldPagedList' examples: success: summary: OK description: success value: pageNum: 0 pageSize: 20 count: 1 totalCount: 1 hasMore: false result: - worldId: A1b2C3d4E5 name: Living room reconstruction cover: https://cdn.example.com/cover/world-001.jpg scene: space createTime: 1699339916000 updateTime: 1699340120000 status: RUNNING progress: 0.45 '400': description: Pagination parameter validation failed (`ApiError`) content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: paramsInvalid: summary: Body / parameter validation failed description: Code 10001 value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo.ai message: Invalid request parameters metaData: bizCode: '10001' '401': description: Missing or invalid `Authorization`; authentication failed (`ApiError`). content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: notLoggedIn: summary: Not logged in or authentication failed description: Legacy biz code 10004 (NOT_LOGGED_IN) value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo.ai message: Not logged in metaData: bizCode: '10004' security: - AuthorizationHeader: [] x-scalar-order: 30 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createWorldClient } from '@manycore/aholo-sdk-world'; const world = createWorldClient({ region: 'com' }); const page = await world.list({ pageNum: 1, pageSize: 20 }); page.result?.forEach((w) => console.log(w.worldId, w.status)); - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.world.WorldClient; import com.manycoreapis.sdk.world.model.ReconstructionCreateParams; import com.manycoreapis.sdk.world.model.GenerationCreateParams; import com.manycoreapis.sdk.world.model.WorldListParams; import com.manycoreapis.sdk.world.model.WorldAsyncOperation; import com.manycoreapis.sdk.world.model.WorldDetail; import com.manycoreapis.sdk.world.model.WorldPagedList; WorldClient world = WorldClient.create(AholoClientConfig.ofRegion("com")); WorldPagedList page = world.list( WorldListParams.builder().pageNum(1).pageSize(20).build()); page.result().ifPresent(items -> items.forEach(w -> System.out.println(w.worldId() + " " + w.status()))); - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_world import create_world_client world = create_world_client(region='com') page = world.list(page_num=1, page_size=20) for w in page.get('result', []): print(w.get('worldId'), w.get('status')) /global/lux3d/v1/generate/multimodal-to-image/task/create: post: tags: - Lux3D summary: Create Multimodal Single-Image Generation Task description: > Creates an asynchronous single-image generation task from an image, a text prompt, or both. At least one of img and prompt is required. The response contains a task ID (taskid); use the task query API to retrieve its status and result image URL. operationId: createMultimodalToImageTaskGlobal requestBody: description: Multimodal single-image request body. At least one of img and prompt is required. required: true content: application/json: schema: $ref: '#/components/schemas/lux3d_MultimodalToImageRequest' examples: promptOnly: summary: Generate one image from text value: prompt: A modern minimalist light-wood dining chair on a pure white background imageOnly: summary: Generate one image from a reference value: img: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg imageAndPrompt: summary: Edit a reference image according to a prompt value: img: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg prompt: Change the chair to light natural wood while preserving its shape and viewpoint responses: '200': description: Returns the task ID on success. content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: Task created successfully value: f: null c: '0' m: '' d: 1256174 invalidInput: summary: Neither img nor prompt was provided value: f: null c: '-1' m: img or prompt is required d: null concurrencyLimit: summary: Generation task concurrency limit reached value: f: null c: GENERATION_CONCURRENCY_LIMIT_EXCEEDED m: There is already a generation task in progress. Please wait for it to finish and try again. d: null '401': description: Missing or invalid Authorization header content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] servers: - url: https://api.aholo.ai description: Global x-scalar-order: 1 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'com' }); const taskId = await lux3d.multimodalToImage.create({ prompt: 'A wooden chair product photo, white background', img: 'https://example.com/object.jpg', }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("com")); long taskId = lux3d.multimodalToImage().create( MultimodalToImageCreateParams.builder() .prompt("A wooden chair product photo, white background") .img("https://example.com/object.jpg") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='com') task_id = lux3d.multimodal_to_image.create( prompt='A wooden chair product photo, white background', img='https://example.com/object.jpg', ) result = lux3d.tasks.wait_for(task_id) /global/lux3d/v1/generate/image-to-four-view/task/create: post: tags: - Lux3D summary: Create Multimodal Four-View Task description: > Creates an asynchronous task that generates four views of an object from an image, a text prompt, or both. At least one of img and prompt is required. The response contains a task ID (taskid); use the task query API to retrieve its status and results. Successful results contain four image URLs in this order: FRONT_THREE_QUARTER, OPPOSITE_THREE_QUARTER, SIDE, BACK. operationId: createImageToFourViewTaskGlobal requestBody: description: Multimodal four-view task request body. required: true content: application/json: schema: $ref: '#/components/schemas/lux3d_ImageToFourViewRequest' examples: promptOnly: summary: Generate four views from text value: prompt: A modern minimalist light-wood dining chair imageOnly: summary: Generate four views from an image value: img: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg imageAndPrompt: summary: Generate four views from an image and prompt value: img: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg prompt: Change the chair to light natural wood while preserving its shape and viewpoint responses: '200': description: Returns the task ID on success. content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: Task created successfully value: f: null c: '0' m: '' d: 1256173 invalidInput: summary: Neither img nor prompt was provided value: f: null c: '-1' m: img or prompt is required d: null concurrencyLimit: summary: Generation task concurrency limit reached value: f: null c: GENERATION_CONCURRENCY_LIMIT_EXCEEDED m: There is already a generation task in progress. Please wait for it to finish and try again. d: null '401': description: Missing or invalid Authorization header content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] servers: - url: https://api.aholo.ai description: Global x-scalar-order: 2 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'com' }); const taskId = await lux3d.imageToFourView.create({ img: 'https://example.com/object.jpg', prompt: 'Product four-view, white background', }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("com")); long taskId = lux3d.imageToFourView().create( ImageToFourViewCreateParams.builder() .img("https://example.com/object.jpg") .prompt("Product four-view, white background") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='com') task_id = lux3d.image_to_four_view.create( img='https://example.com/object.jpg', prompt='Product four-view, white background', ) result = lux3d.tasks.wait_for(task_id) /global/lux3d/v1/generate/img-to-3d/task/create: post: tags: - Lux3D summary: Create Image-to-3D Task description: > Creates an asynchronous 3D generation task from one or more images with G1 or G1-Turbo. If version is omitted, the default version is used. The response contains a task ID (taskid) for querying status and results. operationId: createImgTo3dTaskGlobal requestBody: description: Image-to-3D task request body. content: application/json: schema: $ref: '#/components/schemas/lux3d_ImgTo3dRequest' examples: createTaskG1: summary: Create image-to-3D task with G1 (recommended) value: img: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg version: G1 faceCount: 300000 outputFormat: - zip - glb createTaskG1TurboMultiImage: summary: Create a multi-image image-to-3D task with G1-Turbo (recommended) value: version: G1-Turbo imgs: - https://qhstaticssl.kujiale.com/image/png/1784775590866/multiview_input_1.png - https://qhstaticssl.kujiale.com/image/png/1784775591151/multiview_input_2.png outputFormat: - glb faceCount: 300000 enablePbr: true required: true responses: '200': description: Returns task ID on success. content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: Task created successfully value: f: null c: '0' m: '' d: 1256173 concurrencyLimit: summary: Generation task concurrency limit reached value: f: null c: GENERATION_CONCURRENCY_LIMIT_EXCEEDED m: There is already a generation task in progress. Please wait for it to finish and try again. d: null '401': description: Missing or invalid Authorization header, authentication failed content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] servers: - url: https://api.aholo.ai description: Global x-scalar-order: 3 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'com' }); const taskId = await lux3d.imgTo3d.create({ img: 'https://example.com/object.jpg', version: 'G1', }); const result = await lux3d.tasks.waitFor(taskId); console.log(result.outputs[0]?.content); - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("com")); long taskId = lux3d.imgTo3d().create( ImgTo3dCreateParams.builder() .img("https://example.com/object.jpg") .version("G1") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); result.outputs().forEach(o -> o.content().ifPresent(System.out::println)); - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='com') task_id = lux3d.img_to_3d.create(img='https://example.com/object.jpg', version='G1') result = lux3d.tasks.wait_for(task_id) print(result['outputs'][0]['content']) /global/lux3d/v1/generate/text-to-3d/task/create: post: tags: - Lux3D summary: Create Text-to-3D Task description: > Creates an asynchronous 3D generation task from a prompt and one optional reference image with G1 or G1-Turbo. If version is omitted, the default version is used. The response contains a task ID (taskid) for querying status and results. operationId: createTextTo3dTaskGlobal requestBody: description: Text-to-3D task request body. content: application/json: schema: $ref: '#/components/schemas/lux3d_TextTo3dRequest' examples: textOnlyG1: summary: Text-only generation with G1 (recommended) value: prompt: Generate a high-quality 3D wooden chair model style: photorealistic version: G1 faceCount: 300000 outputFormat: - zip - glb textWithImage: summary: 'Text with reference image generation (recommended: G1)' value: prompt: Generate a high-quality 3D wooden chair model style: photorealistic img: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg version: G1 textG1ZipGlb: summary: G1 text-to-3D with ZIP and GLB output value: prompt: Generate a modern wooden dining chair style: photorealistic version: G1 outputFormat: - zip - glb faceCount: 300000 textG1TurboPly: summary: G1-Turbo text-to-3D with PLY output value: prompt: Generate a modern wooden dining chair style: photorealistic version: G1-Turbo outputFormat: - ply required: true responses: '200': description: Returns task ID on success. content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: Task created successfully value: f: null c: '0' m: '' d: 1256173 concurrencyLimit: summary: Generation task concurrency limit reached value: f: null c: GENERATION_CONCURRENCY_LIMIT_EXCEEDED m: There is already a generation task in progress. Please wait for it to finish and try again. d: null '401': description: Missing or invalid Authorization header, authentication failed content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] servers: - url: https://api.aholo.ai description: Global x-scalar-order: 4 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'com' }); const taskId = await lux3d.textTo3d.create({ prompt: 'A wooden chair with carved legs', version: 'G1', }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("com")); long taskId = lux3d.textTo3d().create( TextTo3dCreateParams.builder() .prompt("A wooden chair with carved legs") .version("G1") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='com') task_id = lux3d.text_to_3d.create(prompt='A wooden chair with carved legs', version='G1') result = lux3d.tasks.wait_for(task_id) /global/lux3d/v1/generate/material-transfer/task/create: post: tags: - Lux3D summary: Create Material Transfer Task description: > Creates an asynchronous material transfer task from a reference image and a GLB model. The response contains a task ID (taskid) for querying status and results. operationId: createMaterialTransferTaskGlobal requestBody: description: Material transfer task request body. content: application/json: schema: $ref: '#/components/schemas/lux3d_MaterialTransferRequest' examples: createTaskDefault: summary: Create a material transfer task value: img: https://qhstaticssl.kujiale.com/image/png/1784776951878/material_transfer_input.png meshUrl: https://qhstaticssl.kujiale.com/application/octetstream/1784776896628/material_transfer_model.glb version: v3.0-standard required: true responses: '200': description: Returns task ID on success. content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: Task created successfully value: f: null c: '0' m: '' d: 1256173 concurrencyLimit: summary: Generation task concurrency limit reached value: f: null c: GENERATION_CONCURRENCY_LIMIT_EXCEEDED m: There is already a generation task in progress. Please wait for it to finish and try again. d: null '401': description: Missing or invalid Authorization header, authentication failed content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] servers: - url: https://api.aholo.ai description: Global x-scalar-order: 5 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'com' }); const taskId = await lux3d.materialTransfer.create({ img: 'https://example.com/material.jpg', meshUrl: 'https://example.com/model.glb', version: 'v3.0-standard', }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("com")); long taskId = lux3d.materialTransfer().create( MaterialTransferCreateParams.builder() .img("https://example.com/material.jpg") .meshUrl("https://example.com/model.glb") .version("v3.0-standard") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='com') task_id = lux3d.material_transfer.create( img='https://example.com/material.jpg', mesh_url='https://example.com/model.glb', version='v3.0-standard', ) result = lux3d.tasks.wait_for(task_id) /global/lux3d/v1/part-split/task/create: post: tags: - Lux3D summary: Create Part-Splitting Task description: > Creates an asynchronous part-splitting task from a GLB model URL accessible to the service. The response contains a task ID (taskid); use the task query API to retrieve the task status and a GLB file URL containing the split parts. If the authenticated account already has a part-splitting task in progress, no task is created. Retry later. operationId: createPartSplitTaskGlobal requestBody: description: Part-splitting task request body. required: true content: application/json: schema: $ref: '#/components/schemas/lux3d_PartSplitRequest' examples: createTask: summary: Create a part-splitting task value: glbUrl: https://qhstaticssl.kujiale.com/model/gltfbinary/1790144390549/14B82261CD6DF53FA6B406240E20CB2C.glb responses: '200': description: Returns the task ID on success. content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: Task created successfully value: f: null c: '0' m: '' d: 1256174 temporarilyUnavailable: summary: Task creation is temporarily unavailable value: f: null c: GENERATION_CONCURRENCY_LIMIT_EXCEEDED m: Service is busy, please try again later d: null '401': description: Missing or invalid Authorization header, authentication failed content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] servers: - url: https://api.aholo.ai description: Global x-scalar-order: 6 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'com' }); const taskId = await lux3d.partSplit.create({ glbUrl: 'https://example.com/model.glb', }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("com")); long taskId = lux3d.partSplit().create( PartSplitCreateParams.builder() .glbUrl("https://example.com/model.glb") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='com') task_id = lux3d.part_split.create(glb_url='https://example.com/model.glb') result = lux3d.tasks.wait_for(task_id) /global/lux3d/v1/multi-format-export/task/create: post: tags: - Lux3D summary: Create Multi-Format Export Task description: > Creates an asynchronous task that exports a ZIP or GLB model to one or more supported formats. The response contains a task ID (taskid); use the task query API to retrieve its status and results. operationId: createMultiFormatExportTaskGlobal requestBody: description: Multi-format export task request body. content: application/json: schema: $ref: '#/components/schemas/lux3d_MultiFormatExportRequest' examples: createTaskDefault: summary: Create a multi-format export task (glb input, export usdz) value: modelUrl: https://qhstaticssl.kujiale.com/application/octetstream/1784776896628/model.glb outputFormat: - usdz createTaskWithPrintFormats: summary: Create a multi-format export task (glb input, export STL and 3MF) value: modelUrl: https://qhstaticssl.kujiale.com/application/octetstream/1784776896628/model.glb outputFormat: - stl - 3mf required: true responses: '200': description: Returns task ID on success. content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: Task created successfully value: f: null c: '0' m: '' d: 1256173 glbNoFormat: summary: glb input without any export format enabled value: f: null c: '-1' m: glb input requires at least one export format in outputFormat (usdz/obj_zip/fbx_zip/stl/3mf) d: null '401': description: Missing or invalid Authorization, authentication failed content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] servers: - url: https://api.aholo.ai description: Global x-scalar-order: 7 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'com' }); const taskId = await lux3d.multiFormatExport.create({ modelUrl: 'https://example.com/model.glb', outputFormat: ['usdz', 'obj_zip', 'stl'], }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("com")); long taskId = lux3d.multiFormatExport().create( MultiFormatExportCreateParams.builder() .modelUrl("https://example.com/model.glb") .outputFormat(java.util.Arrays.asList("usdz", "obj_zip", "stl")) .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='com') task_id = lux3d.multi_format_export.create( model_url='https://example.com/model.glb', output_format=['usdz', 'obj_zip', 'stl'], ) result = lux3d.tasks.wait_for(task_id) /global/lux3d/v1/articulation-animation/task/create: post: tags: - Lux3D summary: Create Model Articulation and Animation Task description: > Creates an asynchronous articulation and animation task from a GLB model URL and a motion prompt. The response contains a task ID (taskid); use the task query API to retrieve the task status and results. operationId: createArticulationAnimationTaskGlobal requestBody: description: >- Model articulation and animation request. Both glbUrl and prompt are required; additional fields are not accepted. required: true content: application/json: schema: $ref: '#/components/schemas/lux3d_ArticulationAnimationRequest' examples: glbAndPrompt: summary: GLB model and motion prompt value: glbUrl: https://assets.aholo3d.com/examples/cubely/joint-motion/target-model.glb prompt: Keep the base fixed and add a hinge joint so the lid opens and closes slowly. responses: '200': description: Returns the task ID on success. content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: Task created successfully value: f: null c: '0' m: '' d: 3725821 invalidInput: summary: Invalid GLB URL or blank prompt value: f: null c: '-1' m: glbUrl must be an HTTP(S) URL and prompt is required d: null concurrencyLimit: summary: Generation task concurrency limit reached value: f: null c: GENERATION_CONCURRENCY_LIMIT_EXCEEDED m: There is already a generation task in progress. Please wait for it to finish and try again. d: null '400': description: Malformed JSON or unsupported request fields. '401': description: Missing or invalid Authorization header content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] servers: - url: https://api.aholo.ai description: Global x-scalar-order: 8 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'com' }); const taskId = await lux3d.articulationAnimation.create({ glbUrl: 'https://example.com/model.glb', prompt: 'Keep the base fixed and slowly open and close the lid', }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("com")); long taskId = lux3d.articulationAnimation().create( ArticulationAnimationCreateParams.builder() .glbUrl("https://example.com/model.glb") .prompt("Keep the base fixed and slowly open and close the lid") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='com') task_id = lux3d.articulation_animation.create( glb_url='https://example.com/model.glb', prompt='Keep the base fixed and slowly open and close the lid', ) result = lux3d.tasks.wait_for(task_id) /global/lux3d/v1/animations/rig/task/create: post: tags: - Lux3D summary: Create Humanoid Auto-Rigging Task description: > Creates an asynchronous auto-rigging task from a GLB model. The response contains a task ID (taskid); use the task query API to retrieve the task status and rigged GLB file URL. operationId: createHumanoidAutoRigTask requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/lux3d_HumanoidAutoRigRequest' example: modelUrl: https://example.com/model.glb responses: '200': description: On success, c is "0" and d contains the task ID. content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' example: f: null c: '0' m: '' d: 3742500 security: - AuthorizationHeader: [] x-scalar-order: 9 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'com' }); const taskId = await lux3d.humanoidAutoRig.create({ modelUrl: 'https://example.com/human.glb', }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("com")); long taskId = lux3d.humanoidAutoRig().create( HumanoidAutoRigCreateParams.builder() .modelUrl("https://example.com/human.glb") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='com') task_id = lux3d.humanoid_auto_rig.create(model_url='https://example.com/human.glb') result = lux3d.tasks.wait_for(task_id) /global/lux3d/v1/animations/retarget/task/create: post: tags: - Lux3D summary: Create Humanoid Animation Retargeting Task description: > Creates an asynchronous task that applies selected animations to a rigged GLB model. Supports separate or combined output in GLB or FBX format. The response contains a task ID (taskid); use the task query API to retrieve the task status and results. operationId: createHumanoidAnimationRetargetTask requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/lux3d_HumanoidAnimationRetargetRequest' example: rigModelUrl: https://qhstaticssl.kujiale.com/application/octetstream/1790240555913/rigModel.glb animationIds: - Dance_Loop - Swim_Fwd_Loop animationOutputMode: separate outFormat: glb animateInPlace: false responses: '200': description: On success, c is "0" and d contains the task ID. content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' example: f: null c: '0' m: '' d: 3742500 security: - AuthorizationHeader: [] x-scalar-order: 10 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'com' }); const taskId = await lux3d.humanoidAnimationRetarget.create({ rigModelUrl: 'https://example.com/rig.glb', animationIds: ['Idle_Loop', 'Walk_Loop'], outFormat: 'glb', }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("com")); long taskId = lux3d.humanoidAnimationRetarget().create( HumanoidAnimationRetargetCreateParams.builder() .rigModelUrl("https://example.com/rig.glb") .animationIds(java.util.Arrays.asList("Idle_Loop", "Walk_Loop")) .outFormat("glb") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='com') task_id = lux3d.humanoid_animation_retarget.create( rig_model_url='https://example.com/rig.glb', animation_ids=['Idle_Loop', 'Walk_Loop'], out_format='glb', ) result = lux3d.tasks.wait_for(task_id) /global/lux3d/v1/generate/task/get: get: tags: - Lux3D summary: Query Generation Task description: > Returns the status and results of a task created by the authenticated account. A response with `c="0"` means the query succeeded; it does not mean the task has finished. Continue polling while `d.status` is `0` (initialized) or `1` (running). Terminal states are `3` (succeeded), `4` (failed), and `6` (cancelled). Result URLs expire after 2 hours. A running task may include results that have already been produced; check `d.status` to determine whether processing has finished. Read results from `d.outputs[].content` according to the task type: | Task type | Result content and order | | --- | --- | | Multimodal single-image generation | One image URL. | | Multimodal four-view generation | One JSON-array string containing four image URLs in this order: `FRONT_THREE_QUARTER`, `OPPOSITE_THREE_QUARTER`, `SIDE`, `BACK`. | | G1 image-to-3D / text-to-3D | ZIP and GLB URLs, followed by PLY when requested. | | G1-Turbo image-to-3D / text-to-3D | URLs for the requested formats; ZIP when `outputFormat` is omitted or empty. | | Material transfer | ZIP, GLB, USDZ, OBJ ZIP, and FBX ZIP, in that order. | | Multi-format export | ZIP, GLB, USDZ, OBJ ZIP, FBX ZIP, STL, and 3MF, in that order. | | Part splitting | One GLB file URL containing the split parts. | | Articulation and animation | The primary result URL in `d.outputs[0].content`. The file retains its generated format and is not always a ZIP archive. | | Humanoid auto-rigging | A rigged GLB file URL on success, or a JSON string containing `error` on failure. | | Humanoid animation retargeting | A JSON string containing `actions`, with a result URL or error for each action. | For four-view generation and humanoid animation retargeting, parse the JSON string in `content` before reading its fields. Parse auto-rigging error content in the same way. Unrequested optional formats may contain `NOT_REQUESTED`; this is a placeholder, not a downloadable URL. operationId: getTaskGlobal parameters: - name: taskid in: query description: Task ID required: true schema: type: integer format: int64 example: 1389513 responses: '200': description: Returns task status and results on success. content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskQueryResponse' examples: humanoidRigSuccess: summary: Humanoid rigging success value: f: null c: '0' m: '' d: taskId: 3742500 status: 3 outputs: - content: https://example.com/rig.glb humanoidRigFailure: summary: Model is unsuitable for auto-rigging value: f: null c: '0' m: '' d: taskId: 3742500 status: 4 outputs: - content: >- {"error": {"code": "MODEL_NOT_RIGGABLE", "message": "Model does not meet rigging requirements"}} humanoidRetargetGlbSuccess: summary: GLB animation generated successfully value: f: null c: '0' m: '' d: taskId: 3742500 status: 3 outputs: - content: >- {"actions":[{"animation_id":"Dance_Loop","status":"success","animationGlbUrl":"https://example.com/dance.glb"}]} humanoidRetargetAllFailed: summary: All actions failed value: f: null c: '0' m: '' d: taskId: 3742500 status: 4 outputs: - content: >- {"actions":[{"animation_id":"Swim_Fwd_Loop","status":"failed","error":{"code":"ANIMATION_RETARGET_FAILED","message":"Action delivery failed: animation retarget failed"}}]} humanoidRetargetFbxSuccess: summary: FBX action delivered value: f: null c: '0' m: '' d: taskId: 3742500 status: 3 outputs: - content: >- {"actions":[{"animation_id":"Dance_Loop","status":"success","fbxUrl":"https://example.com/dance.fbx"}]} running: summary: Task in progress value: f: null c: '0' m: '' d: taskId: 1389513 status: 1 successMaterialTransferAllFormats: summary: Material transfer with all formats value: f: null c: '0' m: '' d: taskId: 1389513 outputs: - content: https://cdn.example.com/output/result.zip - content: https://cdn.example.com/output/textured.glb - content: https://cdn.example.com/output/RealityKitPreview.usdz - content: https://cos.example.com/lux3d/xxx/model_obj.zip - content: https://cos.example.com/lux3d/xxx/model_fbx.zip status: 3 successMaterialTransferPartialFormats: summary: Material transfer with ZIP, GLB, and USDZ value: f: null c: '0' m: '' d: taskId: 1389514 outputs: - content: https://cdn.example.com/output/result.zip - content: https://cdn.example.com/output/textured.glb - content: https://cdn.example.com/output/RealityKitPreview.usdz - content: NOT_REQUESTED - content: NOT_REQUESTED status: 3 successMultiFormatExport: summary: Multi-format export with all formats value: f: null c: '0' m: '' d: taskId: 1389518 outputs: - content: https://cdn.example.com/input/source.zip - content: https://cdn.example.com/output/model.glb - content: https://cdn.example.com/output/RealityKitPreview.usdz - content: https://cos.example.com/lux3d/xxx/model_obj.zip - content: https://cos.example.com/lux3d/xxx/model_fbx.zip - content: https://cdn.example.com/output/model.stl - content: https://cdn.example.com/output/model.3mf status: 3 successG1Base: summary: G1 task with ZIP and GLB results value: f: null c: '0' m: '' d: taskId: 1389515 outputs: - content: https://cdn.example.com/output/results.zip - content: https://cdn.example.com/output/result.glb status: 3 successG1WithPly: summary: G1 task with ZIP, GLB, and PLY results value: f: null c: '0' m: '' d: taskId: 1389516 outputs: - content: https://cdn.example.com/output/results.zip - content: https://cdn.example.com/output/result.glb - content: https://cdn.example.com/output/result.ply status: 3 successG1TurboPly: summary: G1-Turbo task with PLY result value: f: null c: '0' m: '' d: taskId: 1389517 outputs: - content: https://cdn.example.com/output/result.ply status: 3 successMultimodalToImage: summary: Multimodal single-image generation succeeded value: f: null c: '0' m: '' d: taskId: 2696732 outputs: - content: https://cdn.example.com/multimodal-to-image/result.png status: 3 successArticulationAnimationZIP: summary: Articulation and animation succeeded (ZIP example) value: f: null c: '0' m: '' d: taskId: 3725821 outputs: - content: https://cdn.example.com/articulation-animation/result.zip status: 3 successArticulationAnimationGLB: summary: Articulation and animation succeeded (GLB example) value: f: null c: '0' m: '' d: taskId: 3725821 outputs: - content: https://cdn.example.com/articulation-animation/result.glb status: 3 successImageToFourView: summary: Multimodal four-view generation succeeded value: f: null c: '0' m: '' d: taskId: 2696733 outputs: - content: >- ["https://cdn.example.com/four-view/front-three-quarter.png","https://cdn.example.com/four-view/opposite-three-quarter.png","https://cdn.example.com/four-view/side.png","https://cdn.example.com/four-view/back.png"] status: 3 successPartSplit: summary: Part splitting succeeded value: f: null c: '0' m: '' d: taskId: 2696734 outputs: - content: https://qhsmodel.kujiale.com/glbPartsReconstructResult/NKZXG2IKTIHXGAABAAAAABQ8.glb status: 3 failed: summary: Task failed value: f: null c: '0' m: '' d: taskId: 1389513 status: 4 '401': description: Missing or invalid Authorization header, authentication failed content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskQueryResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskQueryResponse' security: - AuthorizationHeader: [] servers: - url: https://api.aholo.ai description: Global x-scalar-order: 11 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'com' }); const result = await lux3d.tasks.retrieve(taskId); console.log(result.status, result.outputs); // 或 await lux3d.tasks.waitFor(taskId) to poll until success - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("com")); TaskResult result = lux3d.tasks().retrieve(taskId); System.out.println(result.status()); // or lux3d.tasks().waitFor(taskId) to poll until success - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='com') result = lux3d.tasks.retrieve(task_id) print(result.get('status'), result.get('outputs')) # 或 lux3d.tasks.wait_for(task_id) to poll until success /global/lux3d/v1/generate/task/list: get: tags: - Lux3D summary: List Generation Records description: | Lists tasks created by the authenticated account, optionally filtered by status and creation time. operationId: listTasksGlobal parameters: - name: page in: query description: Page number, starting from 1 schema: type: integer minimum: 1 default: 1 - name: pagesize in: query description: Items per page, from 1 to 100 schema: type: integer minimum: 1 maximum: 100 default: 20 - name: status in: query description: >- Task-status filter: 0-initialized, 1-running, 3-succeeded, 4-failed. When omitted, all statuses are returned, so result items may still have status 6 (cancelled). schema: type: integer enum: - 0 - 1 - 3 - 4 - name: starttime in: query description: Inclusive creation-time start as a Unix timestamp in milliseconds schema: type: integer format: int64 minimum: 0 - name: endtime in: query description: Exclusive creation-time end as a Unix timestamp in milliseconds schema: type: integer format: int64 minimum: 0 responses: '200': description: Returns generation records. content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskListResponse' examples: withData: summary: Records found value: f: null c: '0' m: '' d: items: - taskId: 2667998 status: 3 created: 1786591762000 lastModified: 1786592088000 total: 1 page: 1 pageSize: 20 noData: summary: No records found value: f: null c: '0' m: '' d: items: [] total: 0 page: 1 pageSize: 20 '401': description: Missing or invalid Authorization, authentication failed content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskListResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskListResponse' security: - AuthorizationHeader: [] servers: - url: https://api.aholo.ai description: Global x-scalar-order: 12 x-codeSamples: - lang: TypeScript label: Aholo SDK (TypeScript) source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'com' }); const page = await lux3d.tasks.list({ page: 1, pageSize: 20, status: 3 }); page.items.forEach((task) => console.log(task.taskId, task.status)); - lang: Java label: Aholo SDK (Java) source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("com")); TaskPagedList page = lux3d.tasks().list( TaskListParams.builder().page(1).pageSize(20).status(3).build()); page.items().forEach(task -> System.out.println(task.taskId() + " " + task.status())); - lang: Python label: Aholo SDK (Python) source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='com') page = lux3d.tasks.list(page=1, page_size=20, status=3) for task in page['items']: print(task['taskId'], task['status']) /global/rendercloud/v1/jobs: post: tags: - RenderCloud summary: Submit or poll an OpenUSD offline render job description: > Submit an OpenUSD offline render job or poll the status of an existing job. ## Submit mode When `operationId` is empty, a new job is submitted. `requestId` and Base64-encoded `usdContent` are required. The output resolution is read from OpenUSD `RenderSettings.resolution`, with Camera `resolution` supported as a compatibility fallback. Width and height must be positive, and neither side may exceed the server-side configured limit. The default limit is 4500 pixels. The server returns HTTP 202 with `{operationId, metaData:null, done:false, result:null, error:null}`. The `operationId` is the render task ID. `requestId` is generated by the caller and used for request tracing and records. The server applies a 1-minute idempotency guard for the same user and the same `requestId`. If the same user submits the same `requestId` again within 1 minute, the API returns 409 `ALREADY_EXISTS`. ## Poll mode When `operationId` is present, the same POST endpoint polls the job status. - Processing: `done=false` - Succeeded: `done=true + result.taskId/resultUrl` - Failed: `done=true + error` ## Rendering constraints This API does not accept server-side rendering template parameters. The service selects a fixed offline rendering pipeline according to the OpenUSD content and output resolution. ## REST response statuses | HTTP status | Scenario | Response | |-----------|------|---------| | `202` | Submit mode | Job accepted; returns `operationId` for polling | | `200` | Poll mode | Returns current `Operation`; completed responses include `resultUrl` | | `400` | Invalid argument | Missing `requestId` or `usdContent`; missing/invalid OpenUSD resolution; invalid Base64; or OpenUSD parse failure | | `404` | Not found | No job exists for `operationId` | | `409` | Duplicate request | The same user submitted the same `requestId` again within 1 minute | | `429` | Rate limited | User-level offline render frequency exceeded | | `500` | Internal error | Job creation, conversion, or render dispatch failed | operationId: runRenderCloudOfflineJob requestBody: description: >- Offline render submit or poll request body. Submit with `requestId` and `usdContent`; poll with only `operationId`. required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/rendercloud_OfflineRenderSubmitRequest' - $ref: '#/components/schemas/rendercloud_OperationPollRequest' examples: submit: summary: Submit an offline render job description: Create an offline render job from OpenUSD content. Output resolution is read from OpenUSD resolution. value: requestId: render-req-20260515-0001 usdContent: I3VzZGEgMS4wCg== poll: summary: Poll offline render result description: Use the `operationId` returned by submit to query the job status or result. value: operationId: '1305220918472257536' responses: '200': description: Current offline render operation status. content: application/+json: schema: oneOf: - $ref: '#/components/schemas/rendercloud_OfflineRenderProcessingOperation' - $ref: '#/components/schemas/rendercloud_OfflineRenderSuccessOperation' - $ref: '#/components/schemas/rendercloud_OperationError' examples: processing: summary: Job processing description: The offline render job is still processing. value: operationId: '1305220918472257536' metaData: null done: false result: null error: null success: summary: Render succeeded description: The offline render job finished and returned the rendered image URL. value: operationId: '1305220918472257536' metaData: null done: true result: taskId: '1305220918472257536' resultUrl: https://example.com/render/result.png error: null failed: summary: Render failed description: The offline render job failed and returned an error. value: operationId: '1305220918472257536' metaData: null done: true result: null error: code: 500 message: >- code: INTERNAL, details: ErrorDetails(reason=INTERNAL_ERROR, message=null, domain=render, metaData=null) status: INTERNAL details: reason: INTERNAL_ERROR domain: render '202': description: Offline render job accepted and still processing. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_OfflineRenderProcessingOperation' examples: processing: summary: Job processing description: The offline render job has been created but is not finished yet. value: operationId: '1305220918472257536' metaData: null done: false result: null error: null '400': $ref: '#/components/responses/rendercloud_BadRequest' '404': $ref: '#/components/responses/rendercloud_NotFound' '409': $ref: '#/components/responses/rendercloud_Conflict' '429': $ref: '#/components/responses/rendercloud_TooManyRequests' '500': $ref: '#/components/responses/rendercloud_InternalServerError' x-scalar-order: 3 /global/rendercloud/v1/streams: post: tags: - RenderCloud summary: Create or poll an OpenUSD realtime render stream description: > Create a realtime render session or poll an existing session. ## Submit mode When `operationId` is empty, a new session is created. `requestId` and `usdContent` are required. Optional `settings.autoEnhanceAI` enables AI enhancement. Omit it or set it to `false` to disable enhancement. The server returns HTTP 202 with `{operationId, metaData:null, done:false, result:null, error:null}`. The returned `operationId` is the `sessionId`. ## Poll mode When `operationId` is present, poll the session status. Recommended polling interval is 2 seconds; timeout is 120 seconds. When `status` is `ACTIVE`, `result` contains `host`, `nodeId`, `streamId`, and `token`, which are required to open the WebSocket Streaming connection. ## REST response statuses | HTTP status | Scenario | Response | |-----------|------|---------| | `202` | Submit mode | Session is being created; returns `operationId` for polling | | `200` | Poll mode | Current `Operation`; processing is `done=false`, success is `done=true + result`, failure is `done=true + error` | | `400` | Invalid argument | Request body is missing required fields or contains invalid values | | `404` | Not found | `operationId` or session does not exist | | `429` | Rate limited | Request frequency exceeded | | `500` | Internal error | Internal server error | ## WebSocket Streaming protocol ### Connection URL ``` wss://{host}/streaming/ws/session?nid={encodeURIComponent(nodeId)}&token={encodeURIComponent(token)} ``` Set `ws.binaryType = 'blob'` when creating the WebSocket; otherwise image frames cannot be received as Blob objects. ### Handshake Immediately after WebSocket `onopen`, send: ```json {"type":3,"slaveInit":{"masterStreamingId":"{streamId}","receiveImage":true}} ``` | Field | Value | Description | |------|-----|------| | type | fixed `3` | Slave initialization message | | slaveInit.masterStreamingId | `{streamId}` | The streamId returned by this API | | slaveInit.receiveImage | fixed `true` | Receive rendered images | ### Server messages JSON status messages are received when `typeof event.data === 'string'`. Binary image messages are JPEG Blob objects. Convert the Blob with `FileReader.readAsDataURL(blob)` before assigning it to an `` source. Status codes: | code | Meaning | Connection state change | |------|------|-------------| | `"0"` | Initialized | Success | | `"1000"` | Node overloaded | Error | | `"1001"` | Initialization failed | Error | | `"1003"` | Slave limit exceeded | SlaveExceeded | | `"2001"` | Engine render error | No connection state change; only render failure callback | | `"2002"` | Engine process error | No connection state change; only render failure callback | Close the WebSocket first, then call the DELETE API to end the server-side session. operationId: createRenderCloudRealtimeStream requestBody: description: >- Realtime render stream creation or poll request body. Create with `requestId`, `usdContent`, and optional `settings` (currently `autoEnhanceAI`); poll with only `operationId`. required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/rendercloud_RealtimeSessionSubmitRequest' - $ref: '#/components/schemas/rendercloud_OperationPollRequest' examples: submit: summary: Create a realtime render stream description: Create a render stream with AI enhancement enabled. value: requestId: stream-req-20260515-0001 usdContent: I3VzZGEgMS4wCg== settings: autoEnhanceAI: true poll: summary: Poll realtime render stream description: Use the `operationId` returned by creation to query stream status. value: operationId: '1305220918472257536' responses: '200': description: >- Realtime render stream polling result. When status is ACTIVE, result contains WebSocket connection parameters. content: application/+json: schema: oneOf: - $ref: '#/components/schemas/rendercloud_RealtimeSessionProcessingOperation' - $ref: '#/components/schemas/rendercloud_RealtimeSessionSuccessOperation' - $ref: '#/components/schemas/rendercloud_OperationError' examples: processing: summary: Creating description: The realtime render stream is still initializing. value: operationId: '1305220918472257536' metaData: null done: false result: null error: null success: summary: Created description: The realtime render stream is ready and returns connection parameters. value: operationId: '1305220918472257536' metaData: null done: true result: sessionId: '1305220918472257536' status: ACTIVE currentQueuePosition: 0 host: stream.example.com nodeId: node-01 streamId: stream-1305220918472257536 token: stream-token error: null failed: summary: Creation failed description: The realtime render stream failed to initialize. value: operationId: '1305220918472257536' metaData: null done: true result: null error: code: 500 message: >- code: INTERNAL, details: ErrorDetails(reason=INTERNAL_ERROR, message=null, domain=render, metaData=null) status: INTERNAL details: reason: INTERNAL_ERROR domain: render '202': description: Session creation is in progress. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_RealtimeSessionProcessingOperation' examples: processing: summary: Session creating description: The submit response. `operationId` is the sessionId. value: operationId: '1305220918472257536' metaData: null done: false result: null error: null '400': $ref: '#/components/responses/rendercloud_BadRequest' '404': $ref: '#/components/responses/rendercloud_NotFound' '429': $ref: '#/components/responses/rendercloud_TooManyRequests' '500': $ref: '#/components/responses/rendercloud_InternalServerError' x-scalar-order: 4 /global/rendercloud/v1/streams/{sessionId}:push: post: tags: - RenderCloud summary: Push incremental OpenUSD content to a realtime render stream description: > Apply incremental scene updates to an established realtime render session. This API is used after the WebSocket Streaming session is ready. It pushes Base64-encoded incremental OpenUSD content to the server. The incremental content may describe camera, model, light, or environment-light patches; the server converts it into render operations and dispatches it to the realtime render pipeline. See the `RenderCloud OpenUSD Format Guide` for the USDA formats. ## Requirements - `sessionId` must be the `operationId` returned by `/rendercloud/v1/streams` after creation. - Session status must be `ACTIVE`, otherwise the update is rejected. - `requestId` is generated by the caller for idempotency and request records. - `usdContent` is Base64-encoded incremental OpenUSD content. ## REST response statuses | HTTP status | Scenario | Response | |-----------|------|---------| | `200` | Updated | Returns session ID and current session status | | `400` | Invalid argument | Missing `requestId` or `usdContent`, or invalid request body | | `404` | Not found | No session exists for `sessionId` | | `429` | Rate limited | User-level realtime render frequency exceeded | | `500` | Internal error | Session is not ACTIVE, forwarding failed, or update was rejected by the render pipeline | operationId: pushRenderCloudRealtimeStreamUpdate parameters: - $ref: '#/components/parameters/rendercloud_SessionId' requestBody: description: >- Realtime render stream incremental update request body. `usdContent` is Patch USDA for a camera, model, light, or environment light. required: true content: application/json: schema: $ref: '#/components/schemas/rendercloud_RealtimeSessionUpdateRequest' examples: update: summary: Push incremental content description: >- Push camera, model, light, or environment-light Patch OpenUSD content to an existing realtime render stream. value: requestId: stream-update-20260515-0001 usdContent: I3VzZGEgMS4wCg== responses: '200': description: Incremental content pushed successfully. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_RealtimeSessionUpdateResponse' examples: success: summary: Updated description: Session remains ACTIVE and incremental content has been sent to the realtime render pipeline. value: sessionId: '1305220918472257536' status: ACTIVE '400': $ref: '#/components/responses/rendercloud_BadRequest' '404': $ref: '#/components/responses/rendercloud_NotFound' '429': $ref: '#/components/responses/rendercloud_TooManyRequests' '500': $ref: '#/components/responses/rendercloud_InternalServerError' x-scalar-order: 5 /global/rendercloud/v1/streams/{sessionId}: delete: tags: - RenderCloud summary: Close a realtime render stream description: > Close the specified realtime render session and release server-side resources. When closing a realtime render stream, close the WebSocket first, then call this API to end the server-side session. The server releases resources related to the realtime rendering session. ## REST response statuses | HTTP status | Scenario | Response | |-----------|------|---------| | `200` | Closed | `closed=true` means the server found and closed the session; `closed=false` means the session no longer exists or was already cleaned up | | `404` | Not found | The node that owns the session reports that the session does not exist | | `429` | Rate limited | User-level realtime render frequency exceeded | | `500` | Internal error | Forwarding failed or an internal server error occurred | operationId: closeRenderCloudRealtimeStream parameters: - $ref: '#/components/parameters/rendercloud_SessionId' responses: '200': description: Realtime render stream closed. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_RealtimeSessionCloseResponse' examples: closed: summary: Closed description: The server found and closed the session. value: sessionId: '1305220918472257536' closed: true alreadyGone: summary: Session already gone description: The session was already closed, timed out, cleaned up, or is not on the current node. value: sessionId: '1305220918472257536' closed: false '404': $ref: '#/components/responses/rendercloud_NotFound' '429': $ref: '#/components/responses/rendercloud_TooManyRequests' '500': $ref: '#/components/responses/rendercloud_InternalServerError' x-scalar-order: 6 /global/rendercloud/v1/mesh-upload-process/task/create: post: tags: - RenderCloud summary: Create a 3D parsing and ingestion task description: > Create a 3D parsing and ingestion task to process a raw 3D file URL. Specify the original 3D file URL with `originMeshUrl`. The optional `fastUpload` field enables fast upload and defaults to `false`. When `fastUpload` is `true` and the file is in GLB format, the fast upload workflow is used. If omitted or set to `false`, the standard upload workflow is used. ## REST Response Status | HTTP Status | Scenario | Response Description | |-----------|------|---------| | `200` | Task created successfully | Returns the task ID | | `400` | Invalid arguments | `originMeshUrl` missing or invalid | | `500` | Internal error | Task creation or processing error | operationId: createMeshUploadAndProcessTask requestBody: description: Mesh upload and process task request body. required: true content: application/json: schema: $ref: '#/components/schemas/rendercloud_MeshUploadProcessRequest' examples: submit: summary: Create a 3D parsing and ingestion task description: >- Submit a raw Mesh URL using the standard upload workflow. fastUpload can also be omitted and defaults to false. value: originMeshUrl: https://example.com/mesh/original.glb fastUpload: false fastSubmit: summary: Create a fast GLB upload task description: Submit an original GLB file URL and enable fast upload. value: originMeshUrl: https://example.com/mesh/original.glb fastUpload: true responses: '200': description: Mesh upload and parse task created successfully. content: application/json: schema: $ref: '#/components/schemas/rendercloud_TaskCreateResponse' examples: success: summary: Task created successfully description: Returns the task ID for subsequent queries. value: success: true data: 1272794 errorMsg: null '400': description: Invalid request arguments. content: application/json: schema: $ref: '#/components/schemas/rendercloud_CommonErrorResponse' examples: invalidArgument: summary: Invalid arguments description: originMeshUrl missing or invalid. value: success: false data: null errorMsg: originMeshUrl cannot be empty '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/rendercloud_CommonErrorResponse' examples: internalError: summary: Internal error description: Task creation or processing error. value: success: false data: null errorMsg: System error x-scalar-order: 1 /global/rendercloud/v1/mesh-upload-process/task/get: get: tags: - RenderCloud summary: Query 3D parsing and ingestion task status description: > Query the status and result of a specified 3D parsing and ingestion task. This API is used to query the task execution status and result. During the query, data that should not be exposed to users is filtered out, and the output data is wrapped for processing. Task status: `0`=INIT, `1`=RUNNING, `3`=SUCCESS, `4`=FAIL ## Requirements - `taskid` must come from the task ID returned by the task creation API ## REST Response Status | HTTP Status | Scenario | Response Description | |-----------|------|---------| | `200` | Query succeeded | Returns task details | | `400` | Invalid arguments | `taskid` missing or invalid | | `404` | Task not found | Specified task ID does not exist | | `500` | Internal error | Query error | operationId: getRenderCloudInstanceInAholo parameters: - name: taskid in: query required: true description: Task ID. schema: type: integer format: int64 responses: '200': description: Task query succeeded. content: application/json: schema: $ref: '#/components/schemas/rendercloud_TaskQueryResponse' examples: processing: summary: Job processing description: Task is currently executing. value: success: true data: taskId: 1272794 status: 1 outputs: null errorMsg: null success: summary: Task completed description: Task execution completed, returning the result. value: success: true data: taskId: 1272794 status: 3 outputs: - content: YYZN2MZVAIQLEPTULM888888 sourceReferId: '607583273' errorMsg: null '400': description: Invalid request arguments. content: application/json: schema: $ref: '#/components/schemas/rendercloud_CommonErrorResponse' examples: invalidArgument: summary: Invalid arguments description: taskid missing or invalid. value: success: false data: null errorMsg: taskid cannot be empty '404': description: Task not found. content: application/json: schema: $ref: '#/components/schemas/rendercloud_CommonErrorResponse' examples: notFound: summary: Task not found description: Specified task ID does not exist. value: success: false data: null errorMsg: Task not found '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/rendercloud_CommonErrorResponse' examples: internalError: summary: Internal error description: Query error. value: success: false data: null errorMsg: System error x-scalar-order: 2 /global/spatial-understanding/v1/tasks: post: tags: - SpatialUnderstanding summary: Create spatial understanding task description: >- Creates an async spatial understanding task that detects walls, doors, windows, and object 3D bboxes from an indoor point cloud. `inputFileUrl` must be a `.ply` URL from Asset upload. The point-cloud coordinate system is meters, right-handed, Z-up; if it is not aligned, pass `transformationMatrix` (translation in the 4th column). Credits are deducted on acceptance. Returns `taskId` only (same as the path parameter of **Get spatial understanding task details**). After the task succeeds, details include `result.resultSslUrl` as a DSL text file — download and parse it yourself. operationId: createSpatialUnderstandingTask requestBody: description: >- Create-task body. `inputFileUrl` is required and must be an indoor `.ply` URL from Asset upload. Optional `transformationMatrix` aligns the cloud to meters, right-handed, Z-up. content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_CreateSpatialUnderstandingTaskRequest' examples: createWithoutMatrix: summary: Point cloud only, no transform description: createWithoutMatrix value: inputFileUrl: https://holo-cos.aholo3d.cn/resource/openapi/xxx.ply createWithMatrix: summary: Include a 4×4 transform (rotation and translation; translation in the 4th column) description: createWithMatrix value: inputFileUrl: https://holo-cos.aholo3d.cn/resource/openapi/xxx.ply transformationMatrix: - - 0.9337461173020494 - 0.3579360116324523 - 0 - 1.871216953359744 - - -0.3579360116324523 - 0.9337461173020494 - 0 - -0.2091883674268249 - - 0 - 0 - 0.9999999999999999 - 1.2121098756790158 - - 0 - 0 - 0 - 1 required: true responses: '200': description: Accepted. Returns `taskId` for polling task details. content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_SpatialUnderstandingTaskAsyncOperation' examples: success: summary: Create accepted description: success value: taskId: A1b2C3d4E5 '400': description: >- Validation failed, invalid point-cloud URL, invalid transform matrix, or insufficient credits (`details.metaData.bizCode` is the business code) content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_ApiError' examples: paramsInvalid: summary: Body validation failed (e.g. empty inputFileUrl) description: Business code 10001 value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo.ai message: Invalid request parameters metaData: bizCode: '10001' invalidInputUrl: summary: inputFileUrl is invalid or not a .ply description: Business code 13001. Use a `.ply` URL returned by the Asset upload APIs. value: code: 400 message: invalid file url, please upload a .ply file via the Asset module APIs status: INVALID_ARGUMENT details: reason: BIZ_13001 domain: api.aholo.ai message: invalid file url, please upload a .ply file via the Asset module APIs metaData: bizCode: '13001' invalidTransformationMatrix: summary: Invalid transform matrix description: Business code 13002. Must be a 4×4 array of valid numbers. value: code: 400 message: invalid transformation matrix, expect a 4x4 numeric array status: INVALID_ARGUMENT details: reason: BIZ_13002 domain: api.aholo.ai message: invalid transformation matrix, expect a 4x4 numeric array metaData: bizCode: '13002' insufficientCredits: summary: Insufficient credits description: Business code 24002, insufficient credits value: code: 400 message: insufficient credits status: FAILED_PRECONDITION details: reason: BIZ_24002 domain: api.aholo.ai message: insufficient credits metaData: bizCode: '24002' '401': description: Missing or invalid Authorization content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_ApiError' examples: notLoggedIn: summary: Missing or invalid API key description: Business code 10004 value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo.ai message: Not logged in metaData: bizCode: '10004' security: - AuthorizationHeader: [] x-scalar-order: 10 /global/spatial-understanding/v1/tasks/{taskId}: get: tags: - SpatialUnderstanding summary: Get spatial understanding task details description: >- Get details for a task owned by the current account. `PENDING` / `RUNNING` means it is not finished — keep polling. On `SUCCEEDED`, the response includes `result.resultSslUrl` (DSL text with Wall / Door / Window / Bbox; download and parse it yourself). On `FAILED` / `TIMEOUT`, the response includes `errorCode` and `errorMessage`. operationId: getSpatialUnderstandingTaskDetail parameters: - name: taskId in: path description: Task id (same as `taskId` in the create success response) required: true schema: minLength: 1 type: string example: A1b2C3d4E5 responses: '200': description: Task details. content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_SpatialUnderstandingTask' examples: pending: summary: Queued, no result yet description: pending value: taskId: A1b2C3d4E5 status: PENDING modelVersion: spatiallm-pointcloud-1.2-20260910 createTime: 1699339916000 updateTime: 1699339916000 succeeded: summary: Finished, includes result URL description: succeeded value: taskId: A1b2C3d4E5 status: SUCCEEDED modelVersion: spatiallm-pointcloud-1.2-20260910 result: resultSslUrl: https://holo-cos.aholo3d.cn/resource/openapi/xxx-result.txt createTime: 1699339916000 updateTime: 1699340120000 failed: summary: Failed, includes error code and message description: failed value: taskId: A1b2C3d4E5 status: FAILED modelVersion: spatiallm-pointcloud-1.2-20260910 errorCode: MODEL_TASK_FAILED errorMessage: task failed createTime: 1699339916000 updateTime: 1699340120000 '401': description: Missing or invalid Authorization content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_ApiError' examples: notLoggedIn: summary: Missing or invalid API key description: Business code 10004 value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo.ai message: Not logged in metaData: bizCode: '10004' '404': description: Task not found, or you cannot access it content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_ApiError' examples: taskNotFound: summary: Task not found description: Business code 13003 value: code: 404 message: spatial understanding task not found status: NOT_FOUND details: reason: BIZ_13003 domain: api.aholo.ai message: spatial understanding task not found metaData: bizCode: '13003' security: - AuthorizationHeader: [] x-scalar-order: 20 /global/spatial-understanding/v1/tasks/list: post: tags: - SpatialUnderstanding summary: List my spatial understanding tasks description: >- Paginate spatial understanding tasks for the current account, optionally filtered by status. `pageNum` starts at 1 (`0` and `1` both mean the first page). If `pageSize` is omitted or `0`, it defaults to 20; maximum is 100. operationId: getMySpatialUnderstandingTaskList requestBody: description: Paging and filter conditions. content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_SpatialUnderstandingTaskListQueryRequest' examples: listTaskRequest: description: Example — page 1, 20 per page, filter RUNNING and SUCCEEDED value: pageNum: 1 pageSize: 20 statusList: - RUNNING - SUCCEEDED required: true responses: '200': description: Paged list with `pageNum`, `pageSize`, and the current page of tasks. content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_SpatialUnderstandingTaskPagedList' examples: success: summary: List succeeded description: success value: pageNum: 1 pageSize: 20 count: 2 totalCount: 2 hasMore: false result: - taskId: A1b2C3d4E5 status: RUNNING modelVersion: spatiallm-pointcloud-1.2-20260910 createTime: 1699339916000 updateTime: 1699339916000 - taskId: B2c3D4e5F6 status: SUCCEEDED modelVersion: spatiallm-pointcloud-1.2-20260910 result: resultSslUrl: https://holo-cos.aholo3d.cn/resource/openapi/xxx-result.txt createTime: 1699339800000 updateTime: 1699340120000 '400': description: Invalid paging parameters content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_ApiError' examples: paramsInvalid: summary: Body / paging validation failed description: Business code 10001, e.g. pageSize outside [0, 100] value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo.ai message: Invalid request parameters metaData: bizCode: '10001' '401': description: Missing or invalid Authorization content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_ApiError' examples: notLoggedIn: summary: Missing or invalid API key description: Business code 10004 value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo.ai message: Not logged in metaData: bizCode: '10004' security: - AuthorizationHeader: [] x-scalar-order: 30 components: schemas: asset_UploadTokenOuterOpen: type: object properties: ousToken: type: string description: 'Upload token. For OUS host requests set header `ous-token-v2: `.' example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... globalDomain: type: string description: OUS global host (no path); upload/part requests go here. example: https://ous-sg.kujiale.com blockSize: type: integer description: Part size threshold (bytes); larger files use multipart. format: int64 example: 1048576 description: OUS credential for direct upload on `globalDomain`; header `ous-token-v2`; full flow under **Upload** `ousCos*`. asset_ApiError: required: - code - details - message - status type: object properties: code: type: integer description: HTTP status code format: int32 example: 403 message: type: string description: Developer-facing error message (English); use `localizedMessage` for user-visible localized text. example: Permission denied to access this resource status: $ref: '#/components/schemas/asset_Code' details: $ref: '#/components/schemas/asset_ErrorDetails' localizedMessage: $ref: '#/components/schemas/asset_LocalizedMessage' help: $ref: '#/components/schemas/asset_Help' description: API error response with status, details, and optional help. asset_Code: type: string description: REST API status code per Google API design guidelines. example: PERMISSION_DENIED enum: - OK - CANCELLED - UNKNOWN - INVALID_ARGUMENT - DEADLINE_EXCEEDED - NOT_FOUND - ALREADY_EXISTS - PERMISSION_DENIED - UNAUTHENTICATED - RESOURCE_EXHAUSTED - FAILED_PRECONDITION - ABORTED - OUT_OF_RANGE - UNIMPLEMENTED - INTERNAL - UNAVAILABLE - DATA_LOSS - PARTIAL_ELEMENT_UPDATE_FAILED asset_ErrorDetails: required: - reason type: object properties: reason: maxLength: 63 pattern: '[A-Z][A-Z0-9_]+[A-Z0-9]' type: string description: Error reason identifier in UPPER_SNAKE_CASE (max 63 characters). example: RESOURCE_NOT_FOUND message: type: string description: Human-readable explanation with error context. nullable: true example: The requested design with ID 12345 does not exist domain: type: string description: Error domain, usually the service that produced the error. nullable: true example: restapi.qunhe.com metaData: type: object additionalProperties: type: string description: Additional metadata as key/value pairs (keys up to 64 chars, pattern /[a-zA-Z0-9-_]/). nullable: true example: '{"instanceLimitPerRequest":"100","currentInstanceCount":"150"}' description: Additional metadata as key/value pairs (keys up to 64 chars, pattern /[a-zA-Z0-9-_]/). nullable: true example: instanceLimitPerRequest: '100' currentInstanceCount: '150' description: 'Error details: reason, domain, and metadata.' asset_Help: required: - desc - url type: object properties: desc: type: string description: Description of the linked help document. example: How to resolve permission denied errors url: type: string description: URL of the help document example: https://docs.example.com/errors/permission-denied description: Help link and description for resolving the error. nullable: true asset_LocalizedMessage: required: - locale - message type: object properties: locale: type: string description: Locale identifier for the message example: zh_CN message: type: string description: Localized error text for end users example: You do not have permission to access this resource description: Localized message for a specific locale. nullable: true asset_OusCosSingleUploadForm: required: - file - md5 type: object properties: md5: type: string description: File MD5, lowercase hex example: d41d8cd98f00b204e9800998ecf8427e file: type: string description: Full file body to upload format: binary description: '`multipart/form-data` fields (client supplies boundary).' asset_OusCosBlockUploadInitRequest: required: - blocks - md5 - name - size type: object properties: md5: type: string description: Whole-file MD5, lowercase hex example: e99a18c428cb38d5f260853678922e03 blocks: minimum: 1 type: integer description: Total parts ≈ ceil(fileSize / blockSize); `blockSize` from token. format: int64 example: 11 size: minimum: 1 type: integer description: File size in bytes format: int64 example: 10616832 name: type: string description: Original file name example: photo.jpg metadata: type: string description: Metadata (optional) customPrefix: type: string description: Custom storage prefix (optional) customFilename: type: string description: Custom file name (optional) description: Multipart init parameter semantics (same as **query** on `POST …/block/upload/init`; not a JSON body). asset_OusCosBlockUploadPartForm: required: - block - file type: object properties: block: minimum: 1 type: integer description: Part index from 1 up to `blocks` from init format: int32 example: 1 file: type: string description: Binary bytes for this part format: binary description: '`multipart/form-data` fields `block` + `file`' asset_OusV2UploadTaskStatus: type: integer description: |- Read `d.status` when polling `GET /ous/api/v2/upload/status`. **Guide**: `5` success (use `url`); `6`/`8` terminal failure—stop polling; others keep polling. | Value | Meaning | Terminal | |---|---|---| | 0 | Draft | No | | 1 | Basic checks done | No | | 2 | Content checks done | No | | 3 | Queued | No | | 4 | Uploading | No | | 5 | Success | **Yes** | | 6 | Failed | **Yes** | | 7 | Reviewing | No | | 8 | Aborted | **Yes** | format: int32 enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 asset_OusV2BusinessErrorCode: type: integer description: |- Use `errorCode` in non-success responses for retries/metrics (field names vary). | Code | Meaning | Suggestion | |---|---|---| | 1 | Config error | Check upload config | | 2 | Bad file size | Check size / parts | | 3 | Bad format | Change format / retry | | 4 | Bad content | Change content | | 5 | Safety check failed | Change asset | | 6 | Upload throttled | Backoff / fewer concurrent | | 7 | Uploading | Poll / retry later | | 8 | Part failed | Retry parts / restart | | 9 | Server limit | Backoff | | 10 | Pool full | Backoff | | 11 | Metadata too large | Shrink metadata | | 12 | Token issue | Re-fetch token / re-init | | 13 | Task issue | New task | format: int32 enum: - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 13 asset_OusV2BlockInitData: required: - taskId type: object properties: taskId: type: integer description: Task id; bound to the token for subsequent status polling. format: int64 example: 123456789 lackBlocks: type: array description: Missing part indexes (`a-b` ranges); `null` if not resuming. nullable: true items: type: string example: 1-3 progress: type: number description: Progress [0,1]; `null` if N/A. format: double nullable: true example: 0.6 deduplicated: type: boolean description: 'Dedup: `true` means file exists—skip parts, poll `status`.' nullable: true example: false description: Multipart init result (V2). asset_OusV2BlockInitApiResponse: required: - c - d type: object properties: c: type: string description: Business code; `0` is success. example: '0' m: type: string description: Message; may be empty. example: '' d: $ref: '#/components/schemas/asset_OusV2BlockInitData' description: 'Init 200 body: when `c` is `0`, `d` has multipart task info.' asset_OusV2SingleUploadData: required: - taskId type: object properties: taskId: type: string description: Upload task id; bound to the token for subsequent status polling. example: task_id description: Returned on single-file success. asset_OusV2SingleUploadApiResponse: required: - c - d type: object properties: c: type: string description: Business code; `0` is success. example: '0' m: type: string description: Message; may be empty. example: '' d: $ref: '#/components/schemas/asset_OusV2SingleUploadData' description: Single-file upload HTTP 200 body (`c` is `0`, `d` contains `taskId`). asset_OusV2BlockPartApiResponse: required: - c - d type: object properties: c: type: string description: Business code; `0` is success. example: '0' m: type: string description: Message; may be empty. d: description: On success `d` is `null`. nullable: true description: Part upload success; `d` null when `c` is 0. Failures see `OusV2BusinessErrorCode` (e.g. 6). asset_OusV2StatusPollDataSingle: type: object properties: status: $ref: '#/components/schemas/asset_OusV2UploadTaskStatus' uploadKey: type: string description: Object key path. example: heihei/2026/02/03/NGA5S6IKBIDN3RSQAAAAAAA8.jpg url: type: string description: Public resource URL. format: uri md5: type: string description: File MD5, lowercase hex. obsTaskId: type: string description: OUS task/object id. example: 3FO4K029K4A3 description: Typical `d` for **single-file** status polling; see `OusV2UploadTaskStatus`. asset_OusV2StatusBlockProgress: type: object properties: obsId: type: string description: Multipart sub-task id. status: $ref: '#/components/schemas/asset_OusV2UploadTaskStatus' progressPercent: type: integer description: Progress percent. format: int32 example: 100 lackBlocks: type: array description: Missing parts (same encoding as init). items: type: string description: Aggregated multipart progress in `d.blockUpload`; see `OusV2UploadTaskStatus`. asset_OusV2StatusPollDataBlock: type: object properties: obsTaskId: type: string description: Task id. status: $ref: '#/components/schemas/asset_OusV2UploadTaskStatus' uploadKey: type: string url: type: string format: uri md5: type: string errorCode: nullable: true allOf: - $ref: '#/components/schemas/asset_OusV2BusinessErrorCode' errorMsg: type: string nullable: true blockUpload: $ref: '#/components/schemas/asset_OusV2StatusBlockProgress' errorInfo: type: string description: Extra error detail; may be null. nullable: true description: Typical `d` for **multipart** polling; see `OusV2UploadTaskStatus` / `OusV2BusinessErrorCode`. asset_OusV2UploadStatusApiResponse: required: - c - d type: object properties: c: type: string description: Business code; `0` is success. example: '0' m: type: string description: Message; may be empty. d: description: '`oneOf` single-file vs multipart shapes.' oneOf: - $ref: '#/components/schemas/asset_OusV2StatusPollDataSingle' - $ref: '#/components/schemas/asset_OusV2StatusPollDataBlock' description: Status poll response; `d` is one of single/multipart shapes; `d.status` in `OusV2UploadTaskStatus`. world_CreateWorldRequest: required: - resources - scene - taskQuality type: object properties: name: type: string description: Display name example: Living room reconstruction cover: type: string description: Cover image URL (optional) example: https://cdn.example.com/cover/custom-cover.jpg resources: minItems: 1 type: array description: >- Input resources (≥1). Formats see CreateWorldRequest description (image: .jpg / .jpeg / .png / .webp; video: .mp4 / .mov; insv: .insv). With images, need ≥20 image entries (`type=image` or omit); for video set `type=video`; for Insta360 panoramic video set `type=insv`. items: $ref: '#/components/schemas/world_WorldResourceItem' useMask: type: boolean description: Whether to segment uploaded resources. `true` enables matting; omit or `false` to skip. example: false taskQuality: $ref: '#/components/schemas/world_WorldOpenApiTaskQuality' scene: $ref: '#/components/schemas/world_WorldOpenApiProjectScene' description: > Body for **Create 3DGS world reconstruction**. `scene` is `model` or `space`; see `WorldOpenApiTaskQuality` for `taskQuality` (`low` fast preview / `normal` standard / `high` professional). **Resource formats**: image: .jpg / .jpeg / .png / .webp; video: .mp4 / .mov; insv: .insv. **Counts**: if any image-type resource (`type=image` or omit `type`), need **≥20** image entries; for video or Insta360 panoramic video, set `type=video` or `type=insv` on each (no 20-image rule). world_WorldOpenApiProjectScene: type: string description: 'Scene type: `model` object scene; `space` indoor.' example: space enum: - model - space world_WorldOpenApiResourceType: type: string description: >- Input resource type. `image`: images, supports .jpg / .jpeg / .png / .webp; `video`: standard video, supports .mp4 / .mov; `insv`: Insta360 panoramic video, supports .insv. example: image enum: - image - video - insv world_WorldOpenApiTaskQuality: type: string description: 'Reconstruction quality tier: `low` fast preview; `normal` standard; `high` professional.' example: high enum: - low - normal - high world_WorldResourceItem: required: - url type: object properties: url: minLength: 1 type: string description: >- Resource URL; file extension must match `type` (image: .jpg / .jpeg / .png / .webp; video: .mp4 / .mov; insv: .insv). example: https://cdn.example.com/input/room-001.jpg type: $ref: '#/components/schemas/world_WorldOpenApiResourceType' description: >- One reconstruction input resource. Omit `type` → image; standard video → `video`; Insta360 panoramic video → `insv`. image: .jpg / .jpeg / .png / .webp; video: .mp4 / .mov; insv: .insv. world_WorldAsyncOperation: required: - worldId type: object properties: worldId: type: string description: World id; use as `{worldId}` in `GET /global/world/v1/{worldId}` to poll status and outputs. example: A1b2C3d4E5 description: 'Async create acceptance: returns `worldId` for polling details until a terminal state.' world_ApiError: required: - code - details - message - status type: object properties: code: type: integer description: HTTP status code format: int32 example: 403 message: type: string description: Developer-facing error message (English); use `localizedMessage` for user-visible localized text. example: Permission denied to access this resource status: $ref: '#/components/schemas/world_Code' details: $ref: '#/components/schemas/world_ErrorDetails' localizedMessage: $ref: '#/components/schemas/world_LocalizedMessage' help: $ref: '#/components/schemas/world_Help' description: API error response with status, details, and optional help. world_Code: type: string description: REST API status code per Google API design guidelines. example: PERMISSION_DENIED enum: - OK - CANCELLED - UNKNOWN - INVALID_ARGUMENT - DEADLINE_EXCEEDED - NOT_FOUND - ALREADY_EXISTS - PERMISSION_DENIED - UNAUTHENTICATED - RESOURCE_EXHAUSTED - FAILED_PRECONDITION - ABORTED - OUT_OF_RANGE - UNIMPLEMENTED - INTERNAL - UNAVAILABLE - DATA_LOSS - PARTIAL_ELEMENT_UPDATE_FAILED world_ErrorDetails: required: - reason type: object properties: reason: maxLength: 63 pattern: '[A-Z][A-Z0-9_]+[A-Z0-9]' type: string description: Error reason identifier in UPPER_SNAKE_CASE (max 63 characters). example: RESOURCE_NOT_FOUND message: type: string description: Human-readable explanation with error context. nullable: true example: The requested design with ID 12345 does not exist domain: type: string description: Error domain, usually the service that produced the error. nullable: true example: restapi.qunhe.com metaData: type: object additionalProperties: type: string description: Additional metadata as key/value pairs (keys up to 64 chars, pattern /[a-zA-Z0-9-_]/). nullable: true example: '{"instanceLimitPerRequest":"100","currentInstanceCount":"150"}' description: Additional metadata as key/value pairs (keys up to 64 chars, pattern /[a-zA-Z0-9-_]/). nullable: true example: instanceLimitPerRequest: '100' currentInstanceCount: '150' description: 'Error details: reason, domain, and metadata.' world_Help: required: - desc - url type: object properties: desc: type: string description: Description of the linked help document. example: How to resolve permission denied errors url: type: string description: URL of the help document example: https://docs.example.com/errors/permission-denied description: Help link and description for resolving the error. nullable: true world_LocalizedMessage: required: - locale - message type: object properties: locale: type: string description: Locale identifier for the message example: zh_CN message: type: string description: Localized error text for end users example: You do not have permission to access this resource description: Localized message for a specific locale. nullable: true world_WorldListQueryRequest: type: object properties: pageNum: minimum: 0 type: integer description: Page index (0-based). format: int32 example: 0 pageSize: maximum: 100 minimum: 0 type: integer description: Page size (max 100); defaults to 20 when 0 or omitted. format: int32 example: 20 statusList: type: array description: Filter by reconstruction status; empty means no status filter. items: $ref: '#/components/schemas/world_WorldOpenApiTaskStatus' description: >- List body: `pageNum` from 0, `pageSize` 1–100 (default 20 when 0 or omitted). Returns 3DGS worlds for the current account only. world_WorldOpenApiTaskStatus: type: string description: >- Task status. **In progress**: `PENDING` queued; `PREPROCESSING` preprocessing; `RUNNING` running. **Terminal**: `SUCCEEDED` succeeded; `FAILED` failed; `CANCELED` canceled; `TIMEOUT` timeout; `REJECTED` rejected. example: SUCCEEDED enum: - PENDING - PREPROCESSING - RUNNING - SUCCEEDED - FAILED - CANCELED - TIMEOUT - REJECTED world_SplatFileUrls: type: object properties: plyPath: type: string description: PLY URL (`output.plyPath`). example: https://cdn.example.com/output/world-001.ply spzPath: type: string description: SPZ URL (`output.spzPath`). example: https://cdn.example.com/output/world-001.spz lodMetaPath: type: string description: >- LOD chunk metadata download URL (`output.lodMetaPath`); present after successful LOD post-processing, else null. example: https://cdn.example.com/output/world-001-lod-meta.json description: '3DGS splat download URLs: PLY / SPZ and optional LOD metadata (same fields as task output).' world_WorldAssetBundle: type: object properties: splats: $ref: '#/components/schemas/world_WorldSplatBundle' imagery: $ref: '#/components/schemas/world_WorldImagery' semanticsMetadata: $ref: '#/components/schemas/world_WorldSemanticsMetadata' description: >- World output bundle. On 3D reconstruction success, `splats` is filled (ply/spz/lodMetaPath under `splats.urls`); AI generation additionally returns the panorama URL at `imagery.panoUrl`. world_WorldDetail: required: - worldId type: object properties: worldId: type: string description: World id; create APIs return the same value in `WorldAsyncOperation.worldId`. example: A1b2C3d4E5 name: type: string description: World name example: Living room reconstruction cover: type: string description: Cover image URL. example: https://cdn.example.com/cover/world-001.jpg scene: $ref: '#/components/schemas/world_WorldOpenApiProjectScene' createTime: type: integer description: Created at, Unix milliseconds. format: int64 example: 1699339916000 updateTime: type: integer description: Updated at, Unix milliseconds. format: int64 example: 1699340120000 status: $ref: '#/components/schemas/world_WorldOpenApiTaskStatus' progress: type: number description: Reconstruction progress in [0.0, 1.0]. format: float example: 0.65 assets: $ref: '#/components/schemas/world_WorldAssetBundle' description: >- World record: `worldId` is the business world id; `scene`/`status` are convention strings; `createTime` / `updateTime` are Unix milliseconds. When outputs are ready, details may include splat URLs; AI-generated worlds also return the panorama at `assets.imagery.panoUrl`. world_WorldImagery: type: object properties: panoUrl: type: string description: >- AI-generated panorama download URL. Present only when the pano subtask succeeds for AI-generated (Spatial Gen) worlds. example: https://cdn.example.com/output/world-001-pano.jpg description: Image outputs for AI-generated worlds; currently only the panorama download URL. world_WorldOpenApiUpAxis: type: string description: 'World coordinate up axis. `Y`: +Y up (glTF/USD default); `Z`: +Z up (3DGS output convention for this service).' example: Z enum: - 'Y' - Z world_WorldPagedList: type: object properties: pageNum: type: integer description: Page index used for this request (0-based). format: int32 example: 0 pageSize: type: integer description: Page size used for this request. format: int32 example: 20 count: type: integer description: Rows on this page. format: int32 example: 20 totalCount: type: integer description: Total matching rows. format: int32 example: 128 hasMore: type: boolean description: Whether another page exists. example: false result: type: array description: Rows for this page (WorldOpen mapping; list uses withResult=false by default). items: $ref: '#/components/schemas/world_WorldDetail' description: Paged list with `pageNum` / `pageSize`, current page rows, and totals. world_WorldSemanticsMetadata: type: object properties: upAxis: $ref: '#/components/schemas/world_WorldOpenApiUpAxis' description: >- Semantics metadata (camera pose, scale, offset, coordinate conventions, etc.). When splat outputs are returned, includes `upAxis` to indicate the coordinate system. world_WorldSplatBundle: type: object properties: urls: $ref: '#/components/schemas/world_SplatFileUrls' description: 3DGS splat output files. world_GenerateWorldRequest: type: object properties: name: type: string description: Project / world display name example: Living room generation cover: type: string description: Cover image URL (optional)。 example: https://cdn.example.com/cover/gen-cover.jpg resources: type: array description: >- Input resources; provide `prompt` and/or resources. Images only, at most one; omit `type` → image. image: .jpg / .jpeg / .png / .webp. items: $ref: '#/components/schemas/world_GenerateWorldResourceItem' prompt: type: string description: Text prompt; can combine with `resources`. example: Modern minimalist sunlit living room description: >- Body for world generation: text-only, one image, or both. Indoor scenes are more mature; non-indoor is Beta (see POST operation). Require non-empty `prompt` or at least one image resource (at most one); image: .jpg / .jpeg / .png / .webp. world_GenerateWorldResourceItem: required: - url type: object properties: url: minLength: 1 type: string description: 'Image resource URL; extension must be image: .jpg / .jpeg / .png / .webp.' example: https://cdn.example.com/input/room.jpg type: $ref: '#/components/schemas/world_WorldOpenApiGenResourceType' description: 'One generation input resource (image). Omit `type` → image. image: .jpg / .jpeg / .png / .webp.' world_WorldOpenApiGenResourceType: type: string description: Generation input resource type; image only, supports .jpg / .jpeg / .png / .webp. example: image enum: - image lux3d_HumanoidAutoRigRequest: type: object required: - modelUrl properties: modelUrl: type: string format: uri description: >- Public HTTPS URL of the GLB model. For a local file, upload it with the [Asset upload API](https://labs.aholo.ai/api-docs/en/api-reference#tag/asset), then pass the returned URL. lux3d_HumanoidAnimationRetargetRequest: type: object required: - rigModelUrl - animationIds properties: rigModelUrl: type: string format: uri description: >- Public HTTPS URL of the rigged GLB model. For a local file, upload it with the [Asset upload API](https://labs.aholo.ai/api-docs/en/api-reference#tag/asset), then pass the returned URL. example: https://qhstaticssl.kujiale.com/application/octetstream/1790240555913/rigModel.glb animationIds: type: array minItems: 1 maxItems: 10 uniqueItems: true items: type: string minLength: 1 enum: - A_TPose - Dance_Loop - Idle_Rail_Call - Idle_TalkingPhone_Loop - Idle_Talking_Loop - 'Yes' - Crouch_Idle_Loop - Idle_FoldArms_Loop - Idle_Lantern_Loop - Idle_Loop - Idle_No_Loop - Idle_Rail_Loop - Idle_Torch_Loop - ClimbUp_1m - Crouch_Fwd_Loop - Jog_Fwd_Loop - Sprint_Loop - Swim_Fwd_Loop - Swim_Idle_Loop - Walk_Formal_Loop - Walk_Loop - Jump_Land - Jump_Loop - Jump_Start - NinjaJump_Idle_Loop - NinjaJump_Land - NinjaJump_Start - Roll - Slide_Exit - Slide_Loop - Slide_Start - Sword_Attack - Sword_Block - Sword_Dash - Sword_Heavy_Combo - Sword_Idle - Sword_Regular_A - Sword_Regular_A_Rec - Sword_Regular_B - Sword_Regular_B_Rec - Sword_Regular_C - Sword_Regular_Combo - Idle_Shield_Break - Idle_Shield_Loop - Shield_Dash - Shield_OneShot - Melee_Hook - Melee_Hook_Rec - Punch_Cross - Punch_Jab - Pistol_Aim_Down - Pistol_Aim_Neutral - Pistol_Aim_Up - Pistol_Idle_Loop - Pistol_Reload - Pistol_Shoot - Spell_Simple_Enter - Spell_Simple_Exit - Spell_Simple_Idle_Loop - Spell_Simple_Shoot - Chest_Open - Consume - Driving_Loop - Farm_Harvest - Farm_PlantSeed - Farm_Watering - Fixing_Kneeling - Interact - OverhandThrow - PickUp_Table - Push_Loop - TreeChopping_Loop - Walk_Carry_Loop - LayToIdle - Sitting_Enter - Sitting_Exit - Sitting_Idle_Loop - Sitting_Talking_Loop - Death01 - Hit_Chest - Hit_Head - Hit_Knockback - Zombie_Idle_Loop - Zombie_Scratch - Zombie_Walk_Fwd_Loop description: Select 1–10 distinct, case-sensitive animation IDs from the 85 available values below. animationOutputMode: type: string enum: - separate - combined default: separate description: >- separate: each animation is delivered in its own file; combined: all animations are delivered as separate clips in one file. outFormat: type: string enum: - glb - fbx default: glb description: Output file format. animateInPlace: type: boolean default: false description: Whether to generate animation in place. lux3d_MultimodalToImageRequest: type: object properties: img: minLength: 1 pattern: .*\S.* type: string description: >- A single reference image URL, usable alone or together with prompt. Provide at least one of img and prompt; supplied values must not be blank. For a local file, upload it with the [Asset upload API](https://labs.aholo.ai/api-docs/en/api-reference#tag/asset), then pass the returned URL. example: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg prompt: minLength: 1 pattern: .*\S.* type: string description: >- Image-generation prompt, usable alone or together with img. Provide at least one of img and prompt; supplied values must not be blank. example: Change the chair to light natural wood while preserving its shape and viewpoint description: >- Multimodal single-image request. At least one of img and prompt is required; image-only, prompt-only, and combined inputs are supported. lux3d_ImageToFourViewRequest: type: object properties: img: minLength: 1 pattern: .*\S.* type: string description: >- A single image URL. Provide at least one of img and prompt; supplied values must not be blank. For a local file, upload it with the [Asset upload API](https://labs.aholo.ai/api-docs/en/api-reference#tag/asset), then pass the returned URL. example: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg prompt: minLength: 1 pattern: .*\S.* type: string description: >- Text prompt that can be used alone or together with img. Provide at least one of img and prompt; supplied values must not be blank. example: A modern light-wood dining chair on a pure white background description: >- Multimodal four-view request. At least one of img and prompt is required; image-only, prompt-only, and combined inputs are supported. lux3d_ImgTo3dRequest: type: object properties: img: minLength: 1 pattern: .*\S.* type: string description: >- A single image URL supported by both G1 and G1-Turbo. Provide exactly one of img and imgs; image URLs must not be blank. For a local file, upload it with the [Asset upload API](https://labs.aholo.ai/api-docs/en/api-reference#tag/asset), then pass the returned URL. example: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg imgs: type: array minItems: 1 maxItems: 32 items: type: string minLength: 1 pattern: .*\S.* description: >- 1-32 image URLs for G1 or G1-Turbo. Order is preserved, and the first image is the primary reference. Mutually exclusive with img. When using imgs, version must explicitly be G1 or G1-Turbo. For local files, upload each file with the [Asset upload API](https://labs.aholo.ai/api-docs/en/api-reference#tag/asset), then pass the returned URLs. example: - https://qhstaticssl.kujiale.com/image/png/1784775590866/multiview_input_1.png - https://qhstaticssl.kujiale.com/image/png/1784775591151/multiview_input_2.png version: type: string description: >- Generation version. Supported values are G1 and G1-Turbo. If omitted, the default version is used; specifying a version is recommended. enum: - G1 - G1-Turbo example: G1 faceCount: type: integer description: >- Target Mesh face count. Valid range: 10000-300000. Default: 300000. PLY output is not affected by this parameter. minimum: 10000 maximum: 300000 example: 300000 outputFormat: type: array uniqueItems: true items: type: string enum: - zip - glb - ply description: >- Requested formats. G1 always returns ZIP and GLB and adds PLY when requested. G1-Turbo returns the selected formats; an omitted or empty list returns ZIP. example: - zip - glb enablePbr: type: boolean description: >- For G1-Turbo requests containing Mesh output, true or omitted produces a PBR Mesh and false produces a white Mesh. This does not select output formats. It is ignored by G1 and PLY-only requests. default: true aiPredictSize: type: boolean description: Omitted or true enables AI size prediction and scaling, while false disables it. description: >- Image-to-3D request for G1 and G1-Turbo. Exactly one of img and imgs is required; use img for one image or imgs for multiple images. When using imgs, version must explicitly be G1 or G1-Turbo. lux3d_TextTo3dRequest: required: - prompt type: object properties: prompt: minLength: 1 pattern: .*\S.* type: string description: Text prompt example: Generate a high-quality 3D wooden chair model style: type: string description: Generation style. Defaults to photorealistic. enum: - photorealistic - cartoon - anime - hand_painted - cyberpunk - fantasy - glass default: photorealistic example: photorealistic img: type: string description: >- Optional reference image URL. For a local file, upload it with the [Asset upload API](https://labs.aholo.ai/api-docs/en/api-reference#tag/asset), then pass the returned URL. example: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg version: type: string description: >- Generation version. Supported values are G1 and G1-Turbo. If omitted, the default version is used; specifying a version is recommended. enum: - G1 - G1-Turbo example: G1 faceCount: type: integer description: >- Target Mesh face count. Valid range: 10000-300000. Default: 300000. PLY output is not affected by this parameter. minimum: 10000 maximum: 300000 example: 300000 outputFormat: type: array uniqueItems: true items: type: string enum: - zip - glb - ply description: >- Requested formats. G1 always returns ZIP and GLB and adds PLY when requested. G1-Turbo returns the selected formats; an omitted or empty list returns ZIP. example: - zip - glb enablePbr: type: boolean description: >- For G1-Turbo requests containing Mesh output, true or omitted produces a PBR Mesh and false produces a white Mesh. This does not select output formats. It is ignored by G1 and PLY-only requests. default: true aiPredictSize: type: boolean description: Omitted or true enables AI size prediction and scaling, while false disables it. description: Text-to-3D request for G1 and G1-Turbo with one optional img reference image. lux3d_MaterialTransferRequest: required: - img - meshUrl - version type: object properties: img: minLength: 1 pattern: .*\S.* type: string description: >- Material reference image URL. For a local file, upload it with the [Asset upload API](https://labs.aholo.ai/api-docs/en/api-reference#tag/asset), then pass the returned URL. example: https://qhstaticssl.kujiale.com/image/png/1784776951878/material_transfer_input.png meshUrl: minLength: 1 pattern: .*\S.* type: string description: >- Model GLB file URL. For a local file, upload it with the [Asset upload API](https://labs.aholo.ai/api-docs/en/api-reference#tag/asset), then pass the returned URL. example: https://qhstaticssl.kujiale.com/application/octetstream/1784776896628/material_transfer_model.glb version: type: string description: Required. Currently, this must be v3.0-standard. enum: - v3.0-standard example: v3.0-standard outputFormat: type: array uniqueItems: true items: type: string enum: - zip - glb - usdz - obj_zip - fbx_zip description: 'Requested formats: zip, glb, usdz, obj_zip, or fbx_zip.' example: - zip - glb aiPredictSize: type: boolean description: Whether to predict the model size. When true, customSize is ignored. customSize: type: number format: float minimum: 0 exclusiveMinimum: true description: >- Target height in millimeters when aiPredictSize is false or omitted. If omitted, the original size is preserved. description: Material transfer request. Currently, version must be v3.0-standard. lux3d_PartSplitRequest: required: - glbUrl type: object properties: glbUrl: minLength: 1 pattern: .*\S.* type: string description: >- Publicly accessible URL of the GLB model to split. For a local file, upload it with the [Asset upload API](https://labs.aholo.ai/api-docs/en/api-reference#tag/asset), then pass the returned URL. A Lux3D GLB task result may also be used while its URL remains valid. example: https://qhstaticssl.kujiale.com/model/gltfbinary/1790144390549/14B82261CD6DF53FA6B406240E20CB2C.glb description: Part-splitting task request body. lux3d_MultiFormatExportRequest: required: - modelUrl type: object properties: modelUrl: minLength: 1 type: string description: >- Public URL of a .zip or .glb model. ZIP input must be a Lux3D generation result; GLB input requires a non-empty outputFormat. For a local file, upload it with the [Asset upload API](https://labs.aholo.ai/api-docs/en/api-reference#tag/asset), then pass the returned URL. example: https://qhstaticssl.kujiale.com/application/octetstream/1784776896628/model.glb outputFormat: type: array uniqueItems: true items: type: string enum: - usdz - obj_zip - fbx_zip - stl - 3mf description: > Optional formats to export. Single values or combinations are supported: usdz, obj_zip, fbx_zip, stl, 3mf. outputFormat does not accept glb. - usdz: AR model format commonly used in the Apple ecosystem, suitable for iOS, iPadOS, and Quick Look AR previews. - obj_zip: Archive containing OBJ, MTL, and texture files, compatible with common 3D software and DCC tools. - fbx_zip: Archive containing an FBX model and texture assets, suitable for mainstream DCC workflows such as Maya, 3ds Max, and Blender. - stl: Mesh format for 3D printing and geometry exchange. It does not contain material or texture information. - 3mf: 3D Manufacturing Format for 3D printing workflows and manufacturing/printing delivery. For ZIP input, outputFormat may be omitted or empty; GLB input requires at least one value. example: - usdz - obj_zip - stl - 3mf description: Multi-format export task request body. lux3d_ArticulationAnimationRequest: type: object required: - glbUrl - prompt additionalProperties: false properties: glbUrl: type: string format: uri minLength: 1 description: >- Public HTTP(S) URL of the input GLB model, accessible to the service. For a local file, upload it with the [Asset upload API](https://labs.aholo.ai/api-docs/en/api-reference#tag/asset), then pass the returned URL. example: https://assets.aholo3d.com/examples/cubely/joint-motion/target-model.glb prompt: type: string minLength: 1 pattern: .*\S.* description: Describe the parts that should move and their intended joint motion. Must not be blank. example: Keep the base fixed and add a hinge joint so the lid opens and closes slowly. description: >- Model articulation and animation request. Both glbUrl and prompt are required; additional fields are not accepted. lux3d_TaskCreateResponse: type: object properties: f: type: object description: Failure information; null on success. nullable: true additionalProperties: true d: type: integer description: Returns taskid format: int64 example: 1256173 nullable: true m: type: string description: Message; an empty string "" on success. nullable: true c: type: string description: >- Status code; "0" on success, "-1" for ordinary parameter errors, and a dedicated code for some business errors. nullable: true description: Task creation response body. lux3d_TaskOutput: type: object properties: content: type: string description: >- Result content, which may be a file URL, a JSON string, or NOT_REQUESTED. See the task query API description for the content format and parsing rules for each task type. nullable: true example: https://cos.example.com/lux3d/xxx/result.zip description: Task output item. lux3d_TaskQueryData: type: object properties: taskId: type: integer description: Task ID format: int64 example: 1389513 outputs: type: array description: >- Task results. A running task may include results that have already been produced. See the task query API description for the result format and order for each task type. items: $ref: '#/components/schemas/lux3d_TaskOutput' status: type: integer description: 'Task status: 0-initialized, 1-running, 3-succeeded, 4-failed, 6-cancelled.' format: int32 enum: - 0 - 1 - 3 - 4 - 6 example: 3 description: Task query data. lux3d_TaskQueryResponse: type: object properties: f: type: object description: Failure information; null on success. nullable: true additionalProperties: true d: $ref: '#/components/schemas/lux3d_TaskQueryData' m: type: string description: Message; an empty string "" on success. nullable: true c: type: string description: Status code; "0" on success and "-1" for ordinary parameter errors. nullable: true description: Task query response body. lux3d_TaskListItem: type: object properties: taskId: type: integer format: int64 description: Task ID status: type: integer description: 'Task status: 0-initialized, 1-running, 3-succeeded, 4-failed, 6-cancelled.' enum: - 0 - 1 - 3 - 4 - 6 created: type: integer format: int64 description: Task creation time as a Unix timestamp in milliseconds lastModified: type: integer format: int64 description: Last modification time as a Unix timestamp in milliseconds lux3d_TaskListData: type: object properties: items: type: array items: $ref: '#/components/schemas/lux3d_TaskListItem' total: type: integer description: Total number of matching tasks page: type: integer description: Current page number pageSize: type: integer description: Items per page lux3d_TaskListResponse: type: object properties: f: type: object nullable: true additionalProperties: true description: Failure information; null on success. d: $ref: '#/components/schemas/lux3d_TaskListData' m: type: string nullable: true description: Message. Empty string "" on success. c: type: string nullable: true description: Status code. "0" on success; error code string on failure. description: > Generation-record list response body. The list, create, and query endpoints use the same successful response envelope: f is null, c is "0", and m is an empty string "". Check for c === "0" to determine success. rendercloud_OfflineRenderSubmitRequest: type: object description: Offline render submit request body. Do not pass `operationId` when submitting. additionalProperties: false required: - requestId - usdContent properties: requestId: type: string description: Caller-generated request tracing ID. The server does not use this field for offline render task idempotency. minLength: 1 usdContent: type: string description: Base64-encoded OpenUSD text or binary content. minLength: 1 rendercloud_OperationPollRequest: type: object description: Long-running operation polling request body. Use the returned `operationId` after a successful submit. additionalProperties: false required: - operationId properties: operationId: type: string description: Operation ID returned by submit. minLength: 1 rendercloud_OfflineRenderResponse: type: object description: Offline render result. Returned only when `Operation.done=true` and the job succeeded. additionalProperties: false properties: taskId: type: string description: Offline render task ID. resultUrl: type: string format: uri description: Rendered image URL. rendercloud_RealtimeSessionSubmitRequest: type: object description: Realtime render stream creation request body. Do not pass `operationId` when creating. additionalProperties: false required: - requestId - usdContent properties: requestId: type: string description: Caller-generated idempotency key. minLength: 1 usdContent: type: string description: Base64-encoded OpenUSD text or binary content. minLength: 1 settings: type: object description: Optional realtime-render session configuration. Server defaults apply when omitted. additionalProperties: false properties: autoEnhanceAI: type: boolean default: false description: Enable AI enhancement. Enabling it increases per-frame processing latency. rendercloud_RealtimeSessionQueryResponse: type: object description: Realtime render stream query result. When `status=ACTIVE`, it contains WebSocket connection parameters. additionalProperties: false properties: sessionId: type: string description: Realtime render stream session ID. status: $ref: '#/components/schemas/rendercloud_RenderCloudSessionStatus' currentQueuePosition: type: integer format: int32 description: Current queue position. `0` means the session is ready. host: type: string description: Realtime render stream host. nodeId: type: string description: Value of the `nid` query parameter in the WebSocket URL. streamId: type: string description: Value of `slaveInit.masterStreamingId` in the WebSocket handshake message. token: type: string description: Authentication token required to establish the realtime render stream. rendercloud_RealtimeSessionUpdateRequest: type: object description: Realtime render stream incremental update request body. additionalProperties: false required: - requestId - usdContent properties: requestId: type: string description: Caller-generated idempotency key. minLength: 1 usdContent: type: string description: Base64-encoded incremental OpenUSD content. minLength: 1 rendercloud_RealtimeSessionUpdateResponse: type: object description: Realtime render stream incremental update response body. additionalProperties: false properties: sessionId: type: string description: Realtime render stream session ID. status: $ref: '#/components/schemas/rendercloud_RenderCloudSessionStatus' rendercloud_RealtimeSessionCloseResponse: type: object description: Realtime render stream close response body. additionalProperties: false properties: sessionId: type: string description: Realtime render stream session ID. closed: type: boolean description: Whether the server found and closed the session. rendercloud_OfflineRenderProcessingOperation: type: object description: Offline render processing state. additionalProperties: false required: - operationId - metaData - done - result - error properties: operationId: $ref: '#/components/schemas/rendercloud_OperationId' metaData: $ref: '#/components/schemas/rendercloud_OperationMetaData' done: type: boolean enum: - false result: type: object nullable: true description: Null while processing. error: type: object nullable: true description: Null while processing. rendercloud_OfflineRenderSuccessOperation: type: object description: Offline render success state. additionalProperties: false required: - operationId - metaData - done - result - error properties: operationId: $ref: '#/components/schemas/rendercloud_OperationId' metaData: $ref: '#/components/schemas/rendercloud_OperationMetaData' done: type: boolean enum: - true result: $ref: '#/components/schemas/rendercloud_OfflineRenderResponse' error: type: object nullable: true description: Null on success. rendercloud_RealtimeSessionProcessingOperation: type: object description: Realtime render stream creation processing state. additionalProperties: false required: - operationId - metaData - done - result - error properties: operationId: $ref: '#/components/schemas/rendercloud_OperationId' metaData: $ref: '#/components/schemas/rendercloud_OperationMetaData' done: type: boolean enum: - false result: type: object nullable: true description: Null while processing. error: type: object nullable: true description: Null while processing. rendercloud_RealtimeSessionSuccessOperation: type: object description: Realtime render stream creation success state. additionalProperties: false required: - operationId - metaData - done - result - error properties: operationId: $ref: '#/components/schemas/rendercloud_OperationId' metaData: $ref: '#/components/schemas/rendercloud_OperationMetaData' done: type: boolean enum: - true result: $ref: '#/components/schemas/rendercloud_RealtimeSessionQueryResponse' error: type: object nullable: true description: Null on success. rendercloud_OperationError: type: object description: Long-running operation failure state. additionalProperties: false required: - operationId - metaData - done - result - error properties: operationId: $ref: '#/components/schemas/rendercloud_OperationId' metaData: $ref: '#/components/schemas/rendercloud_OperationMetaData' done: type: boolean enum: - true result: type: object nullable: true description: Null on failure. error: $ref: '#/components/schemas/rendercloud_ApiError' rendercloud_OperationId: type: string description: Long-running operation ID. rendercloud_OperationMetaData: type: object nullable: true description: Long-running operation metadata. This API usually returns null. additionalProperties: true rendercloud_Int2: type: object description: Two-dimensional integer vector. Used for output resolution, where `x` is width and `y` is height. additionalProperties: false required: - x - 'y' properties: x: type: integer format: int32 minimum: 1 description: Image width in pixels. 'y': type: integer format: int32 minimum: 1 description: Image height in pixels. rendercloud_RenderCloudSessionStatus: type: string description: | Realtime render stream session status. - `INITIALIZING`: The session has been created and the backend is establishing the streaming connection. - `ACTIVE`: The streaming connection is ready and can render normally. - `FAILED`: Initialization or operation failed. - `CLOSED`: The session has been closed. enum: - RENDER_CLOUD_SESSION_STATUS_UNSPECIFIED - INITIALIZING - ACTIVE - FAILED - CLOSED rendercloud_ApiError: type: object description: >- Standard OpenAPI gateway error response. For async operation failures, this object is returned in `Operation.error`. additionalProperties: true required: - code - message - status properties: code: type: integer format: int32 description: HTTP semantic error code. example: 500 message: type: string description: Human-readable error message. It may include error details forwarded by the gateway. example: 'code: INTERNAL, details: ErrorDetails(reason=INTERNAL_ERROR, message=null, domain=render, metaData=null)' status: type: string description: Standard error status. enum: - INVALID_ARGUMENT - NOT_FOUND - RESOURCE_EXHAUSTED - INTERNAL example: INTERNAL details: $ref: '#/components/schemas/rendercloud_ErrorDetails' rendercloud_ErrorDetails: type: object description: Extended error details forwarded by the gateway. additionalProperties: true properties: reason: type: string description: Error reason. example: INTERNAL_ERROR domain: type: string description: Error domain. Examples use a generic value and do not expose internal service domains. example: render rendercloud_MeshUploadProcessRequest: type: object description: Mesh upload and parsing task request body. additionalProperties: false properties: originMeshUrl: type: string format: uri description: >- URL of the original Mesh file. Cloud-hosted URLs must be publicly accessible. If the file is stored only locally, upload it first through the [Asset Upload](https://labs.aholo.ai/api-docs/en/api-reference#tag/asset) endpoint to obtain a URL, then populate this field with that URL. example: https://example.com/mesh/original.glb fastUpload: type: boolean description: >- Whether to enable fast upload. Optional; defaults to false. When fastUpload is true and the file is in GLB format, the fast upload workflow is used. If omitted or false, the standard upload workflow is used. default: false example: false rendercloud_TaskCreateResponse: type: object description: Task creation response using the standard Result format. additionalProperties: false properties: success: type: boolean description: Whether the request succeeded. example: true data: type: integer format: int64 description: Created task ID. example: 1305220918472257500 errorMsg: type: string nullable: true description: Error message. Null when the request succeeds. example: null rendercloud_TaskQueryResponse: type: object description: Task query response using the standard Result format. additionalProperties: false properties: success: type: boolean description: Whether the request succeeded. example: true data: $ref: '#/components/schemas/rendercloud_AiGenerateBusInstanceOpenDto' errorMsg: type: string nullable: true description: Error message. Null when the request succeeds. example: null rendercloud_CommonErrorResponse: type: object description: Common error response body. additionalProperties: false properties: success: type: boolean description: Whether the request succeeded. example: false data: type: object nullable: true description: Data payload. Null when an error occurs. example: null errorMsg: type: string description: Error message. example: Invalid arguments rendercloud_AiGenerateBusInstanceOpenDto: type: object description: RenderCloud task details. additionalProperties: false properties: taskId: type: integer format: int64 description: Task ID. example: 1272794 userId: type: integer format: int64 description: User ID. example: 12345 status: type: integer format: int32 description: | Task status: - `0`: INIT - `1`: RUNNING - `3`: SUCCESS - `4`: FAIL example: 3 outputs: type: array nullable: true description: Task output asset list. Null while the task is processing. items: $ref: '#/components/schemas/rendercloud_AiGraphicAssetDto' example: - content: YYZN2MZVAIQLEPTULM888888 sourceReferId: '607583273' rendercloud_AiGraphicAssetDto: type: object description: AI asset object. additionalProperties: false properties: sourceReferId: type: string description: Source asset reference ID, such as a product ID. example: '607583273' content: type: string description: | Asset content: - For Mesh upload task input: original Mesh URL - For Mesh upload task output: parsed meshId example: YYZN2MZVAIQLEPTULM888888 spatialunderstanding_CreateSpatialUnderstandingTaskRequest: required: - inputFileUrl type: object properties: inputFileUrl: minLength: 1 type: string description: >- Point-cloud URL. Only `.ply` is supported, for indoor scenes. The cloud should use a right-handed coordinate system in meters and be spatially aligned ([ScanNet Alignment](https://github.com/ScanNet/ScanNet/tree/master/Alignment)): Z up, floor parallel to the X-Y plane, and major walls preferably aligned with the X or Y axis in the horizontal plane. If the input cloud does not meet this, pass `transformationMatrix`. For a local file, upload it with the [Asset upload API](https://labs.aholo.ai/api-docs/en/api-reference#tag/asset), then put the returned URL here. External URLs are not supported. example: https://holo-cos.aholo3d.cn/resource/openapi/xxx.ply transformationMatrix: type: array description: >- Optional. A 4×4 homogeneous transform (4 rows × 4 columns of numbers) that maps the input cloud into the aligned coordinate system above: Z up, floor parallel to the X-Y plane, and major walls preferably aligned with the X or Y axis in the horizontal plane. Omit it if the input is already aligned. Convention: column-vector multiply `p' = T p`; translation in the 4th column of this array (do not transpose); right-handed; Z-up ([ScanNet Alignment](https://github.com/ScanNet/ScanNet/tree/master/Alignment)); units in meters. Block form: upper-left `R` is 3×3 rotation, right `t` is translation, bottom row is `[0, 0, 0, 1]`. ``` T = [ R(3×3) t(3×1) ] [ 0(1×3) 1 ] ``` Request-body indices: ``` [ [ r00, r01, r02, tx ], [ r10, r11, r12, ty ], [ r20, r21, r22, tz ], [ 0, 0, 0, 1 ] ] ``` example: - - 0.9337461173020494 - 0.3579360116324523 - 0 - 1.871216953359744 - - -0.3579360116324523 - 0.9337461173020494 - 0 - -0.2091883674268249 - - 0 - 0 - 0.9999999999999999 - 1.2121098756790158 - - 0 - 0 - 0 - 1 items: type: array description: >- Optional. A 4×4 homogeneous transform (4 rows × 4 columns of numbers) that maps the input cloud into the aligned coordinate system above: Z up, floor parallel to the X-Y plane, and major walls preferably aligned with the X or Y axis in the horizontal plane. Omit it if the input is already aligned. Convention: column-vector multiply `p' = T p`; translation in the 4th column of this array (do not transpose); right-handed; Z-up ([ScanNet Alignment](https://github.com/ScanNet/ScanNet/tree/master/Alignment)); units in meters. Block form: upper-left `R` is 3×3 rotation, right `t` is translation, bottom row is `[0, 0, 0, 1]`. ``` T = [ R(3×3) t(3×1) ] [ 0(1×3) 1 ] ``` Request-body indices: ``` [ [ r00, r01, r02, tx ], [ r10, r11, r12, ty ], [ r20, r21, r22, tz ], [ 0, 0, 0, 1 ] ] ``` example: - - 0.9337461173020494 - 0.3579360116324523 - 0 - 1.871216953359744 - - -0.3579360116324523 - 0.9337461173020494 - 0 - -0.2091883674268249 - - 0 - 0 - 0.9999999999999999 - 1.2121098756790158 - - 0 - 0 - 0 - 1 items: type: number description: >- Optional. A 4×4 homogeneous transform (4 rows × 4 columns of numbers) that maps the input cloud into the aligned coordinate system above: Z up, floor parallel to the X-Y plane, and major walls preferably aligned with the X or Y axis in the horizontal plane. Omit it if the input is already aligned. Convention: column-vector multiply `p' = T p`; translation in the 4th column of this array (do not transpose); right-handed; Z-up ([ScanNet Alignment](https://github.com/ScanNet/ScanNet/tree/master/Alignment)); units in meters. Block form: upper-left `R` is 3×3 rotation, right `t` is translation, bottom row is `[0, 0, 0, 1]`. ``` T = [ R(3×3) t(3×1) ] [ 0(1×3) 1 ] ``` Request-body indices: ``` [ [ r00, r01, r02, tx ], [ r10, r11, r12, ty ], [ r20, r21, r22, tz ], [ 0, 0, 0, 1 ] ] ``` format: double description: >- Body for creating a spatial understanding task. Indoor point clouds; coordinate system is meters, right-handed, Z-up. spatialunderstanding_SpatialUnderstandingTaskAsyncOperation: required: - taskId type: object properties: taskId: type: string description: Task id. Pass it to `GET /global/spatial-understanding/v1/tasks/{taskId}` topoll status and results. example: A1b2C3d4E5 description: Create acceptance result with `taskId`. Use it to poll details until the task finishes. spatialunderstanding_ApiError: required: - code - details - message - status type: object properties: code: type: integer description: HTTP status code format: int32 example: 403 message: type: string description: Developer-facing error message (English); use `localizedMessage` for user-visible localized text. example: Permission denied to access this resource status: $ref: '#/components/schemas/spatialunderstanding_Code' details: $ref: '#/components/schemas/spatialunderstanding_ErrorDetails' localizedMessage: $ref: '#/components/schemas/spatialunderstanding_LocalizedMessage' help: $ref: '#/components/schemas/spatialunderstanding_Help' description: API error response with status, details, and optional help. spatialunderstanding_Code: type: string description: Standard REST status code following Google API design, used as a unified error-code representation. example: PERMISSION_DENIED enum: - OK - CANCELLED - UNKNOWN - INVALID_ARGUMENT - DEADLINE_EXCEEDED - NOT_FOUND - ALREADY_EXISTS - PERMISSION_DENIED - UNAUTHENTICATED - RESOURCE_EXHAUSTED - FAILED_PRECONDITION - ABORTED - OUT_OF_RANGE - UNIMPLEMENTED - INTERNAL - UNAVAILABLE - DATA_LOSS - PARTIAL_ELEMENT_UPDATE_FAILED spatialunderstanding_ErrorDetails: required: - reason type: object properties: reason: maxLength: 63 pattern: '[A-Z][A-Z0-9_]+[A-Z0-9]' type: string description: Error reason identifier in UPPER_SNAKE_CASE, at most 63 characters example: RESOURCE_NOT_FOUND message: type: string description: Human-readable explanation of this error, with specific context nullable: true example: The requested design with ID 12345 does not exist domain: type: string description: Error domain, usually the service that produced the error nullable: true example: restapi.qunhe.com metaData: type: object additionalProperties: type: string description: Additional error metadata as key-value pairs; keys at most 64 characters, matching /[a-zA-Z0-9-_]/ nullable: true example: '{"instanceLimitPerRequest":"100","currentInstanceCount":"150"}' description: Additional error metadata as key-value pairs; keys at most 64 characters, matching /[a-zA-Z0-9-_]/ nullable: true example: instanceLimitPerRequest: '100' currentInstanceCount: '150' description: Error details with reason, domain, and metadata spatialunderstanding_Help: required: - desc - url type: object properties: desc: type: string description: Description of the linked content and how it helps example: How to resolve a permission-denied error url: type: string description: Help-document URL example: https://docs.example.com/errors/permission-denied description: Help information with a documentation link nullable: true spatialunderstanding_LocalizedMessage: required: - locale - message type: object properties: locale: type: string description: Locale identifier for the message example: en_US message: type: string description: Localized error text for end users example: You do not have permission to access this resource description: Localized message for a specific locale nullable: true spatialunderstanding_SpatialUnderstandingTaskListQueryRequest: type: object properties: pageNum: minimum: 0 type: integer description: Page number, starting at 1; `0` and `1` both mean the first page. format: int32 example: 1 pageSize: maximum: 100 minimum: 0 type: integer description: Page size, maximum 100; `0` or omitted defaults to 20. format: int32 example: 20 statusList: type: array description: Filter by task status (uppercase strings); empty means no status filter. items: $ref: '#/components/schemas/spatialunderstanding_SpatialUnderstandingTaskStatus' description: >- Body for listing spatial understanding tasks. `pageNum` starts at 1 (`0` and `1` both mean the first page); `pageSize` is 1–100 (omitted or `0` defaults to 20). Only tasks owned by the current account are returned. spatialunderstanding_SpatialUnderstandingTaskStatus: type: string description: >- Spatial understanding task status. **In progress**: `PENDING` queued; `RUNNING` running. **Terminal**: `SUCCEEDED` succeeded; `FAILED` failed; `TIMEOUT` timed out. example: SUCCEEDED enum: - PENDING - RUNNING - SUCCEEDED - FAILED - TIMEOUT spatialunderstanding_SpatialUnderstandingTask: type: object properties: taskId: type: string description: Task id, same as the create response. example: A1b2C3d4E5 status: $ref: '#/components/schemas/spatialunderstanding_SpatialUnderstandingTaskStatus' modelVersion: type: string description: >- Model version actually used for this task. Not specified at create time; the server uses the current default. example: spatiallm-pointcloud-1.2-20260910 result: $ref: '#/components/schemas/spatialunderstanding_SpatialUnderstandingTaskResult' errorCode: type: string description: >- Failure category; returned only for `FAILED` or `TIMEOUT`. `MODEL_SUBMIT_FAILED`: submit failed; `MODEL_TASK_FAILED`: execution failed; `RESULT_TRANSFER_FAILED`: result write failed; `TIMEOUT`: timed out. example: MODEL_TASK_FAILED errorMessage: type: string description: Failure details; returned only for `FAILED` or `TIMEOUT`. example: task failed createTime: type: integer description: Create time, Unix milliseconds. format: int64 updateTime: type: integer description: Last update time, Unix milliseconds. format: int64 description: >- Spatial understanding task details. On success includes `result`; on failure or timeout includes `errorCode` and `errorMessage`. spatialunderstanding_SpatialUnderstandingTaskPagedList: type: object properties: pageNum: type: integer description: Page number used for this request (starts at 1; if the request sent `0`, `0` is echoed back). format: int32 example: 1 pageSize: type: integer description: Page size used for this request. format: int32 example: 20 count: type: integer description: Number of records on the current page. format: int32 example: 20 totalCount: type: integer description: Total records matching the filter. format: int32 example: 128 hasMore: type: boolean description: Whether another page exists. example: false result: type: array description: Task records on the current page. items: $ref: '#/components/schemas/spatialunderstanding_SpatialUnderstandingTask' description: >- Paged spatial understanding task list, including `pageNum` / `pageSize` for this request, plus the current page and totals. spatialunderstanding_SpatialUnderstandingTaskResult: type: object properties: resultSslUrl: type: string description: >- URL of the spatial understanding result file. UTF-8 plain text, one entity per line. The server does not return parsed JSON — download and parse it yourself. Coordinate system: meters, right-handed, Z-up ([ScanNet Alignment](https://github.com/ScanNet/ScanNet/tree/master/Alignment)). Line format: `{id}={Type}(arg1,arg2,...)`. Skip unknown `Type` values; do not fail the whole file. | Type | Line format | | --- | --- | | Wall | `wall_{n}=Wall(ax,ay,az,bx,by,bz,height,thickness)` | | Door | `door_{n}=Door(wall_id,position_x,position_y,position_z,width,height)` | | Window | `window_{n}=Window(wall_id,position_x,position_y,position_z,width,height)` | | Bbox | `bbox_{n}=Bbox(class,position_x,position_y,position_z,angle_z,scale_x,scale_y,scale_z)` | | Type | Field | Data type | Description | | --- | --- | --- | --- | | Wall | `ax, ay, az` | number | 3D coordinates of start point A of the wall baseline on the floor. | | Wall | `bx, by, bz` | number | 3D coordinates of end point B of the wall baseline on the floor. | | Wall | `height` | number | Wall height. | | Wall | `thickness` | number | Wall thickness; currently `0.0` because the detector outputs inner-room contour edges. | | Door | `wall_id` | string | Id of the wall that owns the door, e.g. `wall_0`; must refer to a wall in this file. | | Door | `position_x, position_y, position_z` | number | 3D coordinates of the door-opening center. | | Door | `width` | number | Opening width along the owning wall. | | Door | `height` | number | Vertical height of the opening. | | Window | `wall_id` | string | Id of the wall that owns the window, e.g. `wall_4`; must refer to a wall in this file. | | Window | `position_x, position_y, position_z` | number | 3D coordinates of the window-opening center. | | Window | `width` | number | Opening width along the owning wall. | | Window | `height` | number | Vertical height of the opening. | | Bbox | `class` | string | Object class, e.g. `chair`, `sofa`, `carpet`, `coffee_table`. | | Bbox | `position_x, position_y, position_z` | number | Center of the 3D bounding box. | | Bbox | `angle_z` | number | Box rotation around Z, i.e. heading in the horizontal plane. | | Bbox | `scale_x` | number | Full extent along the box local X axis (not half-size). | | Bbox | `scale_y` | number | Full extent along the box local Y axis (not half-size). | | Bbox | `scale_z` | number | Full extent along the box local Z axis (height). | Parsing tips: read line by line. `class` may contain spaces (e.g. `dining chair`); do not split on the first comma. Take the last 7 numbers from the right and treat the remainder as `class`. `class` is usually unquoted. Numbers are floats. Format sample: ``` wall_0=Wall(1.6857,-4.4625,0.0,4.6798,-4.4474,0.0,2.73,0.0) door_0=Door(wall_0,3.1734,-4.4550,1.05,1.3852,2.1) window_0=Window(wall_4,5.6622,-1.0338,1.65,0.6883,1.5) bbox_0=Bbox(carpet,-3.009,4.371,-1.401,-1.5708,5.718,6.734,0.109) ``` **Common `class` values** (use the token as-is; treat unknown values as a generic object): `curtain`, `painting`, `nightstand`, `chandelier`, `wardrobe`, `bed`, `carpet`, `sofa`, `dining chair`, `bathroom cabinet`, `television`, `toilet`, `dining table combination`, `chair`, `shower`, `plants`, `tv cabinet`, `coffee table`, `illumination`, `shoe cabinet`, `refrigerator`, `shower room`, `wall decoration`, `cupboard`, `side table`, `stool`, `wine cabinet`, `bookcase`, `combination sofa`, `air conditioner`, `washing cabinet`, `pillow`, `stove`, `dressing table`, `desk`, `cushion`, `floor-standing lamp`, `dining table`, `washing machine`, `hand sink`, `clothes rack`, `mirror`, `sideboard`, `computer`, `potted bonsai`, `range hood`, `entrance cabinet`, `gas stove`, `multifunctional combination bed`, `leisure table and chair combination`, `bar chair`, `screen`, `sink`, `bar`, `tub`, `decorative cabinet`, `wall cabinet`, `integrated stove`, `micro-wave oven` example: https://holo-cos.aholo3d.cn/resource/openapi/xxx-result.txt description: >- Spatial understanding task output. Returned only when the task succeeds. `resultSslUrl` points to UTF-8 text (DSL) with Wall / Door / Window / Bbox; download and parse it yourself. parameters: rendercloud_SessionId: name: sessionId in: path required: true description: Realtime rendering stream session ID. schema: type: string responses: rendercloud_BadRequest: description: Invalid request arguments. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_ApiError' examples: invalidArgument: summary: Invalid argument description: The request body is missing required fields or contains invalid field values. value: code: 400 message: requestId cannot be empty status: INVALID_ARGUMENT details: reason: INVALID_ARGUMENT domain: render usdContentEmpty: summary: OpenUSD content is empty description: '`usdContent` is empty when submitting a render or creating a realtime stream.' value: code: 400 message: OpenUSD content cannot be empty status: INVALID_ARGUMENT details: reason: USD_CONTENT_EMPTY domain: render openUsdParseError: summary: OpenUSD parse failed description: '`usdContent` is not valid Base64 or the decoded OpenUSD content cannot be parsed.' value: code: 400 message: OpenUSD content parse failed status: INVALID_ARGUMENT details: reason: OPENUSD_PARSE_ERROR domain: render rendercloud_NotFound: description: Resource not found. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_ApiError' examples: taskNotFound: summary: Task not found description: No offline render task exists for the `operationId` when polling. value: code: 404 message: Task not found status: NOT_FOUND details: reason: TASK_NOT_FOUND domain: render sessionNotFound: summary: Session not found description: The realtime render session does not exist, has been closed, or has been cleaned up. value: code: 404 message: Session not found status: NOT_FOUND details: reason: SESSION_NOT_FOUND domain: render rendercloud_Conflict: description: Duplicate request. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_OperationError' examples: duplicateRequest: summary: Duplicate requestId description: The same user submitted the same `requestId` again within 1 minute. value: operationId: null metaData: null done: true result: null error: code: 409 message: requestId has already been submitted within 60 seconds status: ALREADY_EXISTS details: reason: OFFLINE_RENDER_DUPLICATE_REQUEST domain: render rendercloud_TooManyRequests: description: The request was rate limited. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_ApiError' examples: rateLimited: summary: Rate limited description: The user-level request frequency exceeds the current API limit. value: code: 429 message: Rate limited status: RESOURCE_EXHAUSTED details: reason: RATE_LIMITED domain: render rendercloud_InternalServerError: description: Internal render service error. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_ApiError' examples: renderInternalError: summary: Render failed description: Task creation, OpenUSD conversion, render dispatch, or realtime session update failed. value: code: 500 message: Render failed status: INTERNAL details: reason: INTERNAL_ERROR domain: render requestBodies: {} securitySchemes: AuthorizationHeader: type: apiKey description: >- Open platform credential. API key auth: set header `Authorization` to your platform **API key** (no `Bearer` prefix). name: Authorization in: header OusTokenV2: type: apiKey description: >- `ousToken` from **Get OUS upload token**; use only on OUS `globalDomain`; independent of gateway `Authorization`. name: ous-token-v2 in: header x-tagGroups: - name: Asset tags: - Asset - name: World tags: - World - SpatialUnderstanding - name: Lux3D tags: - Lux3D - name: Render Cloud tags: - RenderCloudOpenUSDGuide - RenderCloud