{
"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": "\n com.manycoreapis\n aholo-sdk-world\n 1.3.0\n"
},
{
"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`.\n\n`usdContent` must be transmitted as:\n\n```text\nusdContent = Base64(UTF-8(USDA text))\n```\n\nFiles 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.\n\n## Use Cases\n\n| Scenario | API | `usdContent` | Description |\n|----------|-----|--------------|-------------|\n| Offline render submit | `POST /global/rendercloud/v1/jobs` | Full USDA scene | Parses camera, Mesh, 3DGS, and RenderSettings, then starts offline rendering |\n| Realtime render creation | `POST /global/rendercloud/v1/streams` | Full USDA scene | Parses the full scene and creates a realtime rendering stream |\n| Realtime render patch | `POST /global/rendercloud/v1/streams/{sessionId}:push` | Patch USDA using `over` | Separately updates cameras, models, lights, and environment light |\n\n## Recommended Top-Level Structure\n\n```usda\n#usda 1.0\n(\n defaultPrim = \"World\"\n)\n\ndef Xform \"World\"\n{\n def Xform \"MeshModel1\" { ... }\n def Xform \"Cameras\"\n {\n def Camera \"MainCamera\" { ... }\n }\n def Xform \"Lights\"\n {\n def RectLight \"KeyRect\" { ... }\n def SphereLight \"FillPoint\" { ... }\n }\n}\n\ndef Scope \"Render\"\n{\n def RenderSettings \"MainRenderSettings\"\n {\n custom float3 manycore:environment:giIntensity = (1, 1, 1)\n }\n}\n```\n\nUse `def` for full scenes. Use `over` for realtime patch updates.\n\n## Stage Metadata\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `defaultPrim` | `token` string | No | Default root Prim name, for example `\"World\"` |\n| `doc` | Triple-quoted string | No | Documentation text; retained after parsing and not used for rendering |\n| `upAxis` | `token` string | No | Optional documentation metadata; does not change the cloud-renderer axis |\n| `metersPerUnit` | Floating-point number | No | Optional documentation metadata; does not change the cloud-renderer unit |\n\nCloud 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.\n\n## Xform\n\n`def Xform` wraps models or cameras and applies transform matrices to child Prims.\n\n| Attribute | USDA Type | Required | Description |\n|-----------|-----------|----------|-------------|\n| `matrix4d xformOp:transform` | `matrix4d` | No | 4x4 transform matrix |\n| `uniform token[] xformOpOrder` | `token[]` | No | Recommended value: `[\"xformOp:transform\"]` |\n\nThe matrix follows the USD row-vector convention. Translation is stored in the fourth row:\n\n```usda\nmatrix4d xformOp:transform = (\n (m00, m01, m02, m03),\n (m10, m11, m12, m13),\n (m20, m21, m22, m23),\n (m30, m31, m32, m33)\n)\n```\n\n## External Assets\n\nMesh:\n\n```usda\ndef Mesh \"myMesh\" (\n payload = @manycore:/mesh/{meshId}@\n)\n{\n}\n```\n\n3D Gaussian Splatting:\n\n```usda\ndef ParticleField3DGaussianSplat \"MyGaussianSplat\" (\n payload = @manycore:/mesh/{meshId}@\n)\n{\n}\n```\n\nThe `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.\n\n## Camera\n\nFull 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.\n\n| Attribute | USDA Type | Required | Description |\n|-----------|-----------|----------|-------------|\n| `token projection` | `token` | No | Projection type, for example `\"perspective\"` |\n| `float2 clippingRange` | `(near, far)` | No | Near and far clipping planes |\n| `float focalLength` | `float` | No | Focal length in mm |\n| `float focusDistance` | `float` | No | Focus distance |\n| `float fStop` | `float` | No | Aperture f-number |\n| `float horizontalAperture` | `float` | No | Horizontal aperture in mm |\n| `float verticalAperture` | `float` | No | Vertical aperture in mm |\n| `matrix4d xformOp:transform` | `matrix4d` | No | Camera pose |\n| `uniform token[] xformOpOrder` | `token[]` | No | Recommended value: `[\"xformOp:transform\"]` |\n\nExample:\n\n```usda\ndef Camera \"MainCamera\"\n{\n float2 clippingRange = (0.1, 1000)\n float focalLength = 28\n float fStop = 0\n float horizontalAperture = 24.447495\n float verticalAperture = 13.7517\n token projection = \"perspective\"\n matrix4d xformOp:transform = (\n (1, 0, 0, 0),\n (0, 1, 0, 0),\n (0, 0, 1, 0),\n (0, 0, 8.0, 1)\n )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n}\n```\n\n## RenderSettings\n\n`def RenderSettings` should be placed under `def Scope \"Render\"`.\n\n| Attribute | USDA Type | Required | Description |\n|-----------|-----------|----------|-------------|\n| `rel camera` | Prim path | No | Active camera path, for example `` |\n| `int2 resolution` | `(width, height)` | Required for offline rendering | Output resolution |\n\nOffline 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.\n\n## Lights and Environment Light\n\nLights 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))`.\n\n### Lights\n\nThe 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.\n\n| Prim / Attribute | Constraint |\n|------------------|------------|\n| `RectLight` | `inputs:width` and `inputs:height` must be positive; supports `inputs:color`, `inputs:intensity`, `inputs:exposure`, `inputs:specular`, and `xformOp:transform` |\n| `SphereLight` | `inputs:radius` must be positive; supports `inputs:color`, `inputs:intensity`, `inputs:exposure`, `inputs:specular`, and `xformOp:transform` |\n| `inputs:color` | Linear RGB; white when omitted |\n| `inputs:intensity` / `inputs:exposure` | Effective intensity is `intensity × 2^exposure` |\n| `inputs:normalize` | May be omitted or set to `false`; setting it to `true` is not supported |\n| `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 |\n| `manycore:affectReflections` | `0` or `1` in `customData`; defaults to `1` |\n| `manycore:doubleFace` | Boolean in `customData` for `RectLight`; defaults to `false` |\n\n`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.\n\n### Environment light\n\nWrite environment-light intensity on the active `RenderSettings` Prim, preferably alongside the camera and resolution:\n\n```usda\ncustom float3 manycore:environment:giIntensity = (1.25, 1.25, 1.25)\n```\n\n`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.\n\n### Patch rules\n\nSend 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.\n\n## Minimal Realtime Initialization Example\n\nThe 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.\n\n```usda\n#usda 1.0\n(\n defaultPrim = \"World\"\n)\n\ndef Xform \"World\"\n{\n def Xform \"Model\"\n {\n matrix4d xformOp:transform = (\n (1, 0, 0, 0),\n (0, 1, 0, 0),\n (0, 0, 1, 0),\n (0, 0, 0, 1)\n )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/{meshId}@\n ) {}\n }\n\n def Xform \"Cameras\"\n {\n def Camera \"MainCamera\"\n {\n float2 clippingRange = (0.1, 5000)\n float focalLength = 28\n float horizontalAperture = 24.447495\n float verticalAperture = 13.7517\n token projection = \"perspective\"\n matrix4d xformOp:transform = (\n (1, 0, 0, 0),\n (0, 1, 0, 0),\n (0, 0, 1, 0),\n (0, 0, 8, 1)\n )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n }\n }\n\n def Xform \"Lights\"\n {\n def RectLight \"KeyRect\"\n {\n color3f inputs:color = (1, 1, 1)\n float inputs:intensity = 4\n float inputs:width = 1200\n float inputs:height = 600\n float inputs:specular = 1\n bool inputs:normalize = false\n matrix4d xformOp:transform = (\n (1, 0, 0, 0),\n (0, 1, 0, 0),\n (0, 0, 1, 0),\n (1200, 600, 2400, 1)\n )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n }\n }\n}\n\ndef Scope \"Render\"\n{\n def RenderSettings \"MainRenderSettings\"\n {\n rel camera = \n int2 resolution = (1024, 576)\n custom float3 manycore:environment:giIntensity = (1, 1, 1)\n }\n}\n```\n\n## Realtime Rendering Initialization Example\n\nThe 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.\n\n```usda\n#usda 1.0\n(\n defaultPrim = \"World\"\n)\n\ndef Xform \"World\"\n{\n def Xform \"MainSplat\" {\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def ParticleField3DGaussianSplat \"SplatModel\" (\n payload = @manycore:/mesh/YYKIL7BVAJQPYPTUKU888888@\n )\n {\n }\n }\n\n def Xform \"Model_0_JVAIX5WPTUL4\" {\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/YYWWKOJVAIX5WPTUL4888888@\n )\n {\n }\n }\n\n def Xform \"Model_1_ZVAIPWOPTULY\" {\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/YRNLYLZVAIPWOPTULY888888@\n )\n {\n }\n }\n\n def Xform \"Model_2_ZVAXAG6PTUJU\" {\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/ZSGMVMZVAXAG6PTUJU888888@\n )\n {\n }\n }\n\n def Xform \"Model_3_BVAII3SPTUJU\" {\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/YR3NPCBVAII3SPTUJU888888@\n )\n {\n }\n }\n\n def Xform \"Model_4_RVALFX2PTUJQ\" {\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/YWMNBJRVALFX2PTUJQ888888@\n )\n {\n }\n }\n\n def Xform \"Model_5_RVAIIECPTULA\" {\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/ZC42U2RVAIIECPTULA888888@\n )\n {\n }\n }\n\n def Xform \"Model_6_BVAJRHAPTUKQ\" {\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/ZDAFHEBVAJRHAPTUKQ888888@\n )\n {\n }\n }\n\n def Xform \"Model_7_JVAUMCKPTULM\" {\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/ZS4RG7JVAUMCKPTULM888888@\n )\n {\n }\n }\n\n def Xform \"Model_8_ZVAX3LMPTUJU\" {\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/ZSBUJIZVAX3LMPTUJU888888@\n )\n {\n }\n }\n\n def Xform \"Model_9_ZVAJYACPTULU\" {\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/ZCCN76ZVAJYACPTULU888888@\n )\n {\n }\n }\n\n def Xform \"Model_10_JVAIHW6PTULA\" {\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/ZG55YXJVAIHW6PTULA888888@\n )\n {\n }\n }\n\n def Xform \"Model_11_UTDD52GSRTL4\" {\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/6DM4O3UTDD52GSRTL4888888@\n )\n {\n }\n }\n\n def Xform \"Model_12_JVAITAAPTULE\" {\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/Z65NBFJVAITAAPTULE888888@\n )\n {\n }\n }\n\n def Xform \"Model_13_JVAIJG2PTULA\" {\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/ZMXLP3JVAIJG2PTULA888888@\n )\n {\n }\n }\n\n def Xform \"Model_14_JVAVUWOPTULM\" {\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/6JVR45JVAVUWOPTULM888888@\n )\n {\n }\n }\n\n def Xform \"Cameras\"\n {\n def Camera \"MainCamera\"\n {\n float2 clippingRange = (0.1, 5000)\n float focalLength = 20.7846\n float fStop = 0\n float horizontalAperture = 42.6667\n float verticalAperture = 24.0000\n token projection = \"perspective\"\n 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) )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n }\n }\n\n def Xform \"Lights\"\n {\n def RectLight \"KeyRect\" (\n customData = {\n int manycore:affectReflections = 1\n bool manycore:doubleFace = false\n }\n )\n {\n color3f inputs:color = (1.0, 0.95, 0.90)\n float inputs:intensity = 4.0\n float inputs:exposure = 0.0\n float inputs:width = 1200\n float inputs:height = 600\n float inputs:specular = 1\n bool inputs:normalize = false\n matrix4d xformOp:transform = (\n (1, 0, 0, 0),\n (0, 1, 0, 0),\n (0, 0, 1, 0),\n (1200, 600, 2400, 1)\n )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n }\n\n def SphereLight \"FillPoint\"\n {\n color3f inputs:color = (0.70, 0.80, 1.00)\n float inputs:intensity = 40.0\n float inputs:exposure = -1.0\n float inputs:radius = 80\n float inputs:specular = 1\n bool inputs:normalize = false\n matrix4d xformOp:transform = (\n (1, 0, 0, 0),\n (0, 1, 0, 0),\n (0, 0, 1, 0),\n (-500, 900, 1800, 1)\n )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n }\n }\n}\n\ndef Scope \"Render\"\n{\n def RenderSettings \"MainRenderSettings\"\n {\n rel camera = \n int2 resolution = (1024, 576)\n custom float3 manycore:environment:giIntensity = (1.25, 1.25, 1.25)\n }\n}\n```\n\n## Realtime Patch\n\nRealtime 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.\n\n### Camera patch\n\n```usda\n#usda 1.0\n\nover \"World\"\n{\n over \"Cameras\"\n {\n over \"MainCamera\"\n {\n token projection = \"perspective\"\n float focalLength = 50\n float focusDistance = 100\n float horizontalAperture = 36.0\n float verticalAperture = 24.0\n float2 clippingRange = (0.1, 5000.0)\n matrix4d xformOp:transform = (\n (1, 0, 0, 0),\n (0, 1, 0, 0),\n (0, 0, -1, 0),\n (10, 20, 30, 1)\n )\n }\n }\n}\n```\n\n### Model patch\n\nUse 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.\n#### 3DGS model\n\n**Add a 3DGS model** with `def`, including the Transform, `xformOpOrder`, and `payload`:\n\n```usda\nover \"World\"\n{\n def Xform \"GaussianSplatModel2\"\n {\n matrix4d xformOp:transform = (\n (0.001, 0.0, 0.0, 0.0),\n (0.0, 0.0, 0.001, 0.0),\n (0.0, -0.001, 0.0, 0.0),\n (0.0, 0.0, 0.0, 1.0)\n )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def ParticleField3DGaussianSplat \"MyGaussianSplat2\" (\n payload = @manycore:/mesh/YYPZPUETQYRLIPTUKE888888@\n )\n {\n }\n }\n}\n```\n\n**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:\n\n```usda\nover \"World\"\n{\n over \"GaussianSplatModel2\"\n {\n matrix4d xformOp:transform = (\n (0.001, 0.0, 0.0, 0.0),\n (0.0, 0.0, 0.001, 0.0),\n (0.0, -0.001, 0.0, 0.0),\n (-2.01571919623, -0.262131040274, 1.279749806075, 1.0)\n )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n over ParticleField3DGaussianSplat \"MyGaussianSplat2\"\n {\n }\n }\n}\n```\n\n**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:\n\n```usda\nover \"World\"\n{\n over \"GaussianSplatModel2\"\n {\n over ParticleField3DGaussianSplat \"MyGaussianSplat2\"\n (\n customData = {\n string manycore:operation:type = \"del\"\n }\n )\n {\n }\n }\n}\n```\n\n#### Mesh model\n\n`Mesh` model patches use the same semantics as 3DGS; the `payload` target Prim is ``.\n\n**Add a Mesh model**:\n\n```usda\nover \"World\"\n{\n def Xform \"MeshModel2\"\n {\n matrix4d xformOp:transform = (\n (0.001, 0.0, 0.0, 0.0),\n (0.0, 0.0, 0.001, 0.0),\n (0.0, -0.001, 0.0, 0.0),\n (0.0, 0.0, 0.0, 1.0)\n )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n def Mesh \"Geom\" (\n payload = @manycore:/mesh/YYPZPUETQYRLIPTUKE888888@\n )\n {\n }\n }\n}\n```\n\n**Update a Mesh model Transform**:\n\n```usda\nover \"World\"\n{\n over \"MeshModel2\"\n {\n matrix4d xformOp:transform = (\n (0.001, 0.0, 0.0, 0.0),\n (0.0, 0.0, 0.001, 0.0),\n (0.0, -0.001, 0.0, 0.0),\n (-2.01571919623, -0.262131040274, 1.279749806075, 1.0)\n )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n over Mesh \"Geom\"\n {\n }\n }\n}\n```\n\n**Delete a Mesh model**:\n\n```usda\nover \"World\"\n{\n over \"MeshModel2\"\n {\n over Mesh \"Geom\"\n (\n customData = {\n string manycore:operation:type = \"del\"\n }\n )\n {\n }\n }\n}\n```\n\nModel 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`.\n\n### Light patch\n\nWhen 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`:\n\n```usda\nover \"World\"\n{\n over \"Lights\"\n {\n over RectLight \"KeyRect\"\n {\n color3f inputs:color = (1.0, 0.72, 0.50)\n float inputs:intensity = 8.0\n }\n }\n}\n```\n\nAdd a light with `def` and complete fields. Delete an existing light with the same path and `manycore:operation:type = \"del\"`:\n\n```usda\nover \"World\"\n{\n over \"Lights\"\n {\n def SphereLight \"Accent\"\n {\n color3f inputs:color = (0.2, 0.4, 1.0)\n float inputs:intensity = 12.0\n float inputs:exposure = 0.0\n float inputs:radius = 50.0\n float inputs:specular = 1\n bool inputs:normalize = false\n matrix4d xformOp:transform = (\n (1, 0, 0, 0),\n (0, 1, 0, 0),\n (0, 0, 1, 0),\n (300, 400, 500, 1)\n )\n uniform token[] xformOpOrder = [\"xformOp:transform\"]\n }\n\n over SphereLight \"FillPoint\" (\n customData = { string manycore:operation:type = \"del\" }\n ) {}\n }\n}\n```\n\n### Environment-light patch\n\nAn environment-light patch must target the same `RenderSettings` Prim path recorded during initialization. Explicitly writing the types is recommended:\n\n```usda\n#usda 1.0\n\nover Scope \"Render\"\n{\n over RenderSettings \"MainRenderSettings\"\n {\n custom float3 manycore:environment:giIntensity = (0.8, 0.8, 0.8)\n }\n}\n```\n\nEnvironment-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.\n\n## Supported Prims\n\n| Prim Type | Support | Key Attributes / Metadata |\n|-----------|---------|---------------------------|\n| `Xform` | Supported | `xformOp:transform`, `xformOpOrder`; can be a model parent for `def` / `over` |\n| `Mesh` | Supported | `payload` metadata; removable through `over` and the delete marker |\n| `ParticleField3DGaussianSplat` | Supported | `payload` metadata; removable through `over` and the delete marker |\n| `Camera` | Supported | Camera parameters and pose |\n| `RectLight` | Supported | `inputs:color`, `inputs:intensity`, `inputs:exposure`, `inputs:width`, `inputs:height`, `inputs:specular`, `xformOp:transform` |\n| `SphereLight` | Supported | `inputs:color`, `inputs:intensity`, `inputs:exposure`, `inputs:radius`, `inputs:specular`, `xformOp:transform` |\n| `RenderSettings` | Supported | `camera`, `resolution`, `manycore:environment:giIntensity` |\n| `Scope` | Supported | Hierarchy container |\n| Other USD types | Ignored | Not used for rendering |\n\n## Limitations\n\n| Item | Description |\n|------|-------------|\n| **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 |\n| **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 |\n| Light transforms | `xformOp:transform` alone is not in the USD transform stack; always write `xformOpOrder` with it |\n| Environment-light intensity | The three `manycore:environment:giIntensity` values must be finite and positive; clearing with `0`, attribute deletion, or Prim deletion is unsupported |\n| Unsupported light types | `DistantLight`, `DiskLight`, `DomeLight`, Spot/IES/MeshLight, light linking, projected textures, and color temperature are not rendered |\n| Full USD composition | `references`, `subLayers`, `variantSets`, material networks, and similar composition features are not supported |\n| Multiple cameras / RenderSettings | The first one found during traversal is used |\n| Unknown attributes | Ignored without error |\n| Syntax errors | Unclosed braces or invalid attribute values cause parsing failure |\n| Missing asset | Rendering may fail or miss the referenced asset |\n",
"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.\n\n**Recommended flow:**\n1. Call this endpoint to get `ousToken`, `globalDomain` (e.g. `https://ous-sg.kujiale.com`), and `blockSize`.\n2. If file size **≤ `blockSize`**: call `ousCosSingleUpload`; if **> `blockSize`**: call `ousCosBlockUploadInit` then `ousCosBlockUploadPart` as needed.\n3. Poll `ousCosUploadStatus` until success and you receive `url`.\n4. Use the public URL in downstream APIs, e.g. `resources[].url` for **Create 3DGS world reconstruction**.\n",
"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';\n\n// SDK handles token, multipart upload, and polling — no need to call this endpoint directly\nconst asset = createAssetClient({ region: 'com' });\nconst result = await asset.uploadFile('./video.mp4');\nconsole.log(result.url);"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.asset.AssetClient;\nimport com.manycoreapis.sdk.asset.UploadResult;\nimport com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\n\nAssetClient asset = AssetClient.create(AholoClientConfig.ofRegion(\"com\"));\nUploadResult result = asset.uploadFile(Paths.get(\"video.mp4\"));\nSystem.out.println(result.url());"
},
{
"lang": "Python",
"label": "Aholo SDK (Python)",
"source": "from manycore.aholo_sdk_asset import create_asset_client\n\n# SDK handles token, multipart upload, and polling — no need to call this endpoint directly\nasset = create_asset_client(region='com')\nresult = asset.upload_file('./video.mp4')\nprint(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}`).\n**Resource formats**: image: .jpg / .jpeg / .png / .webp; video: .mp4 / .mov; insv: .insv.\n**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).\n",
"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';\n\nconst world = createWorldClient({ region: 'com' });\nconst { worldId } = await world.reconstructions.create({\n name: 'Living room',\n resources: [{ url: 'https://cdn.example.com/room.mp4', type: 'video' }],\n taskQuality: 'normal',\n scene: 'model',\n});\nconst detail = await world.waitFor(worldId);\nconsole.log(detail.assets?.splats?.urls?.plyPath);"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\nimport com.manycoreapis.sdk.world.WorldClient;\nimport com.manycoreapis.sdk.world.model.ReconstructionCreateParams;\nimport com.manycoreapis.sdk.world.model.GenerationCreateParams;\nimport com.manycoreapis.sdk.world.model.WorldListParams;\nimport com.manycoreapis.sdk.world.model.WorldAsyncOperation;\nimport com.manycoreapis.sdk.world.model.WorldDetail;\nimport com.manycoreapis.sdk.world.model.WorldPagedList;\n\nWorldClient world = WorldClient.create(AholoClientConfig.ofRegion(\"com\"));\nWorldAsyncOperation op = world.reconstructions().create(\n ReconstructionCreateParams.builder()\n .name(\"Living room\")\n .addResource(\"https://cdn.example.com/room.mp4\", \"video\")\n .taskQuality(\"normal\")\n .scene(\"model\")\n .build());\nWorldDetail detail = world.waitFor(op.worldId());"
},
{
"lang": "Python",
"label": "Aholo SDK (Python)",
"source": "from manycore.aholo_sdk_world import create_world_client\n\nworld = create_world_client(region='com')\nop = world.reconstructions.create(\n name='Living room',\n resources=[{'url': 'https://cdn.example.com/room.mp4', 'type': 'video'}],\n task_quality='normal',\n scene='model',\n)\ndetail = world.wait_for(op['worldId'])\nprint(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';\n\nconst world = createWorldClient({ region: 'com' });\nconst { worldId } = await world.generations.create({\n name: 'Forest cabin',\n prompt: 'A modern cabin in the forest',\n});\nconst detail = await world.waitFor(worldId);"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\nimport com.manycoreapis.sdk.world.WorldClient;\nimport com.manycoreapis.sdk.world.model.ReconstructionCreateParams;\nimport com.manycoreapis.sdk.world.model.GenerationCreateParams;\nimport com.manycoreapis.sdk.world.model.WorldListParams;\nimport com.manycoreapis.sdk.world.model.WorldAsyncOperation;\nimport com.manycoreapis.sdk.world.model.WorldDetail;\nimport com.manycoreapis.sdk.world.model.WorldPagedList;\n\nWorldClient world = WorldClient.create(AholoClientConfig.ofRegion(\"com\"));\nWorldAsyncOperation op = world.generations().create(\n GenerationCreateParams.builder()\n .name(\"Forest cabin\")\n .prompt(\"A modern cabin in the forest\")\n .build());\nWorldDetail detail = world.waitFor(op.worldId());"
},
{
"lang": "Python",
"label": "Aholo SDK (Python)",
"source": "from manycore.aholo_sdk_world import create_world_client\n\nworld = create_world_client(region='com')\nop = world.generations.create(\n name='Forest cabin',\n prompt='A modern cabin in the forest',\n)\ndetail = 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';\n\nconst world = createWorldClient({ region: 'com' });\nconst detail = await world.retrieve('A1b2C3d4E5');\nconsole.log(detail.status);"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\nimport com.manycoreapis.sdk.world.WorldClient;\nimport com.manycoreapis.sdk.world.model.ReconstructionCreateParams;\nimport com.manycoreapis.sdk.world.model.GenerationCreateParams;\nimport com.manycoreapis.sdk.world.model.WorldListParams;\nimport com.manycoreapis.sdk.world.model.WorldAsyncOperation;\nimport com.manycoreapis.sdk.world.model.WorldDetail;\nimport com.manycoreapis.sdk.world.model.WorldPagedList;\n\nWorldClient world = WorldClient.create(AholoClientConfig.ofRegion(\"com\"));\nWorldDetail detail = world.retrieve(\"A1b2C3d4E5\");\ndetail.status().ifPresent(System.out::println);"
},
{
"lang": "Python",
"label": "Aholo SDK (Python)",
"source": "from manycore.aholo_sdk_world import create_world_client\n\nworld = create_world_client(region='com')\ndetail = world.retrieve('A1b2C3d4E5')\nprint(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';\n\nconst world = createWorldClient({ region: 'com' });\nconst page = await world.list({ pageNum: 1, pageSize: 20 });\npage.result?.forEach((w) => console.log(w.worldId, w.status));"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\nimport com.manycoreapis.sdk.world.WorldClient;\nimport com.manycoreapis.sdk.world.model.ReconstructionCreateParams;\nimport com.manycoreapis.sdk.world.model.GenerationCreateParams;\nimport com.manycoreapis.sdk.world.model.WorldListParams;\nimport com.manycoreapis.sdk.world.model.WorldAsyncOperation;\nimport com.manycoreapis.sdk.world.model.WorldDetail;\nimport com.manycoreapis.sdk.world.model.WorldPagedList;\n\nWorldClient world = WorldClient.create(AholoClientConfig.ofRegion(\"com\"));\nWorldPagedList page = world.list(\n WorldListParams.builder().pageNum(1).pageSize(20).build());\npage.result().ifPresent(items ->\n 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\n\nworld = create_world_client(region='com')\npage = world.list(page_num=1, page_size=20)\nfor w in page.get('result', []):\n 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.\n",
"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';\n\nconst lux3d = createLux3dClient({ region: 'com' });\nconst taskId = await lux3d.multimodalToImage.create({\n prompt: 'A wooden chair product photo, white background',\n img: 'https://example.com/object.jpg',\n});\nconst result = await lux3d.tasks.waitFor(taskId);"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\nimport com.manycoreapis.sdk.lux3d.Lux3dClient;\nimport com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskListParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskPagedList;\nimport com.manycoreapis.sdk.lux3d.model.TaskResult;\n\nLux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion(\"com\"));\nlong taskId = lux3d.multimodalToImage().create(\n MultimodalToImageCreateParams.builder()\n .prompt(\"A wooden chair product photo, white background\")\n .img(\"https://example.com/object.jpg\")\n .build());\nTaskResult result = lux3d.tasks().waitFor(taskId);"
},
{
"lang": "Python",
"label": "Aholo SDK (Python)",
"source": "from manycore.aholo_sdk_lux3d import create_lux3d_client\n\nlux3d = create_lux3d_client(region='com')\ntask_id = lux3d.multimodal_to_image.create(\n prompt='A wooden chair product photo, white background',\n img='https://example.com/object.jpg',\n)\nresult = 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.\n",
"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';\n\nconst lux3d = createLux3dClient({ region: 'com' });\nconst taskId = await lux3d.imageToFourView.create({\n img: 'https://example.com/object.jpg',\n prompt: 'Product four-view, white background',\n});\nconst result = await lux3d.tasks.waitFor(taskId);"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\nimport com.manycoreapis.sdk.lux3d.Lux3dClient;\nimport com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskListParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskPagedList;\nimport com.manycoreapis.sdk.lux3d.model.TaskResult;\n\nLux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion(\"com\"));\nlong taskId = lux3d.imageToFourView().create(\n ImageToFourViewCreateParams.builder()\n .img(\"https://example.com/object.jpg\")\n .prompt(\"Product four-view, white background\")\n .build());\nTaskResult result = lux3d.tasks().waitFor(taskId);"
},
{
"lang": "Python",
"label": "Aholo SDK (Python)",
"source": "from manycore.aholo_sdk_lux3d import create_lux3d_client\n\nlux3d = create_lux3d_client(region='com')\ntask_id = lux3d.image_to_four_view.create(\n img='https://example.com/object.jpg',\n prompt='Product four-view, white background',\n)\nresult = 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.\n",
"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';\n\nconst lux3d = createLux3dClient({ region: 'com' });\nconst taskId = await lux3d.imgTo3d.create({\n img: 'https://example.com/object.jpg',\n version: 'G1',\n});\nconst result = await lux3d.tasks.waitFor(taskId);\nconsole.log(result.outputs[0]?.content);"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\nimport com.manycoreapis.sdk.lux3d.Lux3dClient;\nimport com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskListParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskPagedList;\nimport com.manycoreapis.sdk.lux3d.model.TaskResult;\n\nLux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion(\"com\"));\nlong taskId = lux3d.imgTo3d().create(\n ImgTo3dCreateParams.builder()\n .img(\"https://example.com/object.jpg\")\n .version(\"G1\")\n .build());\nTaskResult result = lux3d.tasks().waitFor(taskId);\nresult.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\n\nlux3d = create_lux3d_client(region='com')\ntask_id = lux3d.img_to_3d.create(img='https://example.com/object.jpg', version='G1')\nresult = lux3d.tasks.wait_for(task_id)\nprint(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.\n",
"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';\n\nconst lux3d = createLux3dClient({ region: 'com' });\nconst taskId = await lux3d.textTo3d.create({\n prompt: 'A wooden chair with carved legs',\n version: 'G1',\n});\nconst result = await lux3d.tasks.waitFor(taskId);"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\nimport com.manycoreapis.sdk.lux3d.Lux3dClient;\nimport com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskListParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskPagedList;\nimport com.manycoreapis.sdk.lux3d.model.TaskResult;\n\nLux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion(\"com\"));\nlong taskId = lux3d.textTo3d().create(\n TextTo3dCreateParams.builder()\n .prompt(\"A wooden chair with carved legs\")\n .version(\"G1\")\n .build());\nTaskResult result = lux3d.tasks().waitFor(taskId);"
},
{
"lang": "Python",
"label": "Aholo SDK (Python)",
"source": "from manycore.aholo_sdk_lux3d import create_lux3d_client\n\nlux3d = create_lux3d_client(region='com')\ntask_id = lux3d.text_to_3d.create(prompt='A wooden chair with carved legs', version='G1')\nresult = 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.\n",
"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';\n\nconst lux3d = createLux3dClient({ region: 'com' });\nconst taskId = await lux3d.materialTransfer.create({\n img: 'https://example.com/material.jpg',\n meshUrl: 'https://example.com/model.glb',\n version: 'v3.0-standard',\n});\nconst result = await lux3d.tasks.waitFor(taskId);"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\nimport com.manycoreapis.sdk.lux3d.Lux3dClient;\nimport com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskListParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskPagedList;\nimport com.manycoreapis.sdk.lux3d.model.TaskResult;\n\nLux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion(\"com\"));\nlong taskId = lux3d.materialTransfer().create(\n MaterialTransferCreateParams.builder()\n .img(\"https://example.com/material.jpg\")\n .meshUrl(\"https://example.com/model.glb\")\n .version(\"v3.0-standard\")\n .build());\nTaskResult result = lux3d.tasks().waitFor(taskId);"
},
{
"lang": "Python",
"label": "Aholo SDK (Python)",
"source": "from manycore.aholo_sdk_lux3d import create_lux3d_client\n\nlux3d = create_lux3d_client(region='com')\ntask_id = lux3d.material_transfer.create(\n img='https://example.com/material.jpg',\n mesh_url='https://example.com/model.glb',\n version='v3.0-standard',\n)\nresult = 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.\nIf the authenticated account already has a part-splitting task in progress, no task is created. Retry later.\n",
"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';\n\nconst lux3d = createLux3dClient({ region: 'com' });\nconst taskId = await lux3d.partSplit.create({\n glbUrl: 'https://example.com/model.glb',\n});\nconst result = await lux3d.tasks.waitFor(taskId);"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\nimport com.manycoreapis.sdk.lux3d.Lux3dClient;\nimport com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskListParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskPagedList;\nimport com.manycoreapis.sdk.lux3d.model.TaskResult;\n\nLux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion(\"com\"));\nlong taskId = lux3d.partSplit().create(\n PartSplitCreateParams.builder()\n .glbUrl(\"https://example.com/model.glb\")\n .build());\nTaskResult result = lux3d.tasks().waitFor(taskId);"
},
{
"lang": "Python",
"label": "Aholo SDK (Python)",
"source": "from manycore.aholo_sdk_lux3d import create_lux3d_client\n\nlux3d = create_lux3d_client(region='com')\ntask_id = lux3d.part_split.create(glb_url='https://example.com/model.glb')\nresult = 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.\n",
"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';\n\nconst lux3d = createLux3dClient({ region: 'com' });\nconst taskId = await lux3d.multiFormatExport.create({\n modelUrl: 'https://example.com/model.glb',\n outputFormat: ['usdz', 'obj_zip', 'stl'],\n});\nconst result = await lux3d.tasks.waitFor(taskId);"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\nimport com.manycoreapis.sdk.lux3d.Lux3dClient;\nimport com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskListParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskPagedList;\nimport com.manycoreapis.sdk.lux3d.model.TaskResult;\n\nLux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion(\"com\"));\nlong taskId = lux3d.multiFormatExport().create(\n MultiFormatExportCreateParams.builder()\n .modelUrl(\"https://example.com/model.glb\")\n .outputFormat(java.util.Arrays.asList(\"usdz\", \"obj_zip\", \"stl\"))\n .build());\nTaskResult result = lux3d.tasks().waitFor(taskId);"
},
{
"lang": "Python",
"label": "Aholo SDK (Python)",
"source": "from manycore.aholo_sdk_lux3d import create_lux3d_client\n\nlux3d = create_lux3d_client(region='com')\ntask_id = lux3d.multi_format_export.create(\n model_url='https://example.com/model.glb',\n output_format=['usdz', 'obj_zip', 'stl'],\n)\nresult = 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.\n",
"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';\n\nconst lux3d = createLux3dClient({ region: 'com' });\nconst taskId = await lux3d.articulationAnimation.create({\n glbUrl: 'https://example.com/model.glb',\n prompt: 'Keep the base fixed and slowly open and close the lid',\n});\nconst result = await lux3d.tasks.waitFor(taskId);"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\nimport com.manycoreapis.sdk.lux3d.Lux3dClient;\nimport com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskListParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskPagedList;\nimport com.manycoreapis.sdk.lux3d.model.TaskResult;\n\nLux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion(\"com\"));\nlong taskId = lux3d.articulationAnimation().create(\n ArticulationAnimationCreateParams.builder()\n .glbUrl(\"https://example.com/model.glb\")\n .prompt(\"Keep the base fixed and slowly open and close the lid\")\n .build());\nTaskResult result = lux3d.tasks().waitFor(taskId);"
},
{
"lang": "Python",
"label": "Aholo SDK (Python)",
"source": "from manycore.aholo_sdk_lux3d import create_lux3d_client\n\nlux3d = create_lux3d_client(region='com')\ntask_id = lux3d.articulation_animation.create(\n glb_url='https://example.com/model.glb',\n prompt='Keep the base fixed and slowly open and close the lid',\n)\nresult = 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.\n",
"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';\n\nconst lux3d = createLux3dClient({ region: 'com' });\nconst taskId = await lux3d.humanoidAutoRig.create({\n modelUrl: 'https://example.com/human.glb',\n});\nconst result = await lux3d.tasks.waitFor(taskId);"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\nimport com.manycoreapis.sdk.lux3d.Lux3dClient;\nimport com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskListParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskPagedList;\nimport com.manycoreapis.sdk.lux3d.model.TaskResult;\n\nLux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion(\"com\"));\nlong taskId = lux3d.humanoidAutoRig().create(\n HumanoidAutoRigCreateParams.builder()\n .modelUrl(\"https://example.com/human.glb\")\n .build());\nTaskResult result = lux3d.tasks().waitFor(taskId);"
},
{
"lang": "Python",
"label": "Aholo SDK (Python)",
"source": "from manycore.aholo_sdk_lux3d import create_lux3d_client\n\nlux3d = create_lux3d_client(region='com')\ntask_id = lux3d.humanoid_auto_rig.create(model_url='https://example.com/human.glb')\nresult = 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.\n",
"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';\n\nconst lux3d = createLux3dClient({ region: 'com' });\nconst taskId = await lux3d.humanoidAnimationRetarget.create({\n rigModelUrl: 'https://example.com/rig.glb',\n animationIds: ['Idle_Loop', 'Walk_Loop'],\n outFormat: 'glb',\n});\nconst result = await lux3d.tasks.waitFor(taskId);"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\nimport com.manycoreapis.sdk.lux3d.Lux3dClient;\nimport com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskListParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskPagedList;\nimport com.manycoreapis.sdk.lux3d.model.TaskResult;\n\nLux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion(\"com\"));\nlong taskId = lux3d.humanoidAnimationRetarget().create(\n HumanoidAnimationRetargetCreateParams.builder()\n .rigModelUrl(\"https://example.com/rig.glb\")\n .animationIds(java.util.Arrays.asList(\"Idle_Loop\", \"Walk_Loop\"))\n .outFormat(\"glb\")\n .build());\nTaskResult result = lux3d.tasks().waitFor(taskId);"
},
{
"lang": "Python",
"label": "Aholo SDK (Python)",
"source": "from manycore.aholo_sdk_lux3d import create_lux3d_client\n\nlux3d = create_lux3d_client(region='com')\ntask_id = lux3d.humanoid_animation_retarget.create(\n rig_model_url='https://example.com/rig.glb',\n animation_ids=['Idle_Loop', 'Walk_Loop'],\n out_format='glb',\n)\nresult = 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).\nResult 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.\n\nRead results from `d.outputs[].content` according to the task type:\n\n| Task type | Result content and order |\n| --- | --- |\n| Multimodal single-image generation | One image URL. |\n| Multimodal four-view generation | One JSON-array string containing four image URLs in this order: `FRONT_THREE_QUARTER`, `OPPOSITE_THREE_QUARTER`, `SIDE`, `BACK`. |\n| G1 image-to-3D / text-to-3D | ZIP and GLB URLs, followed by PLY when requested. |\n| G1-Turbo image-to-3D / text-to-3D | URLs for the requested formats; ZIP when `outputFormat` is omitted or empty. |\n| Material transfer | ZIP, GLB, USDZ, OBJ ZIP, and FBX ZIP, in that order. |\n| Multi-format export | ZIP, GLB, USDZ, OBJ ZIP, FBX ZIP, STL, and 3MF, in that order. |\n| Part splitting | One GLB file URL containing the split parts. |\n| 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. |\n| Humanoid auto-rigging | A rigged GLB file URL on success, or a JSON string containing `error` on failure. |\n| Humanoid animation retargeting | A JSON string containing `actions`, with a result URL or error for each action. |\n\nFor 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.\n",
"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';\n\nconst lux3d = createLux3dClient({ region: 'com' });\nconst result = await lux3d.tasks.retrieve(taskId);\nconsole.log(result.status, result.outputs);\n// 或 await lux3d.tasks.waitFor(taskId) to poll until success"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\nimport com.manycoreapis.sdk.lux3d.Lux3dClient;\nimport com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskListParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskPagedList;\nimport com.manycoreapis.sdk.lux3d.model.TaskResult;\n\nLux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion(\"com\"));\nTaskResult result = lux3d.tasks().retrieve(taskId);\nSystem.out.println(result.status());\n// 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\n\nlux3d = create_lux3d_client(region='com')\nresult = lux3d.tasks.retrieve(task_id)\nprint(result.get('status'), result.get('outputs'))\n# 或 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.\n",
"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';\n\nconst lux3d = createLux3dClient({ region: 'com' });\nconst page = await lux3d.tasks.list({ page: 1, pageSize: 20, status: 3 });\npage.items.forEach((task) => console.log(task.taskId, task.status));"
},
{
"lang": "Java",
"label": "Aholo SDK (Java)",
"source": "import com.manycoreapis.sdk.core.AholoClientConfig;\nimport java.nio.file.Paths;\nimport com.manycoreapis.sdk.lux3d.Lux3dClient;\nimport com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskListParams;\nimport com.manycoreapis.sdk.lux3d.model.TaskPagedList;\nimport com.manycoreapis.sdk.lux3d.model.TaskResult;\n\nLux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion(\"com\"));\nTaskPagedList page = lux3d.tasks().list(\n TaskListParams.builder().page(1).pageSize(20).status(3).build());\npage.items().forEach(task ->\n System.out.println(task.taskId() + \" \" + task.status()));"
},
{
"lang": "Python",
"label": "Aholo SDK (Python)",
"source": "from manycore.aholo_sdk_lux3d import create_lux3d_client\n\nlux3d = create_lux3d_client(region='com')\npage = lux3d.tasks.list(page=1, page_size=20, status=3)\nfor task in page['items']:\n 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.\n\n## Submit mode\n\nWhen `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.\n\nThe server returns HTTP 202 with `{operationId, metaData:null, done:false, result:null, error:null}`. The `operationId` is the render task ID.\n\n`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`.\n\n## Poll mode\n\nWhen `operationId` is present, the same POST endpoint polls the job status.\n\n- Processing: `done=false`\n- Succeeded: `done=true + result.taskId/resultUrl`\n- Failed: `done=true + error`\n\n## Rendering constraints\n\nThis 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.\n\n## REST response statuses\n\n| HTTP status | Scenario | Response |\n|-----------|------|---------|\n| `202` | Submit mode | Job accepted; returns `operationId` for polling |\n| `200` | Poll mode | Returns current `Operation`; completed responses include `resultUrl` |\n| `400` | Invalid argument | Missing `requestId` or `usdContent`; missing/invalid OpenUSD resolution; invalid Base64; or OpenUSD parse failure |\n| `404` | Not found | No job exists for `operationId` |\n| `409` | Duplicate request | The same user submitted the same `requestId` again within 1 minute |\n| `429` | Rate limited | User-level offline render frequency exceeded |\n| `500` | Internal error | Job creation, conversion, or render dispatch failed |\n",
"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.\n\n## Submit mode\n\nWhen `operationId` is empty, a new session is created. `requestId` and `usdContent` are required.\nOptional `settings.autoEnhanceAI` enables AI enhancement. Omit it or set it to `false` to disable enhancement.\n\nThe server returns HTTP 202 with `{operationId, metaData:null, done:false, result:null, error:null}`. The returned `operationId` is the `sessionId`.\n\n## Poll mode\n\nWhen `operationId` is present, poll the session status. Recommended polling interval is 2 seconds; timeout is 120 seconds.\n\nWhen `status` is `ACTIVE`, `result` contains `host`, `nodeId`, `streamId`, and `token`, which are required to open the WebSocket Streaming connection.\n\n## REST response statuses\n\n| HTTP status | Scenario | Response |\n|-----------|------|---------|\n| `202` | Submit mode | Session is being created; returns `operationId` for polling |\n| `200` | Poll mode | Current `Operation`; processing is `done=false`, success is `done=true + result`, failure is `done=true + error` |\n| `400` | Invalid argument | Request body is missing required fields or contains invalid values |\n| `404` | Not found | `operationId` or session does not exist |\n| `429` | Rate limited | Request frequency exceeded |\n| `500` | Internal error | Internal server error |\n\n## WebSocket Streaming protocol\n\n### Connection URL\n\n```\nwss://{host}/streaming/ws/session?nid={encodeURIComponent(nodeId)}&token={encodeURIComponent(token)}\n```\n\nSet `ws.binaryType = 'blob'` when creating the WebSocket; otherwise image frames cannot be received as Blob objects.\n\n### Handshake\n\nImmediately after WebSocket `onopen`, send:\n\n```json\n{\"type\":3,\"slaveInit\":{\"masterStreamingId\":\"{streamId}\",\"receiveImage\":true}}\n```\n\n| Field | Value | Description |\n|------|-----|------|\n| type | fixed `3` | Slave initialization message |\n| slaveInit.masterStreamingId | `{streamId}` | The streamId returned by this API |\n| slaveInit.receiveImage | fixed `true` | Receive rendered images |\n\n### Server messages\n\nJSON 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.\n\nStatus codes:\n\n| code | Meaning | Connection state change |\n|------|------|-------------|\n| `\"0\"` | Initialized | Success |\n| `\"1000\"` | Node overloaded | Error |\n| `\"1001\"` | Initialization failed | Error |\n| `\"1003\"` | Slave limit exceeded | SlaveExceeded |\n| `\"2001\"` | Engine render error | No connection state change; only render failure callback |\n| `\"2002\"` | Engine process error | No connection state change; only render failure callback |\n\nClose the WebSocket first, then call the DELETE API to end the server-side session.\n",
"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.\n\nThis 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.\n\n## Requirements\n\n- `sessionId` must be the `operationId` returned by `/rendercloud/v1/streams` after creation.\n- Session status must be `ACTIVE`, otherwise the update is rejected.\n- `requestId` is generated by the caller for idempotency and request records.\n- `usdContent` is Base64-encoded incremental OpenUSD content.\n\n## REST response statuses\n\n| HTTP status | Scenario | Response |\n|-----------|------|---------|\n| `200` | Updated | Returns session ID and current session status |\n| `400` | Invalid argument | Missing `requestId` or `usdContent`, or invalid request body |\n| `404` | Not found | No session exists for `sessionId` |\n| `429` | Rate limited | User-level realtime render frequency exceeded |\n| `500` | Internal error | Session is not ACTIVE, forwarding failed, or update was rejected by the render pipeline |\n",
"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.\n\nWhen 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.\n\n## REST response statuses\n\n| HTTP status | Scenario | Response |\n|-----------|------|---------|\n| `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 |\n| `404` | Not found | The node that owns the session reports that the session does not exist |\n| `429` | Rate limited | User-level realtime render frequency exceeded |\n| `500` | Internal error | Forwarding failed or an internal server error occurred |\n",
"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.\n\nSpecify the original 3D file URL with `originMeshUrl`. The optional `fastUpload` field enables fast upload and defaults to `false`.\nWhen `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.\n\n## REST Response Status\n\n| HTTP Status | Scenario | Response Description |\n|-----------|------|---------|\n| `200` | Task created successfully | Returns the task ID |\n| `400` | Invalid arguments | `originMeshUrl` missing or invalid |\n| `500` | Internal error | Task creation or processing error |\n",
"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.\n\nThis 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,\nand the output data is wrapped for processing.\nTask status: `0`=INIT, `1`=RUNNING, `3`=SUCCESS, `4`=FAIL\n\n## Requirements\n\n- `taskid` must come from the task ID returned by the task creation API\n\n## REST Response Status\n\n| HTTP Status | Scenario | Response Description |\n|-----------|------|---------|\n| `200` | Query succeeded | Returns task details |\n| `400` | Invalid arguments | `taskid` missing or invalid |\n| `404` | Task not found | Specified task ID does not exist |\n| `500` | Internal error | Query error |\n",
"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`.\n\n**Guide**: `5` success (use `url`); `6`/`8` terminal failure—stop polling; others keep polling.\n\n| Value | Meaning | Terminal |\n|---|---|---|\n| 0 | Draft | No |\n| 1 | Basic checks done | No |\n| 2 | Content checks done | No |\n| 3 | Queued | No |\n| 4 | Uploading | No |\n| 5 | Success | **Yes** |\n| 6 | Failed | **Yes** |\n| 7 | Reviewing | No |\n| 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).\n\n| Code | Meaning | Suggestion |\n|---|---|---|\n| 1 | Config error | Check upload config |\n| 2 | Bad file size | Check size / parts |\n| 3 | Bad format | Change format / retry |\n| 4 | Bad content | Change content |\n| 5 | Safety check failed | Change asset |\n| 6 | Upload throttled | Backoff / fewer concurrent |\n| 7 | Uploading | Poll / retry later |\n| 8 | Part failed | Retry parts / restart |\n| 9 | Server limit | Backoff |\n| 10 | Pool full | Backoff |\n| 11 | Metadata too large | Shrink metadata |\n| 12 | Token issue | Re-fetch token / re-init |\n| 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).\n**Resource formats**: image: .jpg / .jpeg / .png / .webp; video: .mp4 / .mov; insv: .insv.\n**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).\n"
},
"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.\n- usdz: AR model format commonly used in the Apple ecosystem, suitable for iOS, iPadOS, and Quick Look AR previews.\n- obj_zip: Archive containing OBJ, MTL, and texture files, compatible with common 3D software and DCC tools.\n- fbx_zip: Archive containing an FBX model and texture assets, suitable for mainstream DCC workflows such as Maya, 3ds Max, and Blender.\n- stl: Mesh format for 3D printing and geometry exchange. It does not contain material or texture information.\n- 3mf: 3D Manufacturing Format for 3D printing workflows and manufacturing/printing delivery.\nFor ZIP input, outputFormat may be omitted or empty; GLB input requires at least one value.\n",
"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.\nThe 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.\n"
},
"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.\n\n- `INITIALIZING`: The session has been created and the backend is establishing the streaming connection.\n- `ACTIVE`: The streaming connection is ready and can render normally.\n- `FAILED`: Initialization or operation failed.\n- `CLOSED`: The session has been closed.\n",
"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:\n- `0`: INIT\n- `1`: RUNNING\n- `3`: SUCCESS\n- `4`: FAIL\n",
"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:\n- For Mesh upload task input: original Mesh URL\n- For Mesh upload task output: parsed meshId\n",
"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.\n\nBlock form: upper-left `R` is 3×3 rotation, right `t` is translation, bottom row is `[0, 0, 0, 1]`.\n\n```\nT = [ R(3×3) t(3×1) ]\n [ 0(1×3) 1 ]\n```\n\nRequest-body indices:\n\n```\n[\n [ r00, r01, r02, tx ],\n [ r10, r11, r12, ty ],\n [ r20, r21, r22, tz ],\n [ 0, 0, 0, 1 ]\n]\n```",
"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.\n\nBlock form: upper-left `R` is 3×3 rotation, right `t` is translation, bottom row is `[0, 0, 0, 1]`.\n\n```\nT = [ R(3×3) t(3×1) ]\n [ 0(1×3) 1 ]\n```\n\nRequest-body indices:\n\n```\n[\n [ r00, r01, r02, tx ],\n [ r10, r11, r12, ty ],\n [ r20, r21, r22, tz ],\n [ 0, 0, 0, 1 ]\n]\n```",
"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.\n\nBlock form: upper-left `R` is 3×3 rotation, right `t` is translation, bottom row is `[0, 0, 0, 1]`.\n\n```\nT = [ R(3×3) t(3×1) ]\n [ 0(1×3) 1 ]\n```\n\nRequest-body indices:\n\n```\n[\n [ r00, r01, r02, tx ],\n [ r10, r11, r12, ty ],\n [ r20, r21, r22, tz ],\n [ 0, 0, 0, 1 ]\n]\n```",
"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.\n\nCoordinate system: meters, right-handed, Z-up ([ScanNet Alignment](https://github.com/ScanNet/ScanNet/tree/master/Alignment)).\n\nLine format: `{id}={Type}(arg1,arg2,...)`. Skip unknown `Type` values; do not fail the whole file.\n\n| Type | Line format |\n| --- | --- |\n| Wall | `wall_{n}=Wall(ax,ay,az,bx,by,bz,height,thickness)` |\n| Door | `door_{n}=Door(wall_id,position_x,position_y,position_z,width,height)` |\n| Window | `window_{n}=Window(wall_id,position_x,position_y,position_z,width,height)` |\n| Bbox | `bbox_{n}=Bbox(class,position_x,position_y,position_z,angle_z,scale_x,scale_y,scale_z)` |\n\n| Type | Field | Data type | Description |\n| --- | --- | --- | --- |\n| Wall | `ax, ay, az` | number | 3D coordinates of start point A of the wall baseline on the floor. |\n| Wall | `bx, by, bz` | number | 3D coordinates of end point B of the wall baseline on the floor. |\n| Wall | `height` | number | Wall height. |\n| Wall | `thickness` | number | Wall thickness; currently `0.0` because the detector outputs inner-room contour edges. |\n| Door | `wall_id` | string | Id of the wall that owns the door, e.g. `wall_0`; must refer to a wall in this file. |\n| Door | `position_x, position_y, position_z` | number | 3D coordinates of the door-opening center. |\n| Door | `width` | number | Opening width along the owning wall. |\n| Door | `height` | number | Vertical height of the opening. |\n| Window | `wall_id` | string | Id of the wall that owns the window, e.g. `wall_4`; must refer to a wall in this file. |\n| Window | `position_x, position_y, position_z` | number | 3D coordinates of the window-opening center. |\n| Window | `width` | number | Opening width along the owning wall. |\n| Window | `height` | number | Vertical height of the opening. |\n| Bbox | `class` | string | Object class, e.g. `chair`, `sofa`, `carpet`, `coffee_table`. |\n| Bbox | `position_x, position_y, position_z` | number | Center of the 3D bounding box. |\n| Bbox | `angle_z` | number | Box rotation around Z, i.e. heading in the horizontal plane. |\n| Bbox | `scale_x` | number | Full extent along the box local X axis (not half-size). |\n| Bbox | `scale_y` | number | Full extent along the box local Y axis (not half-size). |\n| Bbox | `scale_z` | number | Full extent along the box local Z axis (height). |\n\nParsing 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.\n\nFormat sample:\n\n```\nwall_0=Wall(1.6857,-4.4625,0.0,4.6798,-4.4474,0.0,2.73,0.0)\ndoor_0=Door(wall_0,3.1734,-4.4550,1.05,1.3852,2.1)\nwindow_0=Window(wall_4,5.6622,-1.0338,1.65,0.6883,1.5)\nbbox_0=Bbox(carpet,-3.009,4.371,-1.401,-1.5708,5.718,6.734,0.109)\n```\n\n**Common `class` values** (use the token as-is; treat unknown values as a generic object):\n\n`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"
]
}
]
}