openapi: 3.0.3 info: title: AHOLO Open API version: 1.0.0 description: >- 本文档为 AHOLO OpenAPI 说明，**侧重世界重建与世界生成**：从图片、视频等资源发起 **3D 高斯溅射（3DGS）世界重建**，或使用文案与图片发起 **世界生成（Spatial Gen）**，并支持按 worldId **查询详情**与**分页列表**等。请在请求头按平台约定携带 `Authorization`（见各接口安全定义）。默认网关地址见 **Servers**。 x-scalar-sdk-installation: - lang: TypeScript description: 从 npm 安装。完整文档：https://labs.aholo3d.cn/api-docs/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-*`。完整文档：https://labs.aholo3d.cn/api-docs/sdk/java source: |- com.manycoreapis aholo-sdk-world 1.3.0 - lang: Python description: Python 3.9+。PyPI `manycore-aholo-sdk-*`。完整文档：https://labs.aholo3d.cn/api-docs/sdk/python source: pip install manycore-aholo-sdk-asset manycore-aholo-sdk-world manycore-aholo-sdk-lux3d servers: - url: https://api.aholo3d.cn description: Aholo 开放平台 HTTPS 入口 tags: - name: Asset description: 获取 OUS token 后，在同一标签下对 globalDomain（COS）发起 ousCos* 直传步骤，再将可访问 URL 用于业务接口。 x-displayName: 资产 - name: World description: 3D 高斯溅射世界重建相关接口 x-displayName: 世界 - name: Lux3D description: 异步图像生成、3D 生成、模型处理、格式导出和任务查询接口。 x-displayName: Lux3D 3D生成 - name: RenderCloudOpenUSDGuide x-displayName: RenderCloud OpenUSD 格式说明 description: > 本条目用于说明 `usdContent` 支持的 OpenUSD/USDA 格式，帮助开发者构造离线渲染和实时渲染请求。 `usdContent` 的传输格式为： ```text usdContent = Base64(UTF-8(USDA 纯文本)) ``` 文件建议以 `#usda 1.0` 开头，编码为 UTF-8。服务端会解析场景中的相机、外部资产引用和渲染设置；未列出的 Prim 类型或属性会被忽略，语法错误会导致任务或会话失败。 ## 使用场景 | 场景 | API | `usdContent` 内容 | 说明 | |------|-----|-------------------|------| | 离线渲染提交 | `POST /rendercloud/v1/jobs` | 完整场景 USDA | 解析相机、Mesh、3DGS、RenderSettings 后发起离线渲染 | | 实时渲染创建 | `POST /rendercloud/v1/streams` | 完整场景 USDA | 解析完整场景并创建实时渲染流 | | 实时渲染增量推送 | `POST /rendercloud/v1/streams/{sessionId}:push` | Patch USDA（`over`） | 区分更新相机、模型、灯光和环境光 | ## 推荐顶层结构 ```usda #usda 1.0 ( defaultPrim = "World" ) def Xform "World" { def Xform "MeshModel1" { ... } def Xform "Cameras" { def Camera "MainCamera" { ... } } def Xform "Lights" { def RectLight "KeyRect" { ... } def SphereLight "FillPoint" { ... } } } def Scope "Render" { def RenderSettings "MainRenderSettings" { custom float3 manycore:environment:giIntensity = (1, 1, 1) } } ``` 支持 `def` 定义完整场景，也支持 `over` 在实时增量推送中覆盖已有 Prim。 ## Stage 元数据 | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | `defaultPrim` | `token` 字符串 | 否 | 默认根 Prim 名称，如 `"World"` | | `doc` | 三引号字符串 | 否 | 文档说明；解析后保留，不参与渲染 | | `upAxis` | `token` 字符串 | 否 | 可选文档元信息；不改变云端渲染坐标轴 | | `metersPerUnit` | 浮点数 | 否 | 可选文档元信息；不改变云端渲染单位 | 云端渲染固定使用 Z-up，且固定按 **1 单位 = 1 毫米** 处理。用户不需要设置 `upAxis` 或 `metersPerUnit`；若携带这两个 Stage 字段，服务端仅将其作为文档元信息读取，不会据此转换坐标或灯光尺寸。 ## Xform 变换容器 `def Xform` 用于包裹模型或相机，并向子 Prim 继承变换矩阵。 | 属性 | USDA 类型 | 必填 | 说明 | |------|-----------|------|------| | `matrix4d xformOp:transform` | `matrix4d` | 否 | 4x4 变换矩阵；有值时应用于子级资产或相机 | | `uniform token[] xformOpOrder` | `token[]` | 否 | 建议填写 `["xformOp:transform"]` | 矩阵采用 USD 行向量约定，平移分量位于第 4 行： ```usda matrix4d xformOp:transform = ( (m00, m01, m02, m03), (m10, m11, m12, m13), (m20, m21, m22, m23), (m30, m31, m32, m33) ) ``` ## 外部资产 ### Mesh ```usda def Mesh "myMesh" ( payload = @manycore:/mesh/{meshId}@ ) { } ``` ### 3D Gaussian Splatting ```usda def ParticleField3DGaussianSplat "MyGaussianSplat" ( payload = @manycore:/mesh/{meshId}@ ) { } ``` `payload` 的 `assetPath` 用于引用已上传资产，`meshId` 取路径最后一段。为保持格式明确且一致，本文所有示例均使用带 target Prim 路径的规范形式：`Mesh` 使用 `@manycore:/mesh/{meshId}@`，3DGS 使用 `@manycore:/mesh/{meshId}@`；不使用裸资产 ID 形式。 ## Camera 完整场景中使用遍历顺序遇到的第一个相机。实时**相机 Patch** 中使用第一个带相机属性的 `over` 节点；该规则不适用于模型、灯光或环境光 Patch。 | 属性 | USDA 类型 | 必填 | 说明 | |------|-----------|------|------| | `token projection` | `token` | 否 | 投影类型，如 `"perspective"` | | `float2 clippingRange` | `(near, far)` | 否 | 近/远裁剪面 | | `float focalLength` | `float` | 否 | 焦距，单位 mm | | `float focusDistance` | `float` | 否 | 对焦距离 | | `float fStop` | `float` | 否 | 光圈 f 值 | | `float horizontalAperture` | `float` | 否 | 水平感光面宽度，单位 mm | | `float verticalAperture` | `float` | 否 | 垂直感光面高度，单位 mm | | `matrix4d xformOp:transform` | `matrix4d` | 否 | 相机位姿 | | `uniform token[] xformOpOrder` | `token[]` | 否 | 建议填写 `["xformOp:transform"]` | 示例： ```usda def Camera "MainCamera" { float2 clippingRange = (0.1, 1000) float focalLength = 28 float fStop = 0 float horizontalAperture = 24.447495 float verticalAperture = 13.7517 token projection = "perspective" matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (0, 0, 8.0, 1) ) uniform token[] xformOpOrder = ["xformOp:transform"] } ``` ## RenderSettings `def RenderSettings` 建议放在 `def Scope "Render"` 下。 | 属性 | USDA 类型 | 必填 | 说明 | |------|-----------|------|------| | `rel camera` | Prim 路径 | 否 | 活动相机路径，如 `` | | `int2 resolution` | `(width, height)` | 离线渲染必填 | 输出分辨率 | 离线渲染分辨率从 `RenderSettings.resolution` 读取，也兼容 Camera 节点上的 `resolution`；宽高必须为正数，且任一边不能超过服务端配置上限，默认上限为 4500 像素。存在多个 `RenderSettings` 时，使用第一个。 ## 灯光和环境光 灯光与环境光可以在创建实时会话时写入完整 USDA，也可以在会话状态为 `ACTIVE` 后通过 `POST /rendercloud/v1/streams/{sessionId}:push` 增量更新。请求中的 `usdContent` 始终使用 `Base64(UTF-8(USDA 纯文本))` 编码。 ### 灯光 当前支持 `RectLight` 矩形面光源和 `SphereLight` 球形点光源。灯光应放在完整场景中稳定且唯一的 Prim 路径下，并保存完整路径；后续更新和删除必须命中同一条路径。灯光的距离和尺寸始终按云端固定的 **1 单位 = 1 毫米、Z-up** 解释，无需设置 `metersPerUnit` 或 `upAxis`。 | Prim / 属性 | 约束 | |-------------|------| | `RectLight` | `inputs:width`、`inputs:height` 必须为正数；支持 `inputs:color`、`inputs:intensity`、`inputs:exposure`、`inputs:specular` 和 `xformOp:transform` | | `SphereLight` | `inputs:radius` 必须为正数；支持 `inputs:color`、`inputs:intensity`、`inputs:exposure`、`inputs:specular` 和 `xformOp:transform` | | `inputs:color` | 线性 RGB；省略时为白色 | | `inputs:intensity` / `inputs:exposure` | 实际亮度为 `intensity × 2^exposure` | | `inputs:normalize` | 可省略或设置为 `false`；设置为 `true` 不支持 | | `xformOp:transform` / `xformOpOrder` | 设置灯光变换时必须同时写入 `uniform token[] xformOpOrder = ["xformOp:transform"]`，否则 Transform 不参与 USD 变换栈 | | `manycore:affectReflections` | `customData` 中的 `0` 或 `1`；省略时为 `1` | | `manycore:doubleFace` | `RectLight` 的 `customData` 布尔值；省略时为 `false` | 当前不支持 `DistantLight`、`DiskLight`、`DomeLight`、Spot/IES/MeshLight、灯光链接、贴图投影、色温，也不支持 `SphereLight` 的非均匀缩放。`inputs:normalize` 可省略或设置为 `false`，但不能设置为 `true`。矩阵继续使用本文约定的行向量格式，平移分量在第 4 行。 ### 环境光 环境光亮度写在当前生效的 `RenderSettings` Prim 上，推荐与相机和分辨率放在同一个 Prim： ```usda custom float3 manycore:environment:giIntensity = (1.25, 1.25, 1.25) ``` `manycore:environment:giIntensity` 是 GI 环境光 RGB 三通道的绝对强度倍率。三个值都必须是可表示为 32 位浮点数的有限正数；普通亮度滑杆应将标量 `v` 转成 `(v, v, v)`。省略该属性表示保留场景默认值，不等价于 `(1, 1, 1)`；该属性也不是灯光颜色，不受 `metersPerUnit`、`upAxis` 或 sRGB/Gamma 影响。 ### Patch 总则 只有会话轮询到 `ACTIVE` 后才允许发送 Patch。更新时使用 `over`，路径必须与初始化场景一致；新增模型或灯光使用 `def` 并提供完整创建字段，删除模型或灯光使用 `manycore:operation:type = "del"`。同一个 session 的相机、模型、灯光和环境光 Patch 应按用户操作顺序串行发送，高频输入应防抖并 flush 最终值。 ## 实时渲染最小初始化示例 以下是一个可读性优先的最小完整场景：包含一个 Mesh、一个相机、一盏矩形面光源和环境光。需要更多资产或灯光时，可在此基础上扩展；它不包含可选的 `upAxis` 或 `metersPerUnit`。 ```usda #usda 1.0 ( defaultPrim = "World" ) def Xform "World" { def Xform "Model" { matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (0, 0, 0, 1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/{meshId}@ ) {} } def Xform "Cameras" { def Camera "MainCamera" { float2 clippingRange = (0.1, 5000) float focalLength = 28 float horizontalAperture = 24.447495 float verticalAperture = 13.7517 token projection = "perspective" matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (0, 0, 8, 1) ) uniform token[] xformOpOrder = ["xformOp:transform"] } } def Xform "Lights" { def RectLight "KeyRect" { color3f inputs:color = (1, 1, 1) float inputs:intensity = 4 float inputs:width = 1200 float inputs:height = 600 float inputs:specular = 1 bool inputs:normalize = false matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (1200, 600, 2400, 1) ) uniform token[] xformOpOrder = ["xformOp:transform"] } } } def Scope "Render" { def RenderSettings "MainRenderSettings" { rel camera = int2 resolution = (1024, 576) custom float3 manycore:environment:giIntensity = (1, 1, 1) } } ``` ## 实时渲染初始化完整示例 下面是包含多个 Mesh、3DGS、相机、灯光和环境光的完整参考场景，不是最小请求体。实际请求时需要将 USDA 文本按 `Base64(UTF-8(USDA 纯文本))` 编码后传入 `usdContent`。示例中的 `payload` 统一使用带 target Prim 路径的规范形式。 ```usda #usda 1.0 ( defaultPrim = "World" ) def Xform "World" { def Xform "MainSplat" { matrix4d xformOp:transform = ( (0.000051545731,0.000085786507,0,0), (-0.000085786507,0.000051545731,0,0), (0,0,0.000100081398,0), (0.174798629761,1.721153564453,0.3,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def ParticleField3DGaussianSplat "SplatModel" ( payload = @manycore:/mesh/YYKIL7BVAJQPYPTUKU888888@ ) { } } def Xform "Model_0_JVAIX5WPTUL4" { matrix4d xformOp:transform = ( (0.001,0,0,0), (0,0.001,0,0), (0,0,0.001,0), (0.18688556,1.6863253,1.321402,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/YYWWKOJVAIX5WPTUL4888888@ ) { } } def Xform "Model_1_ZVAIPWOPTULY" { matrix4d xformOp:transform = ( (0.001,0.000000000073,0,0), (-0.000000000073,0.001,0,0), (0,0,0.001,0), (-1.6171633,0.8850137,0.46721213,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/YRNLYLZVAIPWOPTULY888888@ ) { } } def Xform "Model_2_ZVAXAG6PTUJU" { matrix4d xformOp:transform = ( (-0.00000000008,0.0018392428,0,0), (-0.0018392428,-0.00000000008,0,0), (0,0,0.00015876645,0), (-1.638599,0.9451463,0.0005,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/ZSGMVMZVAXAG6PTUJU888888@ ) { } } def Xform "Model_3_BVAII3SPTUJU" { matrix4d xformOp:transform = ( (-0.00055461276,-0.0007359958,0,0), (0.0007359958,-0.00055461276,0,0), (0,0,0.00092156667,0), (0.06702871,0.49209814,0.32490457,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/YR3NPCBVAII3SPTUJU888888@ ) { } } def Xform "Model_4_RVALFX2PTUJQ" { matrix4d xformOp:transform = ( (0.00083867055,0.00054463905,0,0), (-0.00054463905,0.00083867055,0,0), (0,0,0.001,0), (-0.7005493,0.28526813,0.037392548,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/YWMNBJRVALFX2PTUJQ888888@ ) { } } def Xform "Model_5_RVAIIECPTULA" { matrix4d xformOp:transform = ( (-0.00000000004,0.0009199465,0,0), (-0.0009199465,-0.00000000004,0,0), (0,0,0.0009199465,0), (-3.0077407,0.81905786,0.3764504,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/ZC42U2RVAIIECPTULA888888@ ) { } } def Xform "Model_6_BVAJRHAPTUKQ" { matrix4d xformOp:transform = ( (0.0010743258,0,0,0), (0,0.0010743258,0,0), (0,0,0.0010743258,0), (0.1153041,2.9576484,1.8342776,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/ZDAFHEBVAJRHAPTUKQ888888@ ) { } } def Xform "Model_7_JVAUMCKPTULM" { matrix4d xformOp:transform = ( (-0.000000000048,0.0010972692,0,0), (-0.0010972692,-0.000000000048,0,0), (0,0,0.0010972692,0), (-1.0990643,2.1746306,0.23665573,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/ZS4RG7JVAUMCKPTULM888888@ ) { } } def Xform "Model_8_ZVAX3LMPTUJU" { matrix4d xformOp:transform = ( (0.0009108356,0.00056915325,0,0), (-0.00056915325,0.0009108356,0,0), (0,0,0.0010740377,0), (-3.3463013,2.5292085,0.863,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/ZSBUJIZVAX3LMPTUJU888888@ ) { } } def Xform "Model_9_ZVAJYACPTULU" { matrix4d xformOp:transform = ( (0.0008437305,0,0,0), (0,0.0008437305,0,0), (0,0,0.0008437305,0), (0.12560691,2.9127068,0.46892435,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/ZCCN76ZVAJYACPTULU888888@ ) { } } def Xform "Model_10_JVAIHW6PTULA" { matrix4d xformOp:transform = ( (0.00061403894,0,0,0), (0,0.00061403894,0,0), (0,0,0.00061403894,0), (-1.4365238,3.085212,1.3550343,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/ZG55YXJVAIHW6PTULA888888@ ) { } } def Xform "Model_11_UTDD52GSRTL4" { matrix4d xformOp:transform = ( (0.001,0,0,0), (0,0.0009986295,-0.00005233596,0), (0,0.00005233596,0.0009986295,0), (-0.9053951,3.1488496,1.6107593,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/6DM4O3UTDD52GSRTL4888888@ ) { } } def Xform "Model_12_JVAITAAPTULE" { matrix4d xformOp:transform = ( (0.0011506461,0,0,0), (0,0.0011506461,0,0), (0,0,0.0011506461,0), (-1.6382509,2.5568164,0.444,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/Z65NBFJVAITAAPTULE888888@ ) { } } def Xform "Model_13_JVAIJG2PTULA" { matrix4d xformOp:transform = ( (0.001,0,0,0), (0,0.001,0,0), (0,0,0.001,0), (-1.0495006,3.1262092,1.0833826,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/ZMXLP3JVAIJG2PTULA888888@ ) { } } def Xform "Model_14_JVAVUWOPTULM" { matrix4d xformOp:transform = ( (-0.000000000067,0.0015338801,0,0), (-0.0011504536,-0.00000000005,0,0), (0,0,0.0011504536,0), (-3.763693,2.7723376,1.2795,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/6JVR45JVAVUWOPTULM888888@ ) { } } def Xform "Cameras" { def Camera "MainCamera" { float2 clippingRange = (0.1, 5000) float focalLength = 20.7846 float fStop = 0 float horizontalAperture = 42.6667 float verticalAperture = 24.0000 token projection = "perspective" matrix4d xformOp:transform = ( (0.7333269715309143,0.6797372698783875,-0.01374034397304058,0), (-0.0885528177022934,0.11553312093019485,0.9893485307693481,0), (0.6740845441818237,-0.7242991924285889,0.14491620659828186,0), (0.8263652324676514,-0.030662942677736282,0.8460000157356262,1) ) uniform token[] xformOpOrder = ["xformOp:transform"] } } def Xform "Lights" { def RectLight "KeyRect" ( customData = { int manycore:affectReflections = 1 bool manycore:doubleFace = false } ) { color3f inputs:color = (1.0, 0.95, 0.90) float inputs:intensity = 4.0 float inputs:exposure = 0.0 float inputs:width = 1200 float inputs:height = 600 float inputs:specular = 1 bool inputs:normalize = false matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (1200, 600, 2400, 1) ) uniform token[] xformOpOrder = ["xformOp:transform"] } def SphereLight "FillPoint" { color3f inputs:color = (0.70, 0.80, 1.00) float inputs:intensity = 40.0 float inputs:exposure = -1.0 float inputs:radius = 80 float inputs:specular = 1 bool inputs:normalize = false matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (-500, 900, 1800, 1) ) uniform token[] xformOpOrder = ["xformOp:transform"] } } } def Scope "Render" { def RenderSettings "MainRenderSettings" { rel camera = int2 resolution = (1024, 576) custom float3 manycore:environment:giIntensity = (1.25, 1.25, 1.25) } } ``` ## 实时增量 Patch 实时增量推送不重建完整场景，而是分别通过 Patch 更新相机、模型、灯光和环境光。只有会话状态为 `ACTIVE` 时才能发送；每次 Patch 使用 `over`，并保持与初始化完整 USDA 一致的 Prim 路径。 ### 相机 Patch ```usda #usda 1.0 over "World" { over "Cameras" { over "MainCamera" { token projection = "perspective" float focalLength = 50 float focusDistance = 100 float horizontalAperture = 36.0 float verticalAperture = 24.0 float2 clippingRange = (0.1, 5000.0) matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, -1, 0), (10, 20, 30, 1) ) } } } ``` ### 模型 Patch 模型使用 `Xform` 作为稳定的父 Prim，模型数据可使用 `Mesh` 或 `ParticleField3DGaussianSplat` 的 `payload` 引用已上传资产。模型新增、Transform 修改和删除都必须使用完整且一致的 Prim 路径；父级 `Xform` 必须是完整场景或此前已成功 Patch 的已知节点。 #### 3DGS 模型 **添加 3DGS 模型**：使用 `def`，同时提供模型的 Transform、`xformOpOrder` 和 `payload`。 ```usda over "World" { def Xform "GaussianSplatModel2" { matrix4d xformOp:transform = ( (0.001, 0.0, 0.0, 0.0), (0.0, 0.0, 0.001, 0.0), (0.0, -0.001, 0.0, 0.0), (0.0, 0.0, 0.0, 1.0) ) uniform token[] xformOpOrder = ["xformOp:transform"] def ParticleField3DGaussianSplat "MyGaussianSplat2" ( payload = @manycore:/mesh/YYPZPUETQYRLIPTUKE888888@ ) { } } } ``` **修改 3DGS 模型 Transform**：对已有父 `Xform` 使用 `over`，写入新的完整行向量矩阵；子模型可用空的 `over` 节点明确命中路径。 ```usda over "World" { over "GaussianSplatModel2" { matrix4d xformOp:transform = ( (0.001, 0.0, 0.0, 0.0), (0.0, 0.0, 0.001, 0.0), (0.0, -0.001, 0.0, 0.0), (-2.01571919623, -0.262131040274, 1.279749806075, 1.0) ) uniform token[] xformOpOrder = ["xformOp:transform"] over ParticleField3DGaussianSplat "MyGaussianSplat2" { } } } ``` **删除 3DGS 模型**：在原模型路径下，对 `ParticleField3DGaussianSplat` 添加 `manycore:operation:type = "del"`。不要先修改模型名称或路径再删除。 ```usda over "World" { over "GaussianSplatModel2" { over ParticleField3DGaussianSplat "MyGaussianSplat2" ( customData = { string manycore:operation:type = "del" } ) { } } } ``` #### Mesh 模型 `Mesh` 模型的 Patch 语义与 3DGS 一致，只是 `payload` 的 target Prim 使用 ``。 **添加 Mesh 模型**： ```usda over "World" { def Xform "MeshModel2" { matrix4d xformOp:transform = ( (0.001, 0.0, 0.0, 0.0), (0.0, 0.0, 0.001, 0.0), (0.0, -0.001, 0.0, 0.0), (0.0, 0.0, 0.0, 1.0) ) uniform token[] xformOpOrder = ["xformOp:transform"] def Mesh "Geom" ( payload = @manycore:/mesh/YYPZPUETQYRLIPTUKE888888@ ) { } } } ``` **修改 Mesh 模型 Transform**： ```usda over "World" { over "MeshModel2" { matrix4d xformOp:transform = ( (0.001, 0.0, 0.0, 0.0), (0.0, 0.0, 0.001, 0.0), (0.0, -0.001, 0.0, 0.0), (-2.01571919623, -0.262131040274, 1.279749806075, 1.0) ) uniform token[] xformOpOrder = ["xformOp:transform"] over Mesh "Geom" { } } } ``` **删除 Mesh 模型**： ```usda over "World" { over "MeshModel2" { over Mesh "Geom" ( customData = { string manycore:operation:type = "del" } ) { } } } ``` 模型 Patch 与相机、灯光、环境光 Patch 共用同一个 session 级发送队列；只有服务端返回成功且会话仍为 `ACTIVE` 后，前端才更新本地已提交场景状态。 ### 灯光 Patch 修改灯光时只写发生变化的字段；更新位置、旋转或缩放时写入完整的行向量 `matrix4d xformOp:transform`，并同时写入 `uniform token[] xformOpOrder = ["xformOp:transform"]`。例如修改 `/World/Lights/KeyRect` 的颜色和亮度： ```usda over "World" { over "Lights" { over RectLight "KeyRect" { color3f inputs:color = (1.0, 0.72, 0.50) float inputs:intensity = 8.0 } } } ``` 新增灯光使用 `def` 并填写完整字段；删除已有灯光时使用相同路径和 `manycore:operation:type = "del"`： ```usda over "World" { over "Lights" { def SphereLight "Accent" { color3f inputs:color = (0.2, 0.4, 1.0) float inputs:intensity = 12.0 float inputs:exposure = 0.0 float inputs:radius = 50.0 float inputs:specular = 1 bool inputs:normalize = false matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (300, 400, 500, 1) ) uniform token[] xformOpOrder = ["xformOp:transform"] } over SphereLight "FillPoint" ( customData = { string manycore:operation:type = "del" } ) {} } } ``` ### 环境光 Patch 环境光 Patch 必须命中初始化阶段记录的同一个 `RenderSettings` Prim 路径，推荐显式写出类型： ```usda #usda 1.0 over Scope "Render" { over RenderSettings "MainRenderSettings" { custom float3 manycore:environment:giIntensity = (0.8, 0.8, 0.8) } } ``` 环境光更新使用绝对值覆盖，例如从 `2.0` 更新到 `0.8` 直接发送 `(0.8, 0.8, 0.8)`。不能发送 `0`、负数或 `None`，也不能通过删除属性、删除 `RenderSettings` 或 `manycore:operation:type = "del"` 清除环境光；恢复倍率 1 时显式发送 `(1, 1, 1)`。 ## 已支持 Prim / 属性 | Prim 类型 | 支持 | 关键属性 / 元数据 | |-----------|------|-------------------| | `Xform` | 支持 | `xformOp:transform`, `xformOpOrder`；可作为模型父节点进行 `def` / `over` | | `Mesh` | 支持 | 元数据 `payload`；可通过 `over` 和删除标记移除 | | `ParticleField3DGaussianSplat` | 支持 | 元数据 `payload`；可通过 `over` 和删除标记移除 | | `Camera` | 支持 | 相机参数和位姿 | | `RectLight` | 支持 | `inputs:color`, `inputs:intensity`, `inputs:exposure`, `inputs:width`, `inputs:height`, `inputs:specular`, `xformOp:transform` | | `SphereLight` | 支持 | `inputs:color`, `inputs:intensity`, `inputs:exposure`, `inputs:radius`, `inputs:specular`, `xformOp:transform` | | `RenderSettings` | 支持 | `camera`, `resolution`, `manycore:environment:giIntensity` | | `Scope` | 支持 | 作为层级容器 | | 其他 USD 类型 | 忽略 | 不参与渲染 | ## 限制与常见错误 | 项 | 说明 | |----|------| | **固定单位与坐标轴** | 云端固定按 1 单位 = 1 毫米、Z-up 渲染；不需要设置 `metersPerUnit` 或 `upAxis`，携带时也不会触发坐标或尺寸换算 | | **重要：矩阵约定不一致** | 前端显示使用的矩阵约定可能与云端渲染不同；云端渲染要求 USDA 中模型和相机的 `xformOp:transform` 都按行优先 / 行向量表示，平移分量位于第 4 行 | | 灯光 Transform | 只写 `xformOp:transform` 不会进入 USD 变换栈；必须同时写入 `xformOpOrder` | | 环境光亮度 | `manycore:environment:giIntensity` 的三个值必须是有限正数；不支持用 `0`、删除属性或删除 Prim 清除环境光 | | 不支持的灯光类型 | `DistantLight`、`DiskLight`、`DomeLight`、Spot/IES/MeshLight、灯光链接、贴图投影和色温不参与渲染 | | 非完整 USD | 不支持 `references`、`subLayers`、`variantSets`、材质网络等标准 USD 合成能力 | | 多相机 / 多 RenderSettings | 使用遍历顺序遇到的第一个 | | 未知属性 | 忽略，不报错 | | 语法错误 | 未闭合 `{}`、非法属性值等会导致解析失败 | | 资产不存在 | `payload` 中引用的资产不存在时，渲染可能失败或缺少对应资产 | x-scalar-doc-only: true - name: RenderCloud description: OpenUSD 渲染云接口 x-displayName: 渲染云 - name: SpatialUnderstanding description: 空间理解：用室内点云（.ply）创建异步任务，轮询详情获取 Wall / Door / Window / Bbox 文本结果，或分页查询任务列表。 x-displayName: 空间理解 paths: /asset/v1/token: get: tags: - Asset summary: 获取 OUS 上传凭证 description: > 本接口仅返回上传前置凭证；**真实直传发生在 OUS 的 `globalDomain` 上**（与开放平台网关域名不同），与同标签 **「Upload」** 中的 `ousCosSingleUpload`、`ousCosBlockUploadInit`、`ousCosBlockUploadPart`、`ousCosUploadStatus` 衔接。 **推荐流程：** 1. 调用本接口，取得 `ousToken`、`globalDomain`（示例：`https://ous-cos.kujiale.com`）、`blockSize`。 2. 若文件大小 **≤ `blockSize`**：调用 `ousCosSingleUpload`；若 **> `blockSize`**：依次调用 `ousCosBlockUploadInit` 与多次 `ousCosBlockUploadPart`。 3. 轮询 `ousCosUploadStatus`，直到任务成功并取得 `url`。 4. 将得到的可访问 URL 填入 其他业务接口，比如「创建 3DGS 世界重建任务」的 `resources[].url`。 operationId: getUploadToken responses: '200': description: 成功时响应体为 OUS 上传凭证（`ousToken`、`globalDomain`、`blockSize`），用于在返回的 COS 域名上继续直传或分片上传。 content: application/json: schema: $ref: '#/components/schemas/asset_UploadTokenOuterOpen' examples: success: summary: 获取凭证成功 description: success value: ousToken: globalDomain: https://ous-cos.kujiale.com blockSize: 1048576 '400': description: 参数/业务校验失败（ApiError，`details.metaData.bizCode` 为原业务码） content: application/json: schema: $ref: '#/components/schemas/asset_ApiError' examples: paramsInvalid: summary: 参数校验失败 description: 业务码 10001（PARAMS_INVALID） value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo3d.cn message: Invalid request parameters metaData: bizCode: '10001' '401': description: 未携带或无效的 Authorization，鉴权失败（ApiError） content: application/json: schema: $ref: '#/components/schemas/asset_ApiError' examples: notLoggedIn: summary: 未登录或鉴权失败 description: 业务码 10004（NOT_LOGGED_IN） value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo3d.cn message: Not logged in metaData: bizCode: '10004' security: - AuthorizationHeader: [] x-scalar-order: 5 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createAssetClient } from '@manycore/aholo-sdk-asset'; // SDK 封装 token / 分片 / 轮询，无需手写本接口 const asset = createAssetClient({ region: 'cn' }); const result = await asset.uploadFile('./video.mp4'); console.log(result.url); - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.asset.AssetClient; import com.manycoreapis.sdk.asset.UploadResult; import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; AssetClient asset = AssetClient.create(AholoClientConfig.ofRegion("cn")); UploadResult result = asset.uploadFile(Paths.get("video.mp4")); System.out.println(result.url()); - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_asset import create_asset_client # SDK 封装 token / 分片 / 轮询，无需手写本接口 asset = create_asset_client(region='cn') result = asset.upload_file('./video.mp4') print(result.url) /ous/api/v2/single/upload: post: tags: - Asset summary: OUS 单文件上传（≤ blockSize） description: 当文件字节数 **≤** token 接口返回的 `blockSize` 时使用；详情见 `requestBody` 与 `components.schemas.OusCosSingleUploadForm`。 operationId: ousCosSingleUpload requestBody: description: 单文件上传请求体。 content: multipart/form-data: schema: $ref: '#/components/schemas/asset_OusCosSingleUploadForm' encoding: file: contentType: application/octet-stream required: true responses: '200': description: 成功时 `c` 为 `0`，`d` 含 `taskId`；随后轮询 `GET /ous/api/v2/upload/status`。 content: application/json: schema: $ref: '#/components/schemas/asset_OusV2SingleUploadApiResponse' security: - OusTokenV2: [] servers: - url: https://ous-cos.kujiale.com description: OUS 返回的 `globalDomain`；生产环境常见为该 COS 域名（以 token 接口实际返回为准）。 x-scalar-order: 6 /ous/api/v2/block/upload/init: post: tags: - Asset summary: OUS 分片上传 — 初始化 description: >- 当文件字节数 **>** `blockSize` 时使用。**常用调用**：`POST`，必填参数放在 **URL Query**（无 request body，无需 `Content-Type: application/json`），例如 `…/ous/api/v2/block/upload/init?md5=…&blocks=…&size=…&name=…`。 operationId: ousCosBlockUploadInit parameters: - name: md5 in: query required: true schema: type: string description: 文件 MD5，十六进制小写 example: e99a18c428cb38d5f260853678922e03 - name: blocks in: query required: true schema: type: integer description: 总分片数 format: int64 example: 11 - name: size in: query required: true schema: type: integer description: 文件总字节数 format: int64 example: 5942880 - name: name in: query required: true schema: type: string description: 原始文件名 example: photo.jpg - name: metadata in: query required: false schema: type: string description: 元数据（可选） - name: customPrefix in: query required: false schema: type: string description: 自定义存储前缀（可选） - name: customFilename in: query required: false schema: type: string description: 自定义文件名（可选） responses: '200': description: 成功时 `c` 为 `0`，`d` 含 `taskId`、`lackBlocks`、`progress`、`deduplicated`。 content: application/json: schema: $ref: '#/components/schemas/asset_OusV2BlockInitApiResponse' security: - OusTokenV2: [] servers: - url: https://ous-cos.kujiale.com description: OUS 返回的 `globalDomain`；生产环境常见为该 COS 域名（以 token 接口实际返回为准）。 x-scalar-order: 7 /ous/api/v2/block/upload/part: post: tags: - Asset summary: OUS 分片上传 — 上传单个分片 description: 每个分片调用一次；见 `OusCosBlockUploadPartForm`。 operationId: ousCosBlockUploadPart requestBody: description: 单个分片上传请求体。 content: multipart/form-data: schema: $ref: '#/components/schemas/asset_OusCosBlockUploadPartForm' encoding: file: contentType: application/octet-stream required: true responses: '200': description: 成功时 `c` 为 `0`，`d` 为 `null`。同文件分片并发建议不超过 2。 content: application/json: schema: $ref: '#/components/schemas/asset_OusV2BlockPartApiResponse' security: - OusTokenV2: [] servers: - url: https://ous-cos.kujiale.com description: OUS 返回的 `globalDomain`；生产环境常见为该 COS 域名（以 token 接口实际返回为准）。 x-scalar-order: 8 /ous/api/v2/upload/status: get: tags: - Asset summary: OUS — 查询上传状态（轮询） description: >- 轮询当前上传任务；`d` 在单文件与分片任务下结构不同（见 response schema 中 `d` 的 oneOf）。请求仅携带 `ous-token-v2`，无 body。建议轮询间隔 ≥200ms、总时长约 5s 量级。 operationId: ousCosUploadStatus responses: '200': description: 成功时 `c` 为 `0`；`d` 为单文件或分片任务状态/结果（`status=5` 为成功终态，详见内嵌字段说明与文档状态表）。 content: application/json: schema: $ref: '#/components/schemas/asset_OusV2UploadStatusApiResponse' security: - OusTokenV2: [] servers: - url: https://ous-cos.kujiale.com description: OUS 返回的 `globalDomain`；生产环境常见为该 COS 域名（以 token 接口实际返回为准）。 x-scalar-order: 9 /world/v1/reconstructions: post: tags: - World summary: 创建 3DGS 世界重建任务 description: >- 异步创建一条 3DGS 世界重建任务。受理成功后返回 `WorldAsyncOperation`，仅含 `worldId`，与「查询世界详情」路径 `{worldId}` 一致。**资源格式**：image：.jpg / .jpeg / .png / .webp；video：.mp4 / .mov；insv：.insv。 **输入规则**：若 `resources` 中含有图片类资源（`type=image` 或省略 `type`），则图片类条数须 **至少 20 条**；仅使用视频时请设 `type=video`，Insta360 全景视频请设 `type=insv`（均不触发「至少 20 张图」限制）。 operationId: createWorld parameters: - name: x-source in: header required: false schema: type: string requestBody: description: 创建任务请求体。含图时须满足图片张数与「CreateWorldRequest」中说明一致。 content: application/json: schema: $ref: '#/components/schemas/world_CreateWorldRequest' examples: createWorldWithVideo: description: '单视频 + 室内场景；`type: video`，支持 .mp4 / .mov' value: name: 客厅重建 resources: - url: https://cdn.example.com/input/room-001.mp4 type: video taskQuality: high scene: space createWorldWithInsv: description: 'Insta360 全景视频；`type: insv`，支持 .insv' value: name: 全景客厅重建 resources: - url: https://cdn.example.com/input/room-001.insv type: insv taskQuality: high scene: space createWorldWithImages: description: 多图：须 ≥20 条 image（或省略 type 按图计），支持 .jpg / .jpeg / .png / .webp；此处为结构示意 value: name: 客厅重建 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 required: true responses: '200': description: 受理成功：返回 `WorldAsyncOperation`，含 `worldId`。 content: application/json: schema: $ref: '#/components/schemas/world_WorldAsyncOperation' examples: success: summary: 创建受理成功 description: success value: worldId: A1b2C3d4E5 '400': description: 参数/请求体校验失败、积分不足等（ApiError，`details.metaData.bizCode` 为原业务码） content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: paramsInvalid: summary: 参数/请求体校验失败 description: 业务码 10001（PARAMS_INVALID） value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo3d.cn message: Invalid request parameters metaData: bizCode: '10001' insufficientCredits: summary: 积分不足以完成任务 description: 业务码 11003；若当前环境创建接口未扣积分则可能不出现 value: code: 400 message: insufficient credits to complete task status: FAILED_PRECONDITION details: reason: BIZ_11003 domain: api.aholo3d.cn message: insufficient credits to complete task metaData: bizCode: '11003' taskMattingError: summary: 任务域其它错误（示例） description: 业务码 11004，与本创建链路未必出现 value: code: 400 message: matting error status: FAILED_PRECONDITION details: reason: BIZ_11004 domain: api.aholo3d.cn message: matting error metaData: bizCode: '11004' '401': description: 未携带或无效的 Authorization，鉴权失败（ApiError） content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: notLoggedIn: summary: 未登录或鉴权失败 description: 业务码 10004（NOT_LOGGED_IN） value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo3d.cn message: Not logged in metaData: bizCode: '10004' '429': description: 全局任务并发或限流（ApiError） content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: taskGlobalRateLimit: summary: 全局任务并发达上限 description: 业务码 11001 value: code: 429 message: task global rate limit status: RESOURCE_EXHAUSTED details: reason: BIZ_11001 domain: api.aholo3d.cn message: task global rate limit metaData: bizCode: '11001' security: - AuthorizationHeader: [] x-scalar-order: 10 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createWorldClient } from '@manycore/aholo-sdk-world'; const world = createWorldClient({ region: 'cn' }); const { worldId } = await world.reconstructions.create({ name: '客厅', resources: [{ url: 'https://cdn.example.com/room.mp4', type: 'video' }], taskQuality: 'normal', scene: 'model', }); const detail = await world.waitFor(worldId); console.log(detail.assets?.splats?.urls?.plyPath); - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.world.WorldClient; import com.manycoreapis.sdk.world.model.ReconstructionCreateParams; import com.manycoreapis.sdk.world.model.GenerationCreateParams; import com.manycoreapis.sdk.world.model.WorldListParams; import com.manycoreapis.sdk.world.model.WorldAsyncOperation; import com.manycoreapis.sdk.world.model.WorldDetail; import com.manycoreapis.sdk.world.model.WorldPagedList; WorldClient world = WorldClient.create(AholoClientConfig.ofRegion("cn")); WorldAsyncOperation op = world.reconstructions().create( ReconstructionCreateParams.builder() .name("客厅") .addResource("https://cdn.example.com/room.mp4", "video") .taskQuality("normal") .scene("model") .build()); WorldDetail detail = world.waitFor(op.worldId()); - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_world import create_world_client world = create_world_client(region='cn') op = world.reconstructions.create( name='客厅', resources=[{'url': 'https://cdn.example.com/room.mp4', 'type': 'video'}], task_quality='normal', scene='model', ) detail = world.wait_for(op['worldId']) print(detail.get('assets', {}).get('splats', {}).get('urls', {}).get('plyPath')) /world/v1/generations: post: tags: - World summary: 创建 3DGS 世界生成任务 description: >- 异步创建一条3DGS 世界生成任务（Spatial Gen）。当前 **室内空间** 场景效果更成熟、更稳定，建议优先用于室内。也允许提交 **非室内** 类文案或素材，但非室内生成仍处于 **Beta**，质量与一致性可能明显弱于室内，请按需评估风险。受理成功后返回 `WorldAsyncOperation`（仅含 `worldId`）。支持纯文案、单张图片或图文组合。若 `resources` 中含图片，最多允许 1 张（image：.jpg / .jpeg / .png / .webp。）。 operationId: generateWorld parameters: - name: x-source in: header required: false schema: type: string requestBody: description: 生成世界请求体。支持纯文案、单张图片或图文组合。至多 1 张图片（image：.jpg / .jpeg / .png / .webp。）。 content: application/json: schema: $ref: '#/components/schemas/world_GenerateWorldRequest' examples: generateWorldRequest: summary: 图文组合示例 description: generateWorldRequest value: name: 客厅生成 cover: https://cdn.example.com/cover/gen-cover.jpg prompt: 现代简约风格客厅 resources: - url: https://cdn.example.com/input/room.jpg type: image required: true responses: '200': description: 受理成功：返回 `WorldAsyncOperation`，含 `worldId`。 content: application/json: schema: $ref: '#/components/schemas/world_WorldAsyncOperation' examples: success: summary: 创建受理成功 description: success value: worldId: B2c3D4e5F6 '400': description: 参数/请求体校验失败等业务错误（ApiError） content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: paramsInvalid: summary: 参数/请求体校验失败 description: 业务码 10001（PARAMS_INVALID） value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo3d.cn message: Invalid request parameters metaData: bizCode: '10001' '401': description: 未携带或无效的 Authorization，鉴权失败（ApiError） content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: notLoggedIn: summary: 未登录或鉴权失败 description: 业务码 10004（NOT_LOGGED_IN） value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo3d.cn message: Not logged in metaData: bizCode: '10004' security: - AuthorizationHeader: [] x-scalar-order: 15 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createWorldClient } from '@manycore/aholo-sdk-world'; const world = createWorldClient({ region: 'cn' }); const { worldId } = await world.generations.create({ name: '森林小屋', prompt: '森林中的现代风格小木屋', }); const detail = await world.waitFor(worldId); - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.world.WorldClient; import com.manycoreapis.sdk.world.model.ReconstructionCreateParams; import com.manycoreapis.sdk.world.model.GenerationCreateParams; import com.manycoreapis.sdk.world.model.WorldListParams; import com.manycoreapis.sdk.world.model.WorldAsyncOperation; import com.manycoreapis.sdk.world.model.WorldDetail; import com.manycoreapis.sdk.world.model.WorldPagedList; WorldClient world = WorldClient.create(AholoClientConfig.ofRegion("cn")); WorldAsyncOperation op = world.generations().create( GenerationCreateParams.builder() .name("森林小屋") .prompt("森林中的现代风格小木屋") .build()); WorldDetail detail = world.waitFor(op.worldId()); - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_world import create_world_client world = create_world_client(region='cn') op = world.generations.create( name='森林小屋', prompt='森林中的现代风格小木屋', ) detail = world.wait_for(op['worldId']) /world/v1/{worldId}: get: tags: - World summary: 查询世界详情 description: >- 根据世界 id 查询详情。重建成功且产出可用时，响应中包含 splat（ply/spz）等重建产物的下载地址；若已完成 LOD 后处理，`assets.splats.urls.lodMetaPath` 将包含 LOD 分块元数据文件的下载地址。AI 生成（Spatial Gen）世界在全景图产出后，`assets.imagery.panoUrl` 返回全景图下载地址。 operationId: getWorldDetail parameters: - name: worldId in: path description: 世界 id（与创建接口成功响应 `WorldAsyncOperation.worldId` 一致） required: true schema: type: string example: A1b2C3d4E5 responses: '200': description: 成功时响应体为世界详情对象。 content: application/json: schema: $ref: '#/components/schemas/world_WorldDetail' examples: reconstructionWorldDetail: summary: 3D 重建世界详情 description: 重建成功，含 splats 与坐标系元数据，无 imagery。 value: worldId: A1b2C3d4E5 name: 客厅重建 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 生成世界详情 description: 生成成功，含全景图 imagery.panoUrl 与 splats。 value: worldId: B2c3D4e5F6 name: 现代简约客厅 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: 路径参数校验失败等业务错误（ApiError） content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: paramsInvalid: summary: 路径参数校验失败 description: 业务码 10001 value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo3d.cn message: Invalid request parameters metaData: bizCode: '10001' '401': description: 未携带或无效的 Authorization，鉴权失败（ApiError） content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: notLoggedIn: summary: 未登录或鉴权失败 description: 业务码 10004（NOT_LOGGED_IN） value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo3d.cn message: Not logged in metaData: bizCode: '10004' '403': description: 无访问权限（ApiError） content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: noPermission: summary: 无权限查看 description: 业务码 12003 value: code: 403 message: no permission status: PERMISSION_DENIED details: reason: BIZ_12003 domain: api.aholo3d.cn message: no permission metaData: bizCode: '12003' '404': description: 世界不存在（ApiError） content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: projectNotExist: summary: 世界（项目）不存在 description: 业务码 12001 value: code: 404 message: project not exist status: NOT_FOUND details: reason: BIZ_12001 domain: api.aholo3d.cn message: project not exist metaData: bizCode: '12001' security: - AuthorizationHeader: [] x-scalar-order: 20 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createWorldClient } from '@manycore/aholo-sdk-world'; const world = createWorldClient({ region: 'cn' }); const detail = await world.retrieve('A1b2C3d4E5'); console.log(detail.status); - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.world.WorldClient; import com.manycoreapis.sdk.world.model.ReconstructionCreateParams; import com.manycoreapis.sdk.world.model.GenerationCreateParams; import com.manycoreapis.sdk.world.model.WorldListParams; import com.manycoreapis.sdk.world.model.WorldAsyncOperation; import com.manycoreapis.sdk.world.model.WorldDetail; import com.manycoreapis.sdk.world.model.WorldPagedList; WorldClient world = WorldClient.create(AholoClientConfig.ofRegion("cn")); WorldDetail detail = world.retrieve("A1b2C3d4E5"); detail.status().ifPresent(System.out::println); - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_world import create_world_client world = create_world_client(region='cn') detail = world.retrieve('A1b2C3d4E5') print(detail.get('status')) /world/v1/list: post: tags: - World summary: 分页查询我的世界列表 description: 分页查询当前账号下的 3DGS 世界列表。 operationId: getMyWorldList requestBody: description: 分页与筛选条件。 content: application/json: schema: $ref: '#/components/schemas/world_WorldListQueryRequest' examples: listWorldRequest: description: 示例：第一页、每页 20、按运行中与成功筛选 value: pageNum: 0 pageSize: 20 statusList: - RUNNING - SUCCEEDED required: true responses: '200': description: 成功时响应体为分页列表对象（含 `pageNum`、`pageSize`、列表项等）。 content: application/json: schema: $ref: '#/components/schemas/world_WorldPagedList' examples: success: summary: 查询成功 description: success value: pageNum: 0 pageSize: 20 count: 1 totalCount: 1 hasMore: false result: - worldId: A1b2C3d4E5 name: 客厅重建 cover: https://cdn.example.com/cover/world-001.jpg scene: space createTime: 1699339916000 updateTime: 1699340120000 status: RUNNING progress: 0.45 '400': description: 分页参数等校验失败（ApiError） content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: paramsInvalid: summary: 请求体/参数校验失败 description: 业务码 10001 value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo3d.cn message: Invalid request parameters metaData: bizCode: '10001' '401': description: 未携带或无效的 Authorization，鉴权失败（ApiError） content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: notLoggedIn: summary: 未登录或鉴权失败 description: 业务码 10004（NOT_LOGGED_IN） value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo3d.cn message: Not logged in metaData: bizCode: '10004' security: - AuthorizationHeader: [] x-scalar-order: 30 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createWorldClient } from '@manycore/aholo-sdk-world'; const world = createWorldClient({ region: 'cn' }); const page = await world.list({ pageNum: 1, pageSize: 20 }); page.result?.forEach((w) => console.log(w.worldId, w.status)); - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.world.WorldClient; import com.manycoreapis.sdk.world.model.ReconstructionCreateParams; import com.manycoreapis.sdk.world.model.GenerationCreateParams; import com.manycoreapis.sdk.world.model.WorldListParams; import com.manycoreapis.sdk.world.model.WorldAsyncOperation; import com.manycoreapis.sdk.world.model.WorldDetail; import com.manycoreapis.sdk.world.model.WorldPagedList; WorldClient world = WorldClient.create(AholoClientConfig.ofRegion("cn")); WorldPagedList page = world.list( WorldListParams.builder().pageNum(1).pageSize(20).build()); page.result().ifPresent(items -> items.forEach(w -> System.out.println(w.worldId() + " " + w.status()))); - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_world import create_world_client world = create_world_client(region='cn') page = world.list(page_num=1, page_size=20) for w in page.get('result', []): print(w.get('worldId'), w.get('status')) /lux3d/v1/generate/multimodal-to-image/task/create: post: tags: - Lux3D summary: 创建多模态单图生成任务 description: | 根据图片、文字提示词或图文组合创建异步单图生成任务，img 和 prompt 至少提供一个。请求成功后返回任务 ID（taskid），可通过任务查询接口获取状态和结果图片 URL。 operationId: createMultimodalToImageTask requestBody: description: 多模态单图生成请求体，img 和 prompt 至少提供一个。 required: true content: application/json: schema: $ref: '#/components/schemas/lux3d_MultimodalToImageRequest' examples: promptOnly: summary: 纯文字生成单图 value: prompt: 一把现代简约浅色原木餐椅，纯白背景 imageOnly: summary: 使用参考图生成单图 value: img: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg imageAndPrompt: summary: 按提示词修改参考图 value: img: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg prompt: 把椅子改成浅色原木材质，保持造型和视角 responses: '200': description: 成功时返回任务 ID。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: 任务创建成功 value: f: null c: '0' m: '' d: 1256174 invalidInput: summary: img 和 prompt 均未提供 value: f: null c: '-1' m: img or prompt is required d: null concurrencyLimit: summary: 生成任务并发已达上限 value: f: null c: GENERATION_CONCURRENCY_LIMIT_EXCEEDED m: 当前已有进行中的生成任务，请等待完成后再试 d: null '401': description: 未携带或无效的 Authorization，鉴权失败 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: 服务端内部错误 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] x-scalar-order: 1 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'cn' }); const taskId = await lux3d.multimodalToImage.create({ prompt: '木椅产品图，白色背景', img: 'https://example.com/object.jpg', }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("cn")); long taskId = lux3d.multimodalToImage().create( MultimodalToImageCreateParams.builder() .prompt("木椅产品图，白色背景") .img("https://example.com/object.jpg") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='cn') task_id = lux3d.multimodal_to_image.create( prompt='木椅产品图，白色背景', img='https://example.com/object.jpg', ) result = lux3d.tasks.wait_for(task_id) /lux3d/v1/generate/image-to-four-view/task/create: post: tags: - Lux3D summary: 创建多模态四视图任务 description: > 根据图片、文字提示词或图文组合生成物体的四个视角，img 和 prompt 至少提供一个。请求成功后返回任务 ID（taskid），可通过任务查询接口获取状态和结果。成功结果包含四张图片 URL，顺序为 FRONT_THREE_QUARTER、OPPOSITE_THREE_QUARTER、SIDE、BACK。 operationId: createImageToFourViewTask requestBody: description: 多模态四视图任务请求体。 required: true content: application/json: schema: $ref: '#/components/schemas/lux3d_ImageToFourViewRequest' examples: promptOnly: summary: 纯文字生成四视图 value: prompt: 一把现代简约浅色原木餐椅 imageOnly: summary: 使用单图生成四视图 value: img: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg imageAndPrompt: summary: 使用参考图和提示词生成四视图 value: img: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg prompt: 把椅子改成浅色原木材质，保持造型和视角 responses: '200': description: 成功时返回任务 ID。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: 任务创建成功 value: f: null c: '0' m: '' d: 1256173 invalidInput: summary: img 和 prompt 均未提供 value: f: null c: '-1' m: img or prompt is required d: null concurrencyLimit: summary: 生成任务并发已达上限 value: f: null c: GENERATION_CONCURRENCY_LIMIT_EXCEEDED m: 当前已有进行中的生成任务，请等待完成后再试 d: null '401': description: 未携带或无效的 Authorization，鉴权失败 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: 服务端内部错误 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] x-scalar-order: 2 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'cn' }); const taskId = await lux3d.imageToFourView.create({ img: 'https://example.com/object.jpg', prompt: '产品四视图，白色背景', }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("cn")); long taskId = lux3d.imageToFourView().create( ImageToFourViewCreateParams.builder() .img("https://example.com/object.jpg") .prompt("产品四视图，白色背景") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='cn') task_id = lux3d.image_to_four_view.create( img='https://example.com/object.jpg', prompt='产品四视图，白色背景', ) result = lux3d.tasks.wait_for(task_id) /lux3d/v1/generate/img-to-3d/task/create: post: tags: - Lux3D summary: 创建图生 3D 任务 description: | 根据一张或多张图片创建异步 3D 生成任务，可选择 G1 或 G1-Turbo。省略 version 时使用默认版本。请求成功后返回任务 ID（taskid），可通过任务查询接口获取状态和结果。 operationId: createImgTo3dTask requestBody: description: 图生 3D 任务请求体。 content: application/json: schema: $ref: '#/components/schemas/lux3d_ImgTo3dRequest' examples: createTaskG1: summary: 创建图生 3D 任务（推荐：G1） value: img: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg version: G1 faceCount: 300000 outputFormat: - zip - glb createTaskG1TurboMultiImage: summary: 创建多图输入的图生 3D 任务（推荐：G1-Turbo） 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: 成功时返回任务ID。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: 任务创建成功 value: f: null c: '0' m: '' d: 1256173 concurrencyLimit: summary: 生成任务并发已达上限 value: f: null c: GENERATION_CONCURRENCY_LIMIT_EXCEEDED m: 当前已有进行中的生成任务，请等待完成后再试 d: null '401': description: 未携带或无效的 Authorization，鉴权失败 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: 服务端内部错误 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] x-scalar-order: 3 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'cn' }); const taskId = await lux3d.imgTo3d.create({ img: 'https://example.com/object.jpg', version: 'G1', }); const result = await lux3d.tasks.waitFor(taskId); console.log(result.outputs[0]?.content); - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("cn")); long taskId = lux3d.imgTo3d().create( ImgTo3dCreateParams.builder() .img("https://example.com/object.jpg") .version("G1") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); result.outputs().forEach(o -> o.content().ifPresent(System.out::println)); - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='cn') task_id = lux3d.img_to_3d.create(img='https://example.com/object.jpg', version='G1') result = lux3d.tasks.wait_for(task_id) print(result['outputs'][0]['content']) /lux3d/v1/generate/text-to-3d/task/create: post: tags: - Lux3D summary: 创建文生 3D 任务 description: | 根据文本和一张可选参考图片创建异步 3D 生成任务，可选择 G1 或 G1-Turbo。省略 version 时使用默认版本。请求成功后返回任务 ID（taskid），可通过任务查询接口获取状态和结果。 operationId: createTextTo3dTask requestBody: description: 文生 3D 任务请求体。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TextTo3dRequest' examples: textOnlyG1: summary: 纯文本生成（推荐：G1） value: prompt: 生成一个高质量的3D木椅模型 style: photorealistic version: G1 faceCount: 300000 outputFormat: - zip - glb textWithImage: summary: 文本+参考图生成（推荐：G1） value: prompt: 生成一个高质量的3D木椅模型 style: photorealistic img: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg version: G1 textG1ZipGlb: summary: G1 文生 3D（ZIP + GLB） value: prompt: 生成一把现代木质餐椅 style: photorealistic version: G1 outputFormat: - zip - glb faceCount: 300000 textG1TurboPly: summary: G1-Turbo 文生 3D（仅 PLY） value: prompt: 生成一把现代木质餐椅 style: photorealistic version: G1-Turbo outputFormat: - ply required: true responses: '200': description: 成功时返回任务ID。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: 任务创建成功 value: f: null c: '0' m: '' d: 1256173 concurrencyLimit: summary: 生成任务并发已达上限 value: f: null c: GENERATION_CONCURRENCY_LIMIT_EXCEEDED m: 当前已有进行中的生成任务，请等待完成后再试 d: null '401': description: 未携带或无效的 Authorization，鉴权失败 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: 服务端内部错误 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] x-scalar-order: 4 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'cn' }); const taskId = await lux3d.textTo3d.create({ prompt: '带雕花腿的木椅', version: 'G1', }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("cn")); long taskId = lux3d.textTo3d().create( TextTo3dCreateParams.builder() .prompt("带雕花腿的木椅") .version("G1") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='cn') task_id = lux3d.text_to_3d.create(prompt='带雕花腿的木椅', version='G1') result = lux3d.tasks.wait_for(task_id) /lux3d/v1/generate/material-transfer/task/create: post: tags: - Lux3D summary: 创建模型材质重绘任务 description: | 根据材质参考图片和 GLB 模型创建异步材质重绘任务。请求成功后返回任务 ID（taskid），可通过任务查询接口获取状态和结果。 operationId: createMaterialTransferTask requestBody: description: 模型材质重绘任务请求体。 content: application/json: schema: $ref: '#/components/schemas/lux3d_MaterialTransferRequest' examples: createTaskDefault: summary: 创建材质重绘任务 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: 成功时返回任务ID。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: 任务创建成功 value: f: null c: '0' m: '' d: 1256173 concurrencyLimit: summary: 生成任务并发已达上限 value: f: null c: GENERATION_CONCURRENCY_LIMIT_EXCEEDED m: 当前已有进行中的生成任务，请等待完成后再试 d: null '401': description: 未携带或无效的 Authorization，鉴权失败 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: 服务端内部错误 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] x-scalar-order: 5 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'cn' }); const taskId = await lux3d.materialTransfer.create({ img: 'https://example.com/material.jpg', meshUrl: 'https://example.com/model.glb', version: 'v3.0-standard', }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("cn")); long taskId = lux3d.materialTransfer().create( MaterialTransferCreateParams.builder() .img("https://example.com/material.jpg") .meshUrl("https://example.com/model.glb") .version("v3.0-standard") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='cn') task_id = lux3d.material_transfer.create( img='https://example.com/material.jpg', mesh_url='https://example.com/model.glb', version='v3.0-standard', ) result = lux3d.tasks.wait_for(task_id) /lux3d/v1/part-split/task/create: post: tags: - Lux3D summary: 创建部件拆分任务 description: | 根据一个可由服务端访问的 GLB 模型 URL 创建异步部件拆分任务。请求成功后返回任务 ID（taskid），可通过任务查询接口获取状态和包含拆分结果的 GLB 文件 URL。 若当前账号已有同类任务进行中，本次请求不会创建任务，请稍后重试。 operationId: createPartSplitTask requestBody: description: 部件拆分任务请求体。 required: true content: application/json: schema: $ref: '#/components/schemas/lux3d_PartSplitRequest' examples: createTask: summary: 创建部件拆分任务 value: glbUrl: https://qhstaticssl.kujiale.com/model/gltfbinary/1790144390549/14B82261CD6DF53FA6B406240E20CB2C.glb responses: '200': description: 成功时返回任务 ID。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: 任务创建成功 value: f: null c: '0' m: '' d: 1256174 temporarilyUnavailable: summary: 暂时无法创建任务 value: f: null c: GENERATION_CONCURRENCY_LIMIT_EXCEEDED m: 服务繁忙，请稍候再试 d: null '401': description: 未携带或无效的 Authorization，鉴权失败 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: 服务端内部错误 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] x-scalar-order: 6 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'cn' }); const taskId = await lux3d.partSplit.create({ glbUrl: 'https://example.com/model.glb', }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("cn")); long taskId = lux3d.partSplit().create( PartSplitCreateParams.builder() .glbUrl("https://example.com/model.glb") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='cn') task_id = lux3d.part_split.create(glb_url='https://example.com/model.glb') result = lux3d.tasks.wait_for(task_id) /lux3d/v1/multi-format-export/task/create: post: tags: - Lux3D summary: 创建多格式导出任务 description: | 根据 ZIP 或 GLB 模型 URL 创建异步格式导出任务，可选择一个或多个支持的目标格式。请求成功后返回任务 ID（taskid），可通过任务查询接口获取状态和结果。 operationId: createMultiFormatExportTask requestBody: description: 多格式导出任务请求体。 content: application/json: schema: $ref: '#/components/schemas/lux3d_MultiFormatExportRequest' examples: createTaskDefault: summary: 创建多格式导出任务（glb 输入，导出 usdz） value: modelUrl: https://qhstaticssl.kujiale.com/application/octetstream/1784776896628/model.glb outputFormat: - usdz createTaskWithPrintFormats: summary: 创建多格式导出任务（glb 输入，导出 STL 和 3MF） value: modelUrl: https://qhstaticssl.kujiale.com/application/octetstream/1784776896628/model.glb outputFormat: - stl - 3mf required: true responses: '200': description: 成功时返回任务ID。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: 任务创建成功 value: f: null c: '0' m: '' d: 1256173 glbNoFormat: summary: glb 输入未选择任何导出格式 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: 未携带或无效的 Authorization，鉴权失败 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: 服务端内部错误 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] x-scalar-order: 7 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'cn' }); const taskId = await lux3d.multiFormatExport.create({ modelUrl: 'https://example.com/model.glb', outputFormat: ['usdz', 'obj_zip', 'stl'], }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("cn")); long taskId = lux3d.multiFormatExport().create( MultiFormatExportCreateParams.builder() .modelUrl("https://example.com/model.glb") .outputFormat(java.util.Arrays.asList("usdz", "obj_zip", "stl")) .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='cn') task_id = lux3d.multi_format_export.create( model_url='https://example.com/model.glb', output_format=['usdz', 'obj_zip', 'stl'], ) result = lux3d.tasks.wait_for(task_id) /lux3d/v1/articulation-animation/task/create: post: tags: - Lux3D summary: 创建模型关节化与动画任务 description: | 根据 GLB 模型 URL 和运动提示词创建异步关节化与动画任务。请求成功后返回任务 ID（taskid），可通过任务查询接口获取状态和结果文件 URL。 operationId: createArticulationAnimationTask requestBody: description: 模型关节化与动画请求。glbUrl 和 prompt 均必填，不接受其他字段。 required: true content: application/json: schema: $ref: '#/components/schemas/lux3d_ArticulationAnimationRequest' examples: glbAndPrompt: summary: GLB 模型与运动提示词 value: glbUrl: https://assets.aholo3d.cn/examples/cubely/joint-motion/target-model.glb prompt: 保持底座固定，为盖子添加旋转关节，让盖子缓慢打开和闭合。 responses: '200': description: 成功时返回任务 ID。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: 任务创建成功 value: f: null c: '0' m: '' d: 3725821 invalidInput: summary: GLB 地址无效或提示词为空 value: f: null c: '-1' m: glbUrl must be an HTTP(S) URL and prompt is required d: null concurrencyLimit: summary: 生成任务并发已达上限 value: f: null c: GENERATION_CONCURRENCY_LIMIT_EXCEEDED m: 当前已有进行中的生成任务，请等待完成后再试 d: null '400': description: JSON 格式错误或包含不支持的请求字段。 '401': description: 未携带或无效的 Authorization，鉴权失败 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: 服务端内部错误 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] x-scalar-order: 8 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'cn' }); const taskId = await lux3d.articulationAnimation.create({ glbUrl: 'https://example.com/model.glb', prompt: '保持底座固定，让盖子缓慢打开和闭合', }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("cn")); long taskId = lux3d.articulationAnimation().create( ArticulationAnimationCreateParams.builder() .glbUrl("https://example.com/model.glb") .prompt("保持底座固定，让盖子缓慢打开和闭合") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='cn') task_id = lux3d.articulation_animation.create( glb_url='https://example.com/model.glb', prompt='保持底座固定，让盖子缓慢打开和闭合', ) result = lux3d.tasks.wait_for(task_id) /lux3d/v1/animations/rig/task/create: post: tags: - Lux3D summary: 创建数字人自动绑骨任务 description: | 根据数字人 GLB 模型创建异步自动绑骨任务。请求成功后返回任务 ID（taskid），可通过任务查询接口获取状态和已绑骨 GLB 文件 URL。 operationId: createHumanoidAutoRigTask requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/lux3d_HumanoidAutoRigRequest' example: modelUrl: https://example.com/model.glb responses: '200': description: 请求成功（c="0"）后，d 返回任务 ID。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' example: f: null c: '0' m: '' d: 3742500 security: - AuthorizationHeader: [] x-scalar-order: 9 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'cn' }); const taskId = await lux3d.humanoidAutoRig.create({ modelUrl: 'https://example.com/human.glb', }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("cn")); long taskId = lux3d.humanoidAutoRig().create( HumanoidAutoRigCreateParams.builder() .modelUrl("https://example.com/human.glb") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='cn') task_id = lux3d.humanoid_auto_rig.create(model_url='https://example.com/human.glb') result = lux3d.tasks.wait_for(task_id) /lux3d/v1/animations/retarget/task/create: post: tags: - Lux3D summary: 创建数字人动画重定向任务 description: | 根据已绑骨模型和所选动作创建异步动画重定向任务，支持逐动作输出或合并输出，可选择 GLB 或 FBX 格式。请求成功后返回任务 ID（taskid），可通过任务查询接口获取状态和动作结果。 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: 请求成功（c="0"）后，d 返回任务 ID。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' example: f: null c: '0' m: '' d: 3742500 security: - AuthorizationHeader: [] x-scalar-order: 10 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'cn' }); const taskId = await lux3d.humanoidAnimationRetarget.create({ rigModelUrl: 'https://example.com/rig.glb', animationIds: ['Idle_Loop', 'Walk_Loop'], outFormat: 'glb', }); const result = await lux3d.tasks.waitFor(taskId); - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("cn")); long taskId = lux3d.humanoidAnimationRetarget().create( HumanoidAnimationRetargetCreateParams.builder() .rigModelUrl("https://example.com/rig.glb") .animationIds(java.util.Arrays.asList("Idle_Loop", "Walk_Loop")) .outFormat("glb") .build()); TaskResult result = lux3d.tasks().waitFor(taskId); - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='cn') task_id = lux3d.humanoid_animation_retarget.create( rig_model_url='https://example.com/rig.glb', animation_ids=['Idle_Loop', 'Walk_Loop'], out_format='glb', ) result = lux3d.tasks.wait_for(task_id) /lux3d/v1/generate/task/get: get: tags: - Lux3D summary: 查询生成任务 description: > 根据任务 ID 查询任务状态和结果，仅支持查询当前认证账号创建的任务。结果 URL 有效期为 2 小时。 `c="0"` 表示查询成功，任务是否完成由 `d.status` 判断：0-初始化，1-运行中，3-成功，4-失败，6-已取消。状态为 0 或 1 时继续查询，任务完成后从 `d.outputs` 读取结果；运行中的任务也可能返回部分已生成结果。 不同任务的结果格式如下。表中的 URL 或 JSON 字符串均位于输出项的 `content` 字段。 | 任务类型 | 结果格式 | | --- | --- | | 多模态单图生成 | 一个结果图片 URL。 | | 多模态四视图 | 包含四张图片 URL 的 JSON 数组字符串，顺序为 FRONT_THREE_QUARTER、OPPOSITE_THREE_QUARTER、SIDE、BACK。 | | G1 图生 / 文生 3D | 按 ZIP、GLB 顺序返回文件 URL；请求 PLY 时额外返回 PLY。 | | G1-Turbo 图生 / 文生 3D | 返回指定格式的文件 URL；未指定格式或传空数组时返回 ZIP。 | | 模型材质重绘 | 按 ZIP、GLB、USDZ、OBJ ZIP、FBX ZIP 顺序返回文件 URL。 | | 多格式导出 | 按 ZIP、GLB、USDZ、OBJ ZIP、FBX ZIP、STL、3MF 顺序返回文件 URL。 | | 部件拆分 | 一个包含拆分结果的 GLB 文件 URL。 | | 模型关节化与动画 | `d.outputs[0].content` 为结果文件 URL，文件格式以实际结果为准，不固定为 ZIP。 | | 数字人自动绑骨 | 已绑骨 GLB 文件 URL；失败时可能返回包含 `error` 的 JSON 字符串。 | | 数字人动画重定向 | 包含 `actions` 的 JSON 字符串，列出各动作的结果 URL 或错误信息。 | 未请求的可选格式可能返回 `NOT_REQUESTED`，该值不是文件 URL。对于 JSON 字符串结果，需要解析 `content` 后再读取其中的字段。 operationId: getTask parameters: - name: taskid in: query description: 任务ID required: true schema: type: integer format: int64 example: 1389513 responses: '200': description: 成功时返回任务状态和结果。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskQueryResponse' examples: humanoidRigSuccess: summary: 数字人绑骨成功 value: f: null c: '0' m: '' d: taskId: 3742500 status: 3 outputs: - content: https://example.com/rig.glb humanoidRigFailure: summary: 模型不适合自动绑骨 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 动作生成成功 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: 所有动作失败 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 动作交付成功 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: 任务进行中 value: f: null c: '0' m: '' d: taskId: 1389513 status: 1 successMaterialTransferAllFormats: summary: 材质重绘成功（全部格式） 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: 材质重绘成功（ZIP、GLB、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: 多格式导出成功（全部格式） 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 成功（ZIP、GLB） 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 成功（ZIP、GLB、PLY） 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 成功（仅 PLY） value: f: null c: '0' m: '' d: taskId: 1389517 outputs: - content: https://cdn.example.com/output/result.ply status: 3 successMultimodalToImage: summary: 多模态单图生成成功 value: f: null c: '0' m: '' d: taskId: 2696732 outputs: - content: https://cdn.example.com/multimodal-to-image/result.png status: 3 successArticulationAnimationZIP: summary: 关节化与动画成功（ZIP 示例） value: f: null c: '0' m: '' d: taskId: 3725821 outputs: - content: https://cdn.example.com/articulation-animation/result.zip status: 3 successArticulationAnimationGLB: summary: 关节化与动画成功（GLB 示例） value: f: null c: '0' m: '' d: taskId: 3725821 outputs: - content: https://cdn.example.com/articulation-animation/result.glb status: 3 successImageToFourView: summary: 多模态四视图生成成功 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: 部件拆分成功 value: f: null c: '0' m: '' d: taskId: 2696734 outputs: - content: https://qhsmodel.kujiale.com/glbPartsReconstructResult/NKZXG2IKTIHXGAABAAAAABQ8.glb status: 3 failed: summary: 任务失败 value: f: null c: '0' m: '' d: taskId: 1389513 status: 4 '401': description: 未携带或无效的 Authorization，鉴权失败 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskQueryResponse' '500': description: 服务端内部错误 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskQueryResponse' security: - AuthorizationHeader: [] x-scalar-order: 11 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'cn' }); const result = await lux3d.tasks.retrieve(taskId); console.log(result.status, result.outputs); // 或 await lux3d.tasks.waitFor(taskId) 轮询至成功 - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("cn")); TaskResult result = lux3d.tasks().retrieve(taskId); System.out.println(result.status()); // or lux3d.tasks().waitFor(taskId) 轮询至成功 - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='cn') result = lux3d.tasks.retrieve(task_id) print(result.get('status'), result.get('outputs')) # 或 lux3d.tasks.wait_for(task_id) 轮询至成功 /lux3d/v1/generate/task/list: get: tags: - Lux3D summary: 分页查询生成记录 description: | 分页查询当前认证账号创建的任务，可按状态和创建时间筛选。 operationId: listTasks parameters: - name: page in: query description: 页码，从 1 开始 schema: type: integer minimum: 1 default: 1 - name: pagesize in: query description: 每页数量，范围 1-100 schema: type: integer minimum: 1 maximum: 100 default: 20 - name: status in: query description: 用于筛选的任务状态：0-初始化，1-运行中，3-成功，4-失败。省略时查询全部状态，结果中仍可能出现已取消状态 6。 schema: type: integer enum: - 0 - 1 - 3 - 4 - name: starttime in: query description: 创建时间起点，包含边界；Unix 毫秒时间戳 schema: type: integer format: int64 minimum: 0 - name: endtime in: query description: 创建时间终点，不包含边界；Unix 毫秒时间戳 schema: type: integer format: int64 minimum: 0 responses: '200': description: 返回生成记录分页数据。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskListResponse' examples: withData: summary: 有数据 value: f: null c: '0' m: '' d: items: - taskId: 2667998 status: 3 created: 1786591762000 lastModified: 1786592088000 total: 1 page: 1 pageSize: 20 noData: summary: 无数据 value: f: null c: '0' m: '' d: items: [] total: 0 page: 1 pageSize: 20 '401': description: 未携带或无效的 Authorization，鉴权失败 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskListResponse' '500': description: 服务端内部错误 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskListResponse' security: - AuthorizationHeader: [] x-scalar-order: 12 x-codeSamples: - lang: TypeScript label: Aholo SDK（TypeScript） source: |- import { createLux3dClient } from '@manycore/aholo-sdk-lux3d'; const lux3d = createLux3dClient({ region: 'cn' }); const page = await lux3d.tasks.list({ page: 1, pageSize: 20, status: 3 }); page.items.forEach((task) => console.log(task.taskId, task.status)); - lang: Java label: Aholo SDK（Java） source: |- import com.manycoreapis.sdk.core.AholoClientConfig; import java.nio.file.Paths; import com.manycoreapis.sdk.lux3d.Lux3dClient; import com.manycoreapis.sdk.lux3d.model.ImageToFourViewCreateParams; import com.manycoreapis.sdk.lux3d.model.MultimodalToImageCreateParams; import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams; import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams; import com.manycoreapis.sdk.lux3d.model.ArticulationAnimationCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAnimationRetargetCreateParams; import com.manycoreapis.sdk.lux3d.model.HumanoidAutoRigCreateParams; import com.manycoreapis.sdk.lux3d.model.MultiFormatExportCreateParams; import com.manycoreapis.sdk.lux3d.model.PartSplitCreateParams; import com.manycoreapis.sdk.lux3d.model.TaskListParams; import com.manycoreapis.sdk.lux3d.model.TaskPagedList; import com.manycoreapis.sdk.lux3d.model.TaskResult; Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("cn")); TaskPagedList page = lux3d.tasks().list( TaskListParams.builder().page(1).pageSize(20).status(3).build()); page.items().forEach(task -> System.out.println(task.taskId() + " " + task.status())); - lang: Python label: Aholo SDK（Python） source: |- from manycore.aholo_sdk_lux3d import create_lux3d_client lux3d = create_lux3d_client(region='cn') page = lux3d.tasks.list(page=1, page_size=20, status=3) for task in page['items']: print(task['taskId'], task['status']) /rendercloud/v1/jobs: post: tags: - RenderCloud summary: 提交或轮询 OpenUSD 离线渲染任务 description: | 提交 OpenUSD 离线渲染任务或轮询任务状态。 ## 提交模式 当请求中 `operationId` 为空时，提交新任务。需要提供 `requestId` 和 Base64 编码后的 `usdContent`。出图分辨率从 OpenUSD `RenderSettings.resolution` 读取，也兼容 Camera 节点上的 `resolution`；宽高必须为正数，且任一边不能超过 服务端配置上限，默认上限为 4500 像素。 服务端返回 HTTP 202 + `{operationId, done:false}`，`operationId` 即任务 ID。 `requestId` 由调用方生成，用于请求追踪和记录；服务端对同一用户同一 `requestId` 做 1 分钟幂等保护。 若同一用户在 1 分钟内重复提交相同 `requestId`，接口返回 409 `ALREADY_EXISTS`。 ## 轮询模式 当请求中 `operationId` 非空时，轮询该任务状态。轮询仍调用同一个 POST 端点。 - 处理中：`done=false` - 完成：`done=true + result.taskId/resultUrl` - 失败：`done=true + error` ## 渲染约束 该接口不接收渲染模板类型等服务端参数。服务端会按 OpenUSD 内容和分辨率选择固定离线渲染链路。 ## REST 响应状态 | HTTP 状态码 | 场景 | 响应说明 | |-----------|------|---------| | `202` | 提交模式 | 任务已提交，返回 `operationId` 用于后续轮询 | | `200` | 轮询模式 | 返回当前 `Operation` 状态；完成时包含 `resultUrl` | | `400` | 参数错误 | 缺少 `requestId`、`usdContent`、OpenUSD 分辨率缺失或非法，Base64 非法，或 OpenUSD 解析失败 | | `404` | 资源不存在 | `operationId` 对应任务不存在 | | `409` | 重复请求 | 同一用户同一 `requestId` 在 1 分钟内重复提交 | | `429` | 请求限流 | 用户维度离线渲染频率超过限制 | | `500` | 服务异常 | 任务创建、转换或渲染链路异常 | operationId: runRenderCloudOfflineJob requestBody: description: 离线渲染提交或轮询请求体。提交时传 `requestId`、`usdContent`；轮询时仅传 `operationId`。 required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/rendercloud_OfflineRenderSubmitRequest' - $ref: '#/components/schemas/rendercloud_OperationPollRequest' examples: submit: summary: 提交离线渲染任务 description: 使用 OpenUSD 内容创建离线渲染任务，分辨率从 OpenUSD resolution 读取。 value: requestId: render-req-20260515-0001 usdContent: I3VzZGEgMS4wCg== poll: summary: 轮询离线渲染结果 description: 使用提交响应返回的 `operationId` 查询任务状态或结果。 value: operationId: '1305220918472257536' responses: '200': description: 当前离线渲染操作状态。 content: application/+json: schema: oneOf: - $ref: '#/components/schemas/rendercloud_OfflineRenderProcessingOperation' - $ref: '#/components/schemas/rendercloud_OfflineRenderSuccessOperation' - $ref: '#/components/schemas/rendercloud_OperationError' examples: processing: summary: 任务处理中 description: 离线渲染任务仍在处理中。 value: operationId: '1305220918472257536' metaData: null done: false result: null error: null success: summary: 渲染成功 description: 离线渲染任务完成，返回结果图片地址。 value: operationId: '1305220918472257536' metaData: null done: true result: taskId: '1305220918472257536' resultUrl: https://example.com/render/result.png error: null failed: summary: 渲染失败 description: 离线渲染任务失败，返回错误信息。 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: 离线渲染任务已受理，仍在处理中。 content: application/+json: schema: $ref: '#/components/schemas/rendercloud_OfflineRenderProcessingOperation' examples: processing: summary: 任务处理中 description: 离线渲染任务已创建，但尚未完成。 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 /rendercloud/v1/streams: post: tags: - RenderCloud summary: 创建或轮询 OpenUSD 实时渲染流 description: | 创建新的实时渲染会话或轮询已有会话状态。 ## 提交模式 当请求中 `operationId` 为空时，创建新会话。需要提供 `requestId` 和 `usdContent`。 可选的 `settings.autoEnhanceAI` 用于启用 AI 增强。未传或传 `false` 时不启用。 返回 HTTP 202 + `{operationId, done:false}`。返回的 `operationId` 即 `sessionId`。 ## 轮询模式 当请求中 `operationId` 非空时，轮询该会话的状态。轮询间隔建议 2s，超时 120s。 当 `status` 为 `ACTIVE` 时，返回的 `result` 中包含 `host`、`nodeId`、`streamId`、`token` 四个字段， 用于建立 WebSocket Streaming 连接。 ## REST 响应状态 | HTTP 状态码 | 场景 | 响应说明 | |-----------|------|---------| | `202` | 提交模式 | 会话创建中，返回 `operationId` 用于后续轮询 | | `200` | 轮询模式 | 返回当前 `Operation` 状态；处理中为 `done=false`，完成为 `done=true + result`，失败为 `done=true + error` | | `400` | 参数错误 | 请求体缺少必要字段或字段无效 | | `404` | 资源不存在 | `operationId` 或会话不存在 | | `429` | 请求限流 | 请求频率超过限制 | | `500` | 服务异常 | 服务端内部错误 | ## WebSocket Streaming 连接协议 ### 连接 URL ``` wss://{host}/streaming/ws/session?nid={encodeURIComponent(nodeId)}&token={encodeURIComponent(token)} ``` 创建 WebSocket 时必须设置 `ws.binaryType = 'blob'`，否则图片无法以 Blob 接收。 ### 握手协议 WebSocket `onopen` 触发后立即发送： ```json {"type":3,"slaveInit":{"masterStreamingId":"{streamId}","receiveImage":true}} ``` | 字段 | 值 | 说明 | |------|-----|------| | type | 固定 `3` | 标识 slave 初始化消息 | | slaveInit.masterStreamingId | `{streamId}` | 来自本接口返回的 streamId | | slaveInit.receiveImage | 固定 `true` | 接收渲染图片 | ### 服务端消息（Server -> Client） **类型 A：JSON 状态消息（`typeof event.data === 'string'`）** 消息结构： ```json {"code":"0","desc":"初始化成功","streamId":"...","timestamp":0,"queueInfo":{"queueSize":0,"currentQueuePosition":0}} ``` 状态码： | code | 含义 | 连接状态变更 | |------|------|-------------| | `"0"` | 初始化成功 | 进入 Success，渲染就绪 | | `"1000"` | 节点满载 | 进入 Error | | `"1001"` | 初始化失败 | 进入 Error | | `"1003"` | Slave 超限 | 进入 SlaveExceeded | | `"2001"` | 引擎渲染错误 | 状态不变，仅触发渲染失败回调，连接仍存活 | | `"2002"` | 引擎进程错误 | 状态不变，仅触发渲染失败回调，连接仍存活 | `2001` / `2002` 是渲染级错误，连接仍存活。不修改连接状态。 **类型 B：二进制图片消息（`event.data instanceof Blob`）** Blob 为 JPEG 格式。使用 `FileReader.readAsDataURL(blob)` 转换为 base64 Data URL 后设置 `` src。 ### 连接生命周期 | 状态 | 触发条件 | |------|---------| | Closed | 未连接 / 已断开 | | BeforeConnection | `new WebSocket(url)` 已创建 | | Booting | `onopen` 已触发，握手已发送 | | Queue | 排队中，服务端推送 | | Success | code=`0`，渲染就绪 | | Error | code=`1000` / `1001` 等 | | Sleep | 长时间无操作休眠 | | RenderStart | 渲染开始 | | EquityDone | 快速出图完成 | | SlaveClosed | 服务端关闭，close code=`4003` | | SlaveExceeded | code=`1003` | | KESceneFinished | KE 场景完成 | ### 关闭连接 | close code | 来源 | 含义 | |-----------|------|------| | `4003` | 服务端 | 服务端关闭所有 slave 连接 | | 其他 | - | 一般关闭 / 网络异常 | 关闭 WebSocket 后需另行调用 DELETE 接口结束服务端会话。 ### 常见陷阱 1. 未设置 `ws.binaryType = 'blob'`：必须设置，否则图片不是 Blob。 2. `2001` / `2002` 被当成连接断开：这两个状态仅表示渲染失败回调，不改连接状态。 3. 先 REST 后 WS 关闭：应先 `ws.close()`，再调用 DELETE API。 4. 图片 Blob 无异常处理：`FileReader` 建议使用 Promise + try/catch。 5. URI 参数未编码：`nodeId` 和 `token` 需要使用 `encodeURIComponent` 编码。 operationId: createRenderCloudRealtimeStream requestBody: description: 实时渲染流创建或轮询请求体。创建时传 `requestId`、`usdContent`，可选传 `settings`（当前支持 `autoEnhanceAI`）；轮询时仅传 `operationId`。 required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/rendercloud_RealtimeSessionSubmitRequest' - $ref: '#/components/schemas/rendercloud_OperationPollRequest' examples: submit: summary: 创建实时渲染流 description: 使用 OpenUSD 内容创建启用 AI 增强的渲染流。 value: requestId: stream-req-20260515-0001 usdContent: I3VzZGEgMS4wCg== settings: autoEnhanceAI: true poll: summary: 轮询实时渲染流创建结果 description: 使用创建响应返回的 `operationId` 查询实时渲染流状态。 value: operationId: '1305220918472257536' responses: '200': description: 会话轮询结果（status=ACTIVE 时 result 包含 WebSocket 连接参数）。 content: application/+json: schema: oneOf: - $ref: '#/components/schemas/rendercloud_RealtimeSessionProcessingOperation' - $ref: '#/components/schemas/rendercloud_RealtimeSessionSuccessOperation' - $ref: '#/components/schemas/rendercloud_OperationError' examples: processing: summary: 创建处理中 description: 实时渲染流仍在初始化。 value: operationId: '1305220918472257536' metaData: null done: false result: null error: null success: summary: 创建成功 description: 实时渲染流已就绪，返回连接所需参数。 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: 创建失败 description: 实时渲染流初始化失败，返回错误信息。 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: 会话创建中（提交模式，返回 operationId 用于后续轮询）。 content: application/+json: schema: $ref: '#/components/schemas/rendercloud_RealtimeSessionProcessingOperation' examples: processing: summary: 会话创建中 description: 提交模式返回的异步操作，`operationId` 即 `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 /rendercloud/v1/streams/{sessionId}:push: post: tags: - RenderCloud summary: 推送实时渲染流增量 OpenUSD 内容 description: | 对已建立的实时渲染会话进行增量场景更新。 该接口用于在 WebSocket Streaming 会话就绪后，向服务端推送增量 OpenUSD 内容。增量内容可分别描述相机、模型、灯光或环境光 Patch；服务端会将其转换为渲染操作并下发到实时渲染链路。具体 USDA 写法见 `RenderCloud OpenUSD 格式说明`。 ## 调用要求 - `sessionId` 必须来自 `/rendercloud/v1/streams` 创建成功后的 `operationId`。 - 会话状态必须为 `ACTIVE`，否则更新会被拒绝。 - `requestId` 由调用方生成，用于幂等和请求记录。 - `usdContent` 为 Base64 编码后的增量 OpenUSD 内容。 ## REST 响应状态 | HTTP 状态码 | 场景 | 响应说明 | |-----------|------|---------| | `200` | 更新成功 | 返回会话 ID 和当前会话状态 | | `400` | 参数错误 | `requestId` 或 `usdContent` 缺失，或请求体非法 | | `404` | 资源不存在 | `sessionId` 对应会话不存在 | | `429` | 请求限流 | 用户维度实时渲染请求频率超过限制 | | `500` | 服务异常 | 会话非 ACTIVE、转发失败或增量更新被渲染链路拒绝 | operationId: pushRenderCloudRealtimeStreamUpdate parameters: - $ref: '#/components/parameters/rendercloud_SessionId' requestBody: description: 实时渲染流增量更新请求体。`usdContent` 为相机、模型、灯光或环境光的 Patch USDA。 required: true content: application/json: schema: $ref: '#/components/schemas/rendercloud_RealtimeSessionUpdateRequest' examples: update: summary: 推送增量内容 description: 向已创建的实时渲染流推送相机、模型、灯光或环境光的 Patch OpenUSD 内容。 value: requestId: stream-update-20260515-0001 usdContent: I3VzZGEgMS4wCg== responses: '200': description: 增量内容推送成功。 content: application/+json: schema: $ref: '#/components/schemas/rendercloud_RealtimeSessionUpdateResponse' examples: success: summary: 更新成功 description: 会话保持 ACTIVE，增量内容已下发到实时渲染链路。 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 /rendercloud/v1/streams/{sessionId}: delete: tags: - RenderCloud summary: 关闭实时渲染流 description: | 关闭指定的实时渲染会话并释放服务端资源。 客户端关闭实时渲染时建议先关闭 WebSocket，再调用本接口结束服务端会话。 服务端会释放该实时渲染会话相关资源。 ## REST 响应状态 | HTTP 状态码 | 场景 | 响应说明 | |-----------|------|---------| | `200` | 关闭完成 | 返回 `closed=true` 表示服务端找到并关闭了会话；`closed=false` 表示会话已不存在或已被清理 | | `404` | 资源不存在 | 转发到持有会话的节点时，该节点返回会话不存在 | | `429` | 请求限流 | 用户维度实时渲染请求频率超过限制 | | `500` | 服务异常 | 转发失败或服务端内部错误 | operationId: closeRenderCloudRealtimeStream parameters: - $ref: '#/components/parameters/rendercloud_SessionId' responses: '200': description: 实时渲染流已关闭。 content: application/+json: schema: $ref: '#/components/schemas/rendercloud_RealtimeSessionCloseResponse' examples: closed: summary: 关闭成功 description: 服务端找到并关闭了会话。 value: sessionId: '1305220918472257536' closed: true alreadyGone: summary: 会话已不存在 description: 会话已经被关闭、超时清理或不在当前节点。 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 /rendercloud/v1/mesh-upload-process/task/create: post: tags: - RenderCloud summary: 创建3D解析并入库任务 description: | 创建3D解析并入库任务，用于将原始 3D文件 URL 进行解析处理。 通过 `originMeshUrl` 指定原始 3D 文件 URL，可选字段 `fastUpload` 用于启用快速上传，默认 `false`。 当 `fastUpload` 为 `true` 且文件为 GLB 格式时，使用快速上传流程；未传或为 `false` 时使用普通上传流程。 ## REST 响应状态 | HTTP 状态码 | 场景 | 响应说明 | |-----------|------|---------| | `200` | 任务创建成功 | 返回任务 ID | | `400` | 参数错误 | `originMeshUrl` 缺失或无效 | | `500` | 服务异常 | 任务创建或处理异常 | operationId: createMeshUploadAndProcessTask requestBody: description: Mesh 上传解析任务请求体。 required: true content: application/json: schema: $ref: '#/components/schemas/rendercloud_MeshUploadProcessRequest' examples: submit: summary: 创建 Mesh 上传解析任务 description: 提交原始 Mesh URL，使用普通上传流程；fastUpload 也可省略，默认为 false。 value: originMeshUrl: https://example.com/mesh/original.glb fastUpload: false fastSubmit: summary: 创建 GLB 快速上传任务 description: 提交原始 GLB 文件 URL，并启用快速上传。 value: originMeshUrl: https://example.com/mesh/original.glb fastUpload: true responses: '200': description: Mesh 上传解析任务创建成功。 content: application/json: schema: $ref: '#/components/schemas/rendercloud_TaskCreateResponse' examples: success: summary: 任务创建成功 description: 返回任务 ID 用于后续查询。 value: success: true data: 1272794 errorMsg: null '400': description: 请求参数无效。 content: application/json: schema: $ref: '#/components/schemas/rendercloud_CommonErrorResponse' examples: invalidArgument: summary: 参数无效 description: originMeshUrl 缺失或无效。 value: success: false data: null errorMsg: originMeshUrl 不能为空 '500': description: 服务内部错误。 content: application/json: schema: $ref: '#/components/schemas/rendercloud_CommonErrorResponse' examples: internalError: summary: 服务异常 description: 任务创建或处理异常。 value: success: false data: null errorMsg: 系统错误 x-scalar-order: 1 /rendercloud/v1/mesh-upload-process/task/get: get: tags: - RenderCloud summary: 查询 3D解析并入库 任务状态 description: | 查询指定的 3D解析并入库 任务状态和结果。 该接口用于查询任务执行状态和结果。查询时会剔除一些不应该给用户看的数据， 并对输出数据进行包装处理。 任务状态：`0`=初始化，`1`=进行中，`3`=成功，`4`=失败 ## 调用要求 - `taskid` 必须来自创建任务接口返回的任务 ID ## REST 响应状态 | HTTP 状态码 | 场景 | 响应说明 | |-----------|------|---------| | `200` | 查询成功 | 返回任务详情 | | `400` | 参数错误 | `taskid` 缺失或无效 | | `404` | 任务不存在 | 指定任务 ID 不存在 | | `500` | 服务异常 | 查询异常 | operationId: getRenderCloudInstanceInAholo parameters: - name: taskid in: query required: true description: 任务 ID。 schema: type: integer format: int64 responses: '200': description: 任务查询成功。 content: application/json: schema: $ref: '#/components/schemas/rendercloud_TaskQueryResponse' examples: processing: summary: 任务处理中 description: 任务正在执行中。 value: success: true data: taskId: 1272794 status: 1 outputs: null errorMsg: null success: summary: 任务完成 description: 任务执行完成，返回处理结果。 value: success: true data: taskId: 1272794 status: 3 outputs: - content: YYZN2MZVAIQLEPTULM888888 sourceReferId: '607583273' errorMsg: null '400': description: 请求参数无效。 content: application/json: schema: $ref: '#/components/schemas/rendercloud_CommonErrorResponse' examples: invalidArgument: summary: 参数无效 description: taskid 缺失或无效。 value: success: false data: null errorMsg: taskid 不能为空 '404': description: 任务不存在。 content: application/json: schema: $ref: '#/components/schemas/rendercloud_CommonErrorResponse' examples: notFound: summary: 任务不存在 description: 指定任务 ID 不存在。 value: success: false data: null errorMsg: 任务不存在 '500': description: 服务内部错误。 content: application/json: schema: $ref: '#/components/schemas/rendercloud_CommonErrorResponse' examples: internalError: summary: 服务异常 description: 查询异常。 value: success: false data: null errorMsg: 系统错误 x-scalar-order: 2 /spatial-understanding/v1/tasks: post: tags: - SpatialUnderstanding summary: 创建空间理解任务 description: >- 异步创建一条空间理解任务：从室内点云中识别墙、门、窗与物体 3D bbox。`inputFileUrl` 须为 Asset 上传得到的 `.ply` 文件 URL。点云坐标系为米、右手系、Z-up；未对齐时请传 `transformationMatrix`（列优先，平移在第 4 列）。受理成功即扣减积分，并返回 `taskId`（与「查询任务详情」路径参数一致）。成功后详情中的 `result.resultSslUrl` 为 DSL 文本，需自行下载解析。 operationId: createSpatialUnderstandingTask requestBody: description: 创建任务请求体。`inputFileUrl` 必填，须为 Asset 上传得到的室内 `.ply` URL；`transformationMatrix` 可选，用于将点云对齐到米制、右手系、Z-up。 content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_CreateSpatialUnderstandingTaskRequest' examples: createWithoutMatrix: summary: 仅传点云文件，不做坐标变换 description: createWithoutMatrix value: inputFileUrl: https://holo-cos.aholo3d.cn/resource/openapi/xxx.ply createWithMatrix: summary: 附带 4×4 变换矩阵（列优先，含旋转与平移） 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: 受理成功：返回 `taskId`，用于查询任务详情。 content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_SpatialUnderstandingTaskAsyncOperation' examples: success: summary: 创建受理成功 description: success value: taskId: A1b2C3d4E5 '400': description: 参数校验失败、点云文件 URL 无效、变换矩阵格式非法、或积分不足（`details.metaData.bizCode` 为业务码） content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_ApiError' examples: paramsInvalid: summary: 请求体校验失败（如 inputFileUrl 为空） description: 业务码 10001 value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo3d.cn message: Invalid request parameters metaData: bizCode: '10001' invalidInputUrl: summary: inputFileUrl 无效或不是 .ply description: 业务码 13001，须改用 Asset 上传接口返回的 `.ply` URL 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.aholo3d.cn message: invalid file url, please upload a .ply file via the Asset module APIs metaData: bizCode: '13001' invalidTransformationMatrix: summary: 变换矩阵格式非法 description: 业务码 13002，须为 4 行 4 列合法数字 value: code: 400 message: invalid transformation matrix, expect a 4x4 numeric array status: INVALID_ARGUMENT details: reason: BIZ_13002 domain: api.aholo3d.cn message: invalid transformation matrix, expect a 4x4 numeric array metaData: bizCode: '13002' insufficientCredits: summary: 积分不足以完成任务 description: 业务码 24002，积分不足 value: code: 400 message: insufficient credits status: FAILED_PRECONDITION details: reason: BIZ_24002 domain: api.aholo3d.cn message: insufficient credits metaData: bizCode: '24002' '401': description: 未携带或无效的 Authorization content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_ApiError' examples: notLoggedIn: summary: 未登录或鉴权失败 description: 业务码 10004 value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo3d.cn message: Not logged in metaData: bizCode: '10004' security: - AuthorizationHeader: [] x-scalar-order: 10 /spatial-understanding/v1/tasks/{taskId}: get: tags: - SpatialUnderstanding summary: 查询空间理解任务详情 description: >- 根据任务 id 查询当前账号下的任务详情。`PENDING` / `RUNNING` 表示尚未完成，请继续轮询。`SUCCEEDED` 时响应包含 `result.resultSslUrl`（DSL 文本，含 Wall / Door / Window / Bbox，需自行下载解析）。`FAILED` / `TIMEOUT` 时响应包含 `errorCode`、`errorMessage`。 operationId: getSpatialUnderstandingTaskDetail parameters: - name: taskId in: path description: 任务 id（与创建接口成功响应 `taskId` 一致） required: true schema: minLength: 1 type: string example: A1b2C3d4E5 responses: '200': description: 任务详情。 content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_SpatialUnderstandingTask' examples: pending: summary: 排队中，尚未产出结果 description: pending value: taskId: A1b2C3d4E5 status: PENDING modelVersion: spatiallm-pointcloud-1.2-20260910 createTime: 1699339916000 updateTime: 1699339916000 succeeded: summary: 已完成，含结果地址 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: 失败，含错误码与详情 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: 未携带或无效的 Authorization content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_ApiError' examples: notLoggedIn: summary: 未登录或鉴权失败 description: 业务码 10004 value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo3d.cn message: Not logged in metaData: bizCode: '10004' '404': description: 任务不存在，或无权访问该任务 content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_ApiError' examples: taskNotFound: summary: 任务不存在 description: 业务码 13003 value: code: 404 message: spatial understanding task not found status: NOT_FOUND details: reason: BIZ_13003 domain: api.aholo3d.cn message: spatial understanding task not found metaData: bizCode: '13003' security: - AuthorizationHeader: [] x-scalar-order: 20 /spatial-understanding/v1/tasks/list: post: tags: - SpatialUnderstanding summary: 分页查询我的空间理解任务列表 description: 分页查询当前账号下的空间理解任务，支持按状态过滤。`pageNum` 从 1 起（`0` 与 `1` 均视为第一页）；`pageSize` 未传或为 0 时按 20 条计，最大 100。 operationId: getMySpatialUnderstandingTaskList requestBody: description: 分页与筛选条件。 content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_SpatialUnderstandingTaskListQueryRequest' examples: listTaskRequest: description: 示例：第一页、每页 20、按运行中与成功筛选 value: pageNum: 1 pageSize: 20 statusList: - RUNNING - SUCCEEDED required: true responses: '200': description: 分页列表，含 `pageNum`、`pageSize` 与当前页任务。 content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_SpatialUnderstandingTaskPagedList' examples: success: summary: 查询成功 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: 分页参数校验失败 content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_ApiError' examples: paramsInvalid: summary: 请求体/分页参数校验失败 description: 业务码 10001，如 pageSize 超出 [0, 100] value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo3d.cn message: Invalid request parameters metaData: bizCode: '10001' '401': description: 未携带或无效的 Authorization content: application/json: schema: $ref: '#/components/schemas/spatialunderstanding_ApiError' examples: notLoggedIn: summary: 未登录或鉴权失败 description: 业务码 10004 value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo3d.cn message: Not logged in metaData: bizCode: '10004' security: - AuthorizationHeader: [] x-scalar-order: 30 components: schemas: asset_UploadTokenOuterOpen: type: object properties: ousToken: type: string description: '上传 token。后续对 OUS 域名的上传/分片等请求需在 HTTP Header 中携带：`ous-token-v2: `' example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... globalDomain: type: string description: OUS 全局域名（不含路径）。后续上传、分片等 HTTP 请求发往该主机 example: https://ous-cos.kujiale.com blockSize: type: integer description: 分片阈值（字节）。文件大于该值时需按文档进行分片上传 format: int64 example: 1048576 description: >- OUS 上传凭证：获取后用于在 `globalDomain`（如 `https://ous-cos.kujiale.com`）上直传，请求头携带 `ous-token-v2`；完整步骤见同一份 OpenAPI 中「Upload」标签下的 `ousCos*` 操作。 asset_ApiError: required: - code - details - message - status type: object properties: code: type: integer description: HTTP状态码 format: int32 example: 403 message: type: string description: 面向开发者的错误消息（英文），用户可见的本地化消息请使用localizedMessage字段 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错误响应对象，包含完整的错误信息、状态码和帮助信息 asset_Code: type: string description: REST API标准状态码，符合Google API设计规范，用于统一的错误码表示 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: 错误原因标识符，使用大写蛇形命名法（UPPER_SNAKE_CASE），最多63个字符 example: RESOURCE_NOT_FOUND message: type: string description: 针对此错误的人类可读说明，提供具体的错误上下文 nullable: true example: The requested design with ID 12345 does not exist domain: type: string description: 错误域，通常是生成错误的服务名称 nullable: true example: restapi.qunhe.com metaData: type: object additionalProperties: type: string description: 错误的附加元数据，键值对格式，键最多64个字符，符合模式 /[a-zA-Z0-9-_]/ nullable: true example: '{"instanceLimitPerRequest":"100","currentInstanceCount":"150"}' description: 错误的附加元数据，键值对格式，键最多64个字符，符合模式 /[a-zA-Z0-9-_]/ nullable: true example: instanceLimitPerRequest: '100' currentInstanceCount: '150' description: 错误详情对象，提供错误的详细上下文信息，包括原因、域和元数据 asset_Help: required: - desc - url type: object properties: desc: type: string description: 链接内容的描述，说明此帮助文档的用途 example: 如何解决权限拒绝错误 url: type: string description: 帮助文档的URL链接 example: https://docs.example.com/errors/permission-denied description: 帮助信息对象，提供解决错误的文档链接和说明 nullable: true asset_LocalizedMessage: required: - locale - message type: object properties: locale: type: string description: 消息的语言环境标识 example: zh_CN message: type: string description: 本地化后的错误消息文本，面向最终用户 example: 您没有访问此资源的权限 description: 本地化消息对象，提供特定语言环境的错误消息 nullable: true asset_OusCosSingleUploadForm: required: - file - md5 type: object properties: md5: type: string description: 文件内容的 MD5，十六进制小写 example: d41d8cd98f00b204e9800998ecf8427e file: type: string description: 待上传的完整文件正文 format: binary description: '`multipart/form-data` 表单字段（boundary 由客户端生成）' asset_OusCosBlockUploadInitRequest: required: - blocks - md5 - name - size type: object properties: md5: type: string description: 整文件 MD5，十六进制小写 example: e99a18c428cb38d5f260853678922e03 blocks: minimum: 1 type: integer description: 分片总数，一般取 ceil(fileSize / blockSize)，blockSize 来自 token 接口 format: int64 example: 11 size: minimum: 1 type: integer description: 文件总字节数 format: int64 example: 10616832 name: type: string description: 原始文件名 example: photo.jpg metadata: type: string description: 元数据（可选） customPrefix: type: string description: 自定义存储前缀（可选） customFilename: type: string description: 自定义文件名（可选） description: 分片任务初始化参数语义说明（与 `POST …/block/upload/init` 的 **query** 一致；非 JSON body）。 asset_OusCosBlockUploadPartForm: required: - block - file type: object properties: block: minimum: 1 type: integer description: 当前分片序号，从 1 开始，不超过 init 时传入的 blocks format: int32 example: 1 file: type: string description: 本分片的二进制内容 format: binary description: '`multipart/form-data`：字段 `block` + `file`' asset_OusV2UploadTaskStatus: type: integer description: |- OUS 轮询 `GET /ous/api/v2/upload/status` 时从 `d.status` 读取（或分片子任务中同类字段）。 **判定建议**：`5` 为上传成功终态，可安全使用 `url`；`6` 与 `8` 为失败/中止终态，应结束轮询；其余为非终态，需按间隔继续轮询。 | 值 | 含义 | 终态 | |---|---|---| | 0 | 草稿 | 否 | | 1 | 基础检测完成 | 否 | | 2 | 内容检测完成 | 否 | | 3 | 排队上传 | 否 | | 4 | 上传中 | 否 | | 5 | 上传成功 | **是** | | 6 | 上传失败 | **是** | | 7 | 审核中 | 否 | | 8 | 手动中止 | **是** | format: int32 enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 asset_OusV2BusinessErrorCode: type: integer description: |- 当接口返回非成功或 `d` 中携带子码时，可据此做重试/提示/埋点。具体字段名以各接口响应体为准（如分片态中的 `errorCode`）。 | errorCode | 含义 | 处理建议/提示 | |---|---|---| | 1 | 配置错误 | 配置不存在或未开启，检查上传配置/业务侧引导 | | 2 | 文件大小异常 | 提示检查文件大小与分片/阈值设置 | | 3 | 文件格式异常 | 提示更换格式或重试 | | 4 | 文件内容异常 | 提示更换文件内容 | | 5 | 内容安全检测未通过 | 图片/音频安全校验失败，提示用户更换素材 | | 6 | 上传限制 | 同时上传任务数量超限/并发过高，退避后重试 | | 7 | 文件上传中 | 请稍后重试或继续轮询 | | 8 | 分片操作失败 | 分片初始化/传输失败，可重试分片或重新发起任务 | | 9 | 服务器上传限制 | 服务端忙，退避后重试 | | 10 | 线程池满 | 退避后重试 | | 11 | 元数据超限 | 元信息过大，请精简后重试 | | 12 | Token 异常 | Token 已使用或未绑定任务，需重新走获取 token/初始化流程 | | 13 | 任务异常 | 任务不存在或已结束，需新建任务重试 | 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: 任务 id；后续轮询 status 与 token 已绑定。 format: int64 example: 123456789 lackBlocks: type: array description: 缺失分片序号（从 1 起；连续区间写作 `a-b`）；非续传场景为 `null`。 nullable: true items: type: string example: 1-3 progress: type: number description: 上传进度 [0.0, 1.0]；非续传场景为 `null`。 format: double nullable: true example: 0.6 deduplicated: type: boolean description: 是否命中去重：为 `true` 时文件已存在，无需再传分片，直接轮询 `status`。 nullable: true example: false description: 分片上传初始化结果（V2）。 asset_OusV2BlockInitApiResponse: required: - c - d type: object properties: c: type: string description: 业务状态码，成功为 `0`。 example: '0' m: type: string description: 提示信息；可为空字符串。 example: '' d: $ref: '#/components/schemas/asset_OusV2BlockInitData' description: 分片初始化接口 200 响应体（`c` 为 `0` 时 `d` 为分片任务信息）。 asset_OusV2SingleUploadData: required: - taskId type: object properties: taskId: type: string description: 上传任务 id；后续轮询 `status` 与 token 已绑定。 example: task_id description: 单文件上传成功时返回。 asset_OusV2SingleUploadApiResponse: required: - c - d type: object properties: c: type: string description: 业务状态码，成功为 `0`。 example: '0' m: type: string description: 提示信息；可为空字符串。 example: '' d: $ref: '#/components/schemas/asset_OusV2SingleUploadData' description: 单文件上传 200 响应体（`c` 为 `0` 时 `d` 含 taskId）。 asset_OusV2BlockPartApiResponse: required: - c - d type: object properties: c: type: string description: 业务状态码，成功为 `0`。 example: '0' m: type: string description: 提示信息；可为空字符串。 d: description: 成功时 `d` 为 `null`。 nullable: true description: 分片上传 part 成功响应；`c` 为 0 时 `d` 为 null。并发过高等失败见 `OusV2BusinessErrorCode`（如 6）。 asset_OusV2StatusPollDataSingle: type: object properties: status: $ref: '#/components/schemas/asset_OusV2UploadTaskStatus' uploadKey: type: string description: 对象键路径。 example: heihei/2026/02/03/NGA5S6IKBIDN3RSQAAAAAAA8.jpg url: type: string description: 资源可访问 URL。 format: uri md5: type: string description: 文件 MD5，十六进制小写。 obsTaskId: type: string description: OUS 侧任务/对象标识。 example: 3FO4K029K4A3 description: '**单文件上传**任务轮询 `status` 时 `d` 的常见形态。`status` 含义见 `OusV2UploadTaskStatus`。' asset_OusV2StatusBlockProgress: type: object properties: obsId: type: string description: 分片子任务 id。 status: $ref: '#/components/schemas/asset_OusV2UploadTaskStatus' progressPercent: type: integer description: 进度百分比。 format: int32 example: 100 lackBlocks: type: array description: 仍缺的分片（编码规则同 init）。 items: type: string description: 分片上传聚合进度（嵌套在 d.blockUpload 中）。`status` 含义见 `OusV2UploadTaskStatus`。 asset_OusV2StatusPollDataBlock: type: object properties: obsTaskId: type: string description: 任务 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: 错误详情扩展；可为 null。 nullable: true description: '**分片上传**任务轮询 `status` 时 `d` 的常见形态。`status` / `errorCode` 含义见 `OusV2UploadTaskStatus`、`OusV2BusinessErrorCode`。' asset_OusV2UploadStatusApiResponse: required: - c - d type: object properties: c: type: string description: 业务状态码，成功为 `0`。 example: '0' m: type: string description: 提示信息；可为空字符串。 d: description: 与单文件/分片任务形态二选一，见 `oneOf`。 oneOf: - $ref: '#/components/schemas/asset_OusV2StatusPollDataSingle' - $ref: '#/components/schemas/asset_OusV2StatusPollDataBlock' description: 查询上传状态（轮询）响应；`d` 为单文件或分片结果结构之一。`d.status` 见 `OusV2UploadTaskStatus`。 world_CreateWorldRequest: required: - resources - scene - taskQuality type: object properties: name: type: string description: 世界展示名称 example: 客厅重建 cover: type: string description: 封面图 URL；可选 example: https://cdn.example.com/cover/custom-cover.jpg resources: minItems: 1 type: array description: >- 输入资源列表，至少 1 条。格式见 CreateWorldRequest 说明（image：.jpg / .jpeg / .png / .webp；video：.mp4 / .mov；insv：.insv。）。含图片时须至少 20 条图片类（`type=image` 或省略 type）；纯视频请显式 `type=video`；Insta360 全景视频请显式 `type=insv`。 items: $ref: '#/components/schemas/world_WorldResourceItem' useMask: type: boolean description: 是否对上传资源进行抠图。`true` 开启；省略或 `false` 不抠图。 example: false taskQuality: $ref: '#/components/schemas/world_WorldOpenApiTaskQuality' scene: $ref: '#/components/schemas/world_WorldOpenApiProjectScene' description: >- 创建 3DGS 世界重建任务的请求体。`scene` 仅支持 model 与 space；`taskQuality` 含义见 `WorldOpenApiTaskQuality`（low 极速预览 / normal 标准 / high 专业）。 **资源格式**：image：.jpg / .jpeg / .png / .webp；video：.mp4 / .mov；insv：.insv。 **资源条数**：若 `resources` 中出现图片类资源（`type=image` 或省略 `type`，后者按图片计），则图片类至少 **20 条**；若仅使用视频或 Insta360 全景视频，请为每条资源设置 `type=video` 或 `type=insv`（不触发「至少 20 张图」规则）。 world_WorldOpenApiProjectScene: type: string description: 项目场景类型。model：物体场景；space：室内场景。 example: space enum: - model - space world_WorldOpenApiResourceType: type: string description: 输入资源类型。image：图片，支持 .jpg / .jpeg / .png / .webp；video：普通视频，支持 .mp4 / .mov；insv：Insta360 全景视频，支持 .insv。 example: image enum: - image - video - insv world_WorldOpenApiTaskQuality: type: string description: 3DGS 重建任务质量档位。low：极速预览；normal：标准；high：专业。 example: high enum: - low - normal - high world_WorldResourceItem: required: - url type: object properties: url: minLength: 1 type: string description: 资源地址 URL；扩展名须与 `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: >- 重建任务单条输入资源。未传 `type` 按图片计；普通视频传 `video`；Insta360 全景视频传 `insv`。image：.jpg / .jpeg / .png / .webp；video：.mp4 / .mov；insv：.insv。 world_WorldAsyncOperation: required: - worldId type: object properties: worldId: type: string description: 世界 id；填入 `GET /world/v1/{worldId}` 的路径参数即可轮询任务状态与产出。 example: A1b2C3d4E5 description: 异步创建受理结果：封装 `worldId`，供调用方作为资源 id 请求详情直至终态。 world_ApiError: required: - code - details - message - status type: object properties: code: type: integer description: HTTP状态码 format: int32 example: 403 message: type: string description: 面向开发者的错误消息（英文），用户可见的本地化消息请使用localizedMessage字段 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错误响应对象，包含完整的错误信息、状态码和帮助信息 world_Code: type: string description: REST API标准状态码，符合Google API设计规范，用于统一的错误码表示 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: 错误原因标识符，使用大写蛇形命名法（UPPER_SNAKE_CASE），最多63个字符 example: RESOURCE_NOT_FOUND message: type: string description: 针对此错误的人类可读说明，提供具体的错误上下文 nullable: true example: The requested design with ID 12345 does not exist domain: type: string description: 错误域，通常是生成错误的服务名称 nullable: true example: restapi.qunhe.com metaData: type: object additionalProperties: type: string description: 错误的附加元数据，键值对格式，键最多64个字符，符合模式 /[a-zA-Z0-9-_]/ nullable: true example: '{"instanceLimitPerRequest":"100","currentInstanceCount":"150"}' description: 错误的附加元数据，键值对格式，键最多64个字符，符合模式 /[a-zA-Z0-9-_]/ nullable: true example: instanceLimitPerRequest: '100' currentInstanceCount: '150' description: 错误详情对象，提供错误的详细上下文信息，包括原因、域和元数据 world_Help: required: - desc - url type: object properties: desc: type: string description: 链接内容的描述，说明此帮助文档的用途 example: 如何解决权限拒绝错误 url: type: string description: 帮助文档的URL链接 example: https://docs.example.com/errors/permission-denied description: 帮助信息对象，提供解决错误的文档链接和说明 nullable: true world_LocalizedMessage: required: - locale - message type: object properties: locale: type: string description: 消息的语言环境标识 example: zh_CN message: type: string description: 本地化后的错误消息文本，面向最终用户 example: 您没有访问此资源的权限 description: 本地化消息对象，提供特定语言环境的错误消息 nullable: true world_WorldListQueryRequest: type: object properties: pageNum: minimum: 0 type: integer description: 页码（从 0 起）。 format: int32 example: 0 pageSize: maximum: 100 minimum: 0 type: integer description: 每页条数，最大 100；为 0 或未传时按 20 条计。 format: int32 example: 20 statusList: type: array description: 按重建任务状态过滤；为空表示不按状态过滤。 items: $ref: '#/components/schemas/world_WorldOpenApiTaskStatus' description: 分页查询「我的世界」列表的请求体：`pageNum` 从 0 起；`pageSize` 为每页条数（1–100，缺省或 0 时按 20 条计）。仅查询当前账号下的 3DGS 世界数据。 world_WorldOpenApiTaskStatus: type: string description: >- 重建任务状态。**进行中**：`PENDING` 排队中；`PREPROCESSING` 预处理中；`RUNNING` 执行中。**终态**：`SUCCEEDED` 成功；`FAILED` 失败；`CANCELED` 取消；`TIMEOUT` 超时；`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 分块元数据文件下载 URL（output.lodMetaPath）。任务成功且已完成 LOD 后处理时存在，否则为 null。 example: https://cdn.example.com/output/world-001-lod-meta.json description: 3DGS Splat 相关产物的下载地址：PLY / SPZ 与可选的 LOD 分块元数据（对应任务 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: 世界产物容器。3D 重建任务成功时填充 `splats`（ply/spz/lodMetaPath 在 `splats.urls` 中）；AI 生成任务另在 `imagery.panoUrl` 返回全景图下载地址。 world_WorldDetail: required: - worldId type: object properties: worldId: type: string description: 世界唯一标识；开放「创建世界」接口在 `WorldAsyncOperation.worldId` 字段中返回与本字段相同的值。 example: A1b2C3d4E5 name: type: string description: 世界名称 example: 客厅重建 cover: type: string description: 封面图 URL。 example: https://cdn.example.com/cover/world-001.jpg scene: $ref: '#/components/schemas/world_WorldOpenApiProjectScene' createTime: type: integer description: 创建时间，Unix 毫秒时间戳。 format: int64 example: 1699339916000 updateTime: type: integer description: 最近修改时间，Unix 毫秒时间戳。 format: int64 example: 1699340120000 status: $ref: '#/components/schemas/world_WorldOpenApiTaskStatus' progress: type: number description: 重建任务进度 [0.0, 1.0]。 format: float example: 0.65 assets: $ref: '#/components/schemas/world_WorldAssetBundle' description: >- 世界信息。`worldId` 为业务侧世界唯一标识；`scene`/`status` 等为约定字符串；`createTime` / `updateTime` 为 Unix 毫秒时间戳（与 1.6.2-2-1 时间字段约定一致）。详情接口在产出可用时，可能返回 splat 等下载地址；AI 生成世界另在 `assets.imagery.panoUrl` 返回全景图。 world_WorldImagery: type: object properties: panoUrl: type: string description: AI 生成全景图下载地址。仅 AI 生成（Spatial Gen）世界在全景图子任务成功后有值。 example: https://cdn.example.com/output/world-001-pano.jpg description: AI 生成世界的图片产物；当前仅包含全景图下载地址。 world_WorldOpenApiUpAxis: type: string description: 世界坐标 up 轴。Y：+Y 朝上（glTF/USD 默认）；Z：+Z 朝上（本服务 3DGS 产出约定）。 example: Z enum: - 'Y' - Z world_WorldPagedList: type: object properties: pageNum: type: integer description: 本次请求使用的页码（从 0 起）。 format: int32 example: 0 pageSize: type: integer description: 本次请求使用的每页条数。 format: int32 example: 20 count: type: integer description: 当前页记录条数。 format: int32 example: 20 totalCount: type: integer description: 符合筛选条件的总记录数。 format: int32 example: 128 hasMore: type: boolean description: 是否还有下一页。 example: false result: type: array description: 当前页的世界记录列表（由 ProjectAggregateDTO 映射为 WorldOpen，列表查询默认 withResult=false）。 items: $ref: '#/components/schemas/world_WorldDetail' description: 世界列表分页结果：含本次请求的 `pageNum` / `pageSize`，以及当前页数据与总计。 world_WorldSemanticsMetadata: type: object properties: upAxis: $ref: '#/components/schemas/world_WorldOpenApiUpAxis' description: 语义元数据（相机位姿、比例、偏移、坐标系约定等）。任务成功且返回 splat 产物时，应包含 upAxis 以标明坐标系。 world_WorldSplatBundle: type: object properties: urls: $ref: '#/components/schemas/world_SplatFileUrls' description: 3DGS splat 输出文件集合。 world_GenerateWorldRequest: type: object properties: name: type: string description: 项目 / 世界展示名称 example: 客厅生成 cover: type: string description: 封面图 URL；可选。 example: https://cdn.example.com/cover/gen-cover.jpg resources: type: array description: 输入资源列表；与 prompt 至少满足其一。仅支持图片，至多 1 条；未传 type 时按图片处理。image：.jpg / .jpeg / .png / .webp。 items: $ref: '#/components/schemas/world_GenerateWorldResourceItem' prompt: type: string description: 文本提示词；可与 resources 同时提供。 example: 现代简约风格，阳光充足的客厅 description: |- 创建 3DGS「生成世界」任务的请求体；支持纯文案、单张图片或图文组合。室内场景效果更成熟；非室内为 Beta（详见同路径 POST 说明）。 至少需提供非空 prompt 或至少一条图片资源（至多 1 张）；image：.jpg / .jpeg / .png / .webp。 world_GenerateWorldResourceItem: required: - url type: object properties: url: minLength: 1 type: string description: 图片资源 URL；扩展名须为 image：.jpg / .jpeg / .png / .webp。 example: https://cdn.example.com/input/room.jpg type: $ref: '#/components/schemas/world_WorldOpenApiGenResourceType' description: 生成任务单条输入资源（图片）。未传 `type` 时按图片处理。image：.jpg / .jpeg / .png / .webp。 world_WorldOpenApiGenResourceType: type: string description: 生成任务输入资源类型，仅支持 image（图片），支持 .jpg / .jpeg / .png / .webp。 example: image enum: - image lux3d_HumanoidAutoRigRequest: type: object required: - modelUrl properties: modelUrl: type: string format: uri description: >- GLB 模型的公网 HTTPS URL。如需上传本地文件，请先调用 [Asset 文件上传接口](https://labs.aholo3d.cn/api-docs/api-reference#tag/asset)，再将返回的 URL 填入此字段。 lux3d_HumanoidAnimationRetargetRequest: type: object required: - rigModelUrl - animationIds properties: rigModelUrl: type: string format: uri description: >- 已绑骨 GLB 模型的公网 HTTPS URL。如需上传本地文件，请先调用 [Asset 文件上传接口](https://labs.aholo3d.cn/api-docs/api-reference#tag/asset)，再将返回的 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: 动作 ID 列表，从以下 85 个可选值中选择 1–10 个，不可重复，区分大小写。 animationOutputMode: type: string enum: - separate - combined default: separate description: separate 为每个动作生成一个完整文件；combined 将所选动作合并到一个文件，每个动作保留为独立动画片段。 outFormat: type: string enum: - glb - fbx default: glb description: 输出文件格式。 animateInPlace: type: boolean default: false description: 是否生成原地动画。 lux3d_MultimodalToImageRequest: type: object properties: img: minLength: 1 pattern: .*\S.* type: string description: >- 单张参考图片 URL，可单独使用或与 prompt 组合。img 和 prompt 至少提供一个，传入的值不能为空白。如需上传本地文件，请先调用 [Asset 文件上传接口](https://labs.aholo3d.cn/api-docs/api-reference#tag/asset)，再将返回的 URL 填入此字段。 example: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg prompt: minLength: 1 pattern: .*\S.* type: string description: 图片生成提示词，可单独使用或与 img 组合。img 和 prompt 至少提供一个，传入的值不能为空白。 example: 把椅子改成浅色原木材质，保持造型和视角 description: 多模态单图生成请求体，img 和 prompt 至少提供一个，支持纯图片、纯文字或图文组合输入。 lux3d_ImageToFourViewRequest: type: object properties: img: minLength: 1 pattern: .*\S.* type: string description: >- 单张图片 URL。img 和 prompt 至少提供一个，传入的值不能为空白。如需上传本地文件，请先调用 [Asset 文件上传接口](https://labs.aholo3d.cn/api-docs/api-reference#tag/asset)，再将返回的 URL 填入此字段。 example: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg prompt: minLength: 1 pattern: .*\S.* type: string description: 文字提示词，可单独用于纯文字生成四视图，也可与 img 组合使用。img 和 prompt 至少提供一个，传入的值不能为空白。 example: 一把现代简约浅色原木餐椅，纯白背景 description: 多模态四视图请求体，img 和 prompt 至少提供一个，支持纯图片、纯文字或图文组合输入。 lux3d_ImgTo3dRequest: type: object properties: img: minLength: 1 pattern: .*\S.* type: string description: >- 单张图片 URL，G1 和 G1-Turbo 均支持。img 与 imgs 必须且只能提供一个，图片 URL 不能为空白。如需上传本地文件，请先调用 [Asset 文件上传接口](https://labs.aholo3d.cn/api-docs/api-reference#tag/asset)，再将返回的 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: >- G1 / G1-Turbo 的 1-32 张图片 URL。保留输入顺序，第一张图作为主要参考；与 img 互斥。使用 imgs 时必须显式传入 version=G1 或 version=G1-Turbo。如需上传本地文件，请先调用 [Asset 文件上传接口](https://labs.aholo3d.cn/api-docs/api-reference#tag/asset)，再将返回的 URL 填入此字段。 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: 生成版本，支持 G1 和 G1-Turbo。省略时使用默认版本；建议显式传入。 enum: - G1 - G1-Turbo example: G1 faceCount: type: integer description: 目标 Mesh 面数，取值范围为 10000-300000，默认 300000；PLY 输出不受此参数影响。 minimum: 10000 maximum: 300000 example: 300000 outputFormat: type: array uniqueItems: true items: type: string enum: - zip - glb - ply description: 请求的输出格式。G1 固定返回 ZIP 和 GLB，请求包含 ply 时额外返回 PLY；G1-Turbo 返回指定格式，省略或传空数组时返回 ZIP。 example: - zip - glb enablePbr: type: boolean description: 仅对 G1-Turbo 包含 Mesh 的请求生效：true 或省略时生成 PBR Mesh，false 生成白模；不决定输出格式。G1 及仅请求 PLY 时忽略。 default: true aiPredictSize: type: boolean description: 省略或 true 会启用 AI 尺寸预测与缩放，false 关闭。 description: >- 图生 3D 请求体，支持 G1 和 G1-Turbo，可使用 img 单图或 imgs 多图；img 与 imgs 必须且只能提供一个。使用 imgs 时必须显式传入 version=G1 或 version=G1-Turbo。 lux3d_TextTo3dRequest: required: - prompt type: object properties: prompt: minLength: 1 pattern: .*\S.* type: string description: 文本提示词 example: 生成一个高质量的3D木椅模型 style: type: string description: 生成风格，默认 photorealistic。 enum: - photorealistic - cartoon - anime - hand_painted - cyberpunk - fantasy - glass default: photorealistic example: photorealistic img: type: string description: >- 可选的参考图片 URL。如需上传本地文件，请先调用 [Asset 文件上传接口](https://labs.aholo3d.cn/api-docs/api-reference#tag/asset)，再将返回的 URL 填入此字段。 example: https://qhstaticssl.kujiale.com/image/jpeg/1784775590613/image_to_3d_model.jpg version: type: string description: 生成版本，支持 G1 和 G1-Turbo。省略时使用默认版本；建议显式传入。 enum: - G1 - G1-Turbo example: G1 faceCount: type: integer description: 目标 Mesh 面数，取值范围为 10000-300000，默认 300000；PLY 输出不受此参数影响。 minimum: 10000 maximum: 300000 example: 300000 outputFormat: type: array uniqueItems: true items: type: string enum: - zip - glb - ply description: 请求的输出格式。G1 固定返回 ZIP 和 GLB，请求包含 ply 时额外返回 PLY；G1-Turbo 返回指定格式，省略或传空数组时返回 ZIP。 example: - zip - glb enablePbr: type: boolean description: 仅对 G1-Turbo 包含 Mesh 的请求生效：true 或省略时生成 PBR Mesh，false 生成白模；不决定输出格式。G1 及仅请求 PLY 时忽略。 default: true aiPredictSize: type: boolean description: 省略或 true 会启用 AI 尺寸预测与缩放，false 关闭。 description: 文生 3D 请求体，支持 G1 和 G1-Turbo，可选提供一张 img 参考图。 lux3d_MaterialTransferRequest: required: - img - meshUrl - version type: object properties: img: minLength: 1 pattern: .*\S.* type: string description: >- 材质参考图片 URL。如需上传本地文件，请先调用 [Asset 文件上传接口](https://labs.aholo3d.cn/api-docs/api-reference#tag/asset)，再将返回的 URL 填入此字段。 example: https://qhstaticssl.kujiale.com/image/png/1784776951878/material_transfer_input.png meshUrl: minLength: 1 pattern: .*\S.* type: string description: >- 模型 GLB 文件 URL。如需上传本地文件，请先调用 [Asset 文件上传接口](https://labs.aholo3d.cn/api-docs/api-reference#tag/asset)，再将返回的 URL 填入此字段。 example: https://qhstaticssl.kujiale.com/application/octetstream/1784776896628/material_transfer_model.glb version: type: string description: 必填，当前固定传 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: 请求的输出格式：zip、glb、usdz、obj_zip 或 fbx_zip。 example: - zip - glb aiPredictSize: type: boolean description: 是否预测模型尺寸；为 true 时忽略 customSize。 customSize: type: number format: float minimum: 0 exclusiveMinimum: true description: aiPredictSize 为 false 或未传时使用的目标高度（mm）；省略时保持原始尺寸。 description: 材质重绘请求体，version 当前固定为 v3.0-standard。 lux3d_PartSplitRequest: required: - glbUrl type: object properties: glbUrl: minLength: 1 pattern: .*\S.* type: string description: >- 待拆分的 GLB 模型公网 URL，必须可由服务端访问。如需上传本地文件，请先调用 [Asset 文件上传接口](https://labs.aholo3d.cn/api-docs/api-reference#tag/asset)，再将返回的 URL 填入此字段；也可使用仍在有效期内的 Lux3D GLB 任务产物 URL。 example: https://qhstaticssl.kujiale.com/model/gltfbinary/1790144390549/14B82261CD6DF53FA6B406240E20CB2C.glb description: 部件拆分任务请求体。 lux3d_MultiFormatExportRequest: required: - modelUrl type: object properties: modelUrl: minLength: 1 type: string description: >- 模型公网 URL，支持 .zip 或 .glb。ZIP 输入必须来自 Lux3D 生成任务；GLB 输入时 outputFormat 不能为空。如需上传本地文件，请先调用 [Asset 文件上传接口](https://labs.aholo3d.cn/api-docs/api-reference#tag/asset)，再将返回的 URL 填入此字段；其中 ZIP 仍必须是 Lux3D 生成任务产物。 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: | 可选导出格式，支持单项或组合：usdz、obj_zip、fbx_zip、stl、3mf。outputFormat 不接受 glb。 - usdz：Apple 生态常用的 AR 模型格式，适用于 iOS、iPadOS 和 Quick Look 等 AR 预览场景。 - obj_zip：包含 OBJ、MTL 和贴图文件的压缩包，兼容常见 3D 软件和 DCC 工具。 - fbx_zip：包含 FBX 模型及贴图资源的压缩包，适用于 Maya、3ds Max、Blender 等主流 DCC 工作流。 - stl：面向 3D 打印和几何交换的网格格式，不包含材质和贴图信息。 - 3mf：面向 3D 打印的 3D Manufacturing Format，适合需要制造/打印格式交付的场景。 ZIP 输入时可以省略或传空数组；GLB 输入时至少需要一个值。 example: - usdz - obj_zip - stl - 3mf description: 多格式导出任务请求体。 lux3d_ArticulationAnimationRequest: type: object required: - glbUrl - prompt additionalProperties: false properties: glbUrl: type: string format: uri minLength: 1 description: >- 输入 GLB 模型的公网 HTTP(S) URL，必须可由服务端访问。如需上传本地文件，请先调用 [Asset 文件上传接口](https://labs.aholo3d.cn/api-docs/api-reference#tag/asset)，再将返回的 URL 填入此字段。 example: https://assets.aholo3d.cn/examples/cubely/joint-motion/target-model.glb prompt: type: string minLength: 1 pattern: .*\S.* description: 描述需要运动的部件及期望的关节运动方式，不能仅包含空白字符。 example: 保持底座固定，为盖子添加旋转关节，让盖子缓慢打开和闭合。 description: 模型关节化与动画请求。glbUrl 和 prompt 均必填，不接受其他字段。 lux3d_TaskCreateResponse: type: object properties: f: type: object description: 失败信息；成功时为 null。 nullable: true additionalProperties: true d: type: integer description: 返回 taskid format: int64 example: 1256173 nullable: true m: type: string description: 提示信息；成功时为空字符串 ""。 nullable: true c: type: string description: 状态码；成功时为 "0"，普通参数错误时为 "-1"，部分业务错误使用专用错误码。 nullable: true description: 任务创建响应体。 lux3d_TaskOutput: type: object properties: content: type: string description: 结果文件 URL、JSON 字符串或未请求格式的标记 NOT_REQUESTED。具体格式见“查询生成任务”接口说明。 nullable: true example: https://cos.example.com/lux3d/xxx/result.zip description: 任务输出项。 lux3d_TaskQueryData: type: object properties: taskId: type: integer description: 任务ID format: int64 example: 1389513 outputs: type: array description: 任务结果列表，具体格式和顺序见“查询生成任务”接口说明。运行中的任务可能返回部分结果。 items: $ref: '#/components/schemas/lux3d_TaskOutput' status: type: integer description: 任务状态：0-初始化，1-运行中，3-成功，4-失败，6-已取消。 format: int32 enum: - 0 - 1 - 3 - 4 - 6 example: 3 description: 任务查询数据。 lux3d_TaskQueryResponse: type: object properties: f: type: object description: 失败信息；成功时为 null。 nullable: true additionalProperties: true d: $ref: '#/components/schemas/lux3d_TaskQueryData' m: type: string description: 提示信息；成功时为空字符串 ""。 nullable: true c: type: string description: 状态码；成功时为 "0"，普通参数错误时为 "-1"。 nullable: true description: 任务查询响应体。 lux3d_TaskListItem: type: object properties: taskId: type: integer format: int64 description: 任务 ID status: type: integer description: 任务状态：0-初始化，1-运行中，3-成功，4-失败，6-已取消。 enum: - 0 - 1 - 3 - 4 - 6 created: type: integer format: int64 description: 任务创建时间，Unix 毫秒时间戳 lastModified: type: integer format: int64 description: 任务最后修改时间，Unix 毫秒时间戳 lux3d_TaskListData: type: object properties: items: type: array items: $ref: '#/components/schemas/lux3d_TaskListItem' total: type: integer description: 符合条件的任务总数 page: type: integer description: 当前页码 pageSize: type: integer description: 每页数量 lux3d_TaskListResponse: type: object properties: f: type: object nullable: true additionalProperties: true description: 失败信息；成功时为 null。 d: $ref: '#/components/schemas/lux3d_TaskListData' m: type: string nullable: true description: 提示信息。成功时为空字符串 ""。 c: type: string nullable: true description: 状态码。成功时为 "0"，失败时为错误码字符串。 description: | 生成记录分页响应体。 列表接口与创建、查询接口的成功响应一致：f 为 null、c 为 "0"、m 为 ""（空字符串）。请按 c === "0" 判断成功。 rendercloud_OfflineRenderSubmitRequest: type: object description: 离线渲染提交请求体。提交时不传 `operationId`。 additionalProperties: false required: - requestId - usdContent properties: requestId: type: string description: 调用方生成的请求追踪标识。服务端不基于该字段做任务幂等。 minLength: 1 usdContent: type: string description: Base64 编码后的 OpenUSD 文本或二进制内容。 minLength: 1 rendercloud_OperationPollRequest: type: object description: 长耗时操作轮询请求体。提交成功后，使用返回的 `operationId` 轮询。 additionalProperties: false required: - operationId properties: operationId: type: string description: 提交响应返回的操作 ID。 minLength: 1 rendercloud_OfflineRenderResponse: type: object description: 离线渲染完成结果。仅在 `Operation.done=true` 且任务成功时返回。 additionalProperties: false properties: taskId: type: string description: 离线渲染任务 ID。 resultUrl: type: string format: uri description: 渲染结果图片地址。 rendercloud_RealtimeSessionSubmitRequest: type: object description: 实时渲染流创建请求体。创建时不传 `operationId`。 additionalProperties: false required: - requestId - usdContent properties: requestId: type: string description: 调用方生成的幂等键。 minLength: 1 usdContent: type: string description: Base64 编码后的 OpenUSD 文本或二进制内容。 minLength: 1 settings: type: object description: 可选的实时渲染会话配置。未传时使用服务端默认配置。 additionalProperties: false properties: autoEnhanceAI: type: boolean default: false description: 是否启用 AI 增强。启用后会增加单帧处理延迟。 rendercloud_RealtimeSessionQueryResponse: type: object description: 实时渲染流查询结果。`status=ACTIVE` 时包含 WebSocket 连接参数。 additionalProperties: false properties: sessionId: type: string description: 实时渲染流会话 ID。 status: $ref: '#/components/schemas/rendercloud_RenderCloudSessionStatus' currentQueuePosition: type: integer format: int32 description: 当前排队位置。为 0 时表示会话已就绪。 host: type: string description: 实时渲染流连接域名。 nodeId: type: string description: WebSocket 连接 URL 中 `nid` 查询参数的值。 streamId: type: string description: WebSocket 握手消息中 `slaveInit.masterStreamingId` 的值。 token: type: string description: 建立实时渲染流连接所需的鉴权 token。 rendercloud_RealtimeSessionUpdateRequest: type: object description: 实时渲染流增量更新请求体。 additionalProperties: false required: - requestId - usdContent properties: requestId: type: string description: 调用方生成的幂等键。 minLength: 1 usdContent: type: string description: Base64 编码后的增量 OpenUSD 内容。 minLength: 1 rendercloud_RealtimeSessionUpdateResponse: type: object description: 实时渲染流增量更新响应体。 additionalProperties: false properties: sessionId: type: string description: 实时渲染流会话 ID。 status: $ref: '#/components/schemas/rendercloud_RenderCloudSessionStatus' rendercloud_RealtimeSessionCloseResponse: type: object description: 实时渲染流关闭响应体。 additionalProperties: false properties: sessionId: type: string description: 实时渲染流会话 ID。 closed: type: boolean description: 是否在服务端找到并关闭了会话。 rendercloud_OfflineRenderProcessingOperation: type: object description: 离线渲染处理中状态。 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。 error: type: object nullable: true description: 处理中时为 null。 rendercloud_OfflineRenderSuccessOperation: type: object description: 离线渲染成功状态。 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。 rendercloud_RealtimeSessionProcessingOperation: type: object description: 实时渲染流创建处理中状态。 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。 error: type: object nullable: true description: 处理中时为 null。 rendercloud_RealtimeSessionSuccessOperation: type: object description: 实时渲染流创建成功状态。 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。 rendercloud_OperationError: type: object description: 长耗时操作失败状态。 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。 error: $ref: '#/components/schemas/rendercloud_ApiError' rendercloud_OperationId: type: string description: 长耗时操作 ID。 rendercloud_OperationMetaData: type: object nullable: true description: 长耗时操作扩展元数据。当前接口通常返回 null。 additionalProperties: true rendercloud_Int2: type: object description: 二维整数向量。用于表示出图分辨率，`x` 为宽，`y` 为高。 additionalProperties: false required: - x - 'y' properties: x: type: integer format: int32 minimum: 1 description: 图片宽度，单位为像素。 'y': type: integer format: int32 minimum: 1 description: 图片高度，单位为像素。 rendercloud_RenderCloudSessionStatus: type: string description: | 实时渲染流会话状态。 - `INITIALIZING`：会话已创建，后台正在建立 streaming 连接。 - `ACTIVE`：streaming 连接已建立，可正常渲染。 - `FAILED`：初始化或操作失败。 - `CLOSED`：会话已关闭。 enum: - RENDER_CLOUD_SESSION_STATUS_UNSPECIFIED - INITIALIZING - ACTIVE - FAILED - CLOSED rendercloud_ApiError: type: object description: OpenAPI 网关标准错误响应。异步操作失败时位于 `Operation.error` 字段内。 additionalProperties: true required: - code - message - status properties: code: type: integer format: int32 description: HTTP 语义错误码。 example: 500 message: type: string description: 可读错误信息。可能包含网关透传的错误详情。 example: 'code: INTERNAL, details: ErrorDetails(reason=INTERNAL_ERROR, message=null, domain=render, metaData=null)' status: type: string description: 标准错误状态。 enum: - INVALID_ARGUMENT - NOT_FOUND - RESOURCE_EXHAUSTED - INTERNAL example: INTERNAL details: $ref: '#/components/schemas/rendercloud_ErrorDetails' rendercloud_ErrorDetails: type: object description: 网关透传的扩展错误详情。 additionalProperties: true properties: reason: type: string description: 错误原因。 example: INTERNAL_ERROR domain: type: string description: 错误归属域名。示例使用通用值，避免暴露内部服务域名。 example: render rendercloud_MeshUploadProcessRequest: type: object description: Mesh 上传解析任务请求体。 additionalProperties: false properties: originMeshUrl: type: string format: uri description: >- 原始 Mesh 文件的 URL 地址。当文件地址是云端 URL 时，该 URL 必须能够被公开访问到。如果文件仅保存在本地，推荐先通过 [资产上传](https://labs.aholo3d.cn/api-docs/api-reference#tag/asset) 上传接口上传文件并取得 URL，再将该 URL 填入此字段。 example: https://example.com/mesh/original.glb fastUpload: type: boolean description: 是否启用快速上传，可选，默认 false。当 fastUpload 为 true 且文件为 GLB 格式时，使用快速上传流程；未传或为 false 时使用普通上传流程。 default: false example: false rendercloud_TaskCreateResponse: type: object description: 任务创建响应体，遵循标准 Result 格式。 additionalProperties: false properties: success: type: boolean description: 是否成功。 example: true data: type: integer format: int64 description: 创建的任务 ID。 example: 1305220918472257500 errorMsg: type: string nullable: true description: 错误信息，成功时为 null。 example: null rendercloud_TaskQueryResponse: type: object description: 任务查询响应体，遵循标准 Result 格式。 additionalProperties: false properties: success: type: boolean description: 是否成功。 example: true data: $ref: '#/components/schemas/rendercloud_AiGenerateBusInstanceOpenDto' errorMsg: type: string nullable: true description: 错误信息，成功时为 null。 example: null rendercloud_CommonErrorResponse: type: object description: 通用错误响应体。 additionalProperties: false properties: success: type: boolean description: 是否成功。 example: false data: type: object nullable: true description: 数据，错误时为 null。 example: null errorMsg: type: string description: 错误信息。 example: 参数无效 rendercloud_AiGenerateBusInstanceOpenDto: type: object description: RenderCloud 任务详情。 additionalProperties: false properties: taskId: type: integer format: int64 description: 任务 ID。 example: 1272794 userId: type: integer format: int64 description: 用户 ID。 example: 12345 status: type: integer format: int32 description: | 任务状态： - `0`: INIT - 初始化 - `1`: RUNNING - 运行中 - `3`: SUCCESS - 成功 - `4`: FAIL - 失败 example: 3 outputs: type: array nullable: true description: 任务输出素材列表，处理中时为 null。 items: $ref: '#/components/schemas/rendercloud_AiGraphicAssetDto' example: - content: YYZN2MZVAIQLEPTULM888888 sourceReferId: '607583273' rendercloud_AiGraphicAssetDto: type: object description: AI 素材对象。 additionalProperties: false properties: sourceReferId: type: string description: 源素材引用 ID（如 商品Id）。 example: '607583273' content: type: string description: | 素材内容： - 对于 Mesh 上传任务输入：原始 Mesh URL - 对于 Mesh 上传任务输出：解析后的 meshId example: YYZN2MZVAIQLEPTULM888888 spatialunderstanding_CreateSpatialUnderstandingTaskRequest: required: - inputFileUrl type: object properties: inputFileUrl: minLength: 1 type: string description: >- 点云文件 URL，仅支持 `.ply`，面向室内场景。点云应使用米为单位的右手坐标系，并完成空间对齐（[ScanNet Alignment](https://github.com/ScanNet/ScanNet/tree/master/Alignment)）：使 Z 轴朝上、地面与 X-Y 平面平行，同时尽量使主要墙体在水平面上的走向与 X 轴或 Y 轴平行。若输入点云未满足上述要求，请传入 `transformationMatrix`。本地文件请先调用 [Asset 文件上传接口](https://labs.aholo3d.cn/api-docs/api-reference#tag/asset)，再将返回的 URL 填入此字段。不支持外部 URL。 example: https://holo-cos.aholo3d.cn/resource/openapi/xxx.ply transformationMatrix: type: array description: >- 可选。用于将输入点云转换至上述对齐坐标系的 4×4 齐次变换矩阵（4 行 4 列数字），使 Z 轴朝上、地面与 X-Y 平面平行，并尽量使主要墙体在水平面上的走向与 X 轴或 Y 轴平行。不传表示输入点云已完成对齐，不做变换。约定：列向量乘法 `p' = T p`；平移在第 4 列；右手系；Z-up（[ScanNet Alignment](https://github.com/ScanNet/ScanNet/tree/master/Alignment)）；单位米。 分块示意：左上 `R` 为 3×3 旋转，右侧 `t` 为平移，底行固定为 `[0, 0, 0, 1]`。 ``` T = [ R(3×3) t(3×1) ] [ 0(1×3) 1 ] ``` 对应请求体下标： ``` [ [ r00, r01, r02, tx ], [ r10, r11, r12, ty ], [ r20, r21, r22, tz ], [ 0, 0, 0, 1 ] ] ``` example: - - 0.9337461173020494 - 0.3579360116324523 - 0 - 1.871216953359744 - - -0.3579360116324523 - 0.9337461173020494 - 0 - -0.2091883674268249 - - 0 - 0 - 0.9999999999999999 - 1.2121098756790158 - - 0 - 0 - 0 - 1 items: type: array description: >- 可选。用于将输入点云转换至上述对齐坐标系的 4×4 齐次变换矩阵（4 行 4 列数字），使 Z 轴朝上、地面与 X-Y 平面平行，并尽量使主要墙体在水平面上的走向与 X 轴或 Y 轴平行。不传表示输入点云已完成对齐，不做变换。约定：列向量乘法 `p' = T p`；平移在第 4 列；右手系；Z-up（[ScanNet Alignment](https://github.com/ScanNet/ScanNet/tree/master/Alignment)）；单位米。 分块示意：左上 `R` 为 3×3 旋转，右侧 `t` 为平移，底行固定为 `[0, 0, 0, 1]`。 ``` T = [ R(3×3) t(3×1) ] [ 0(1×3) 1 ] ``` 对应请求体下标： ``` [ [ r00, r01, r02, tx ], [ r10, r11, r12, ty ], [ r20, r21, r22, tz ], [ 0, 0, 0, 1 ] ] ``` example: - - 0.9337461173020494 - 0.3579360116324523 - 0 - 1.871216953359744 - - -0.3579360116324523 - 0.9337461173020494 - 0 - -0.2091883674268249 - - 0 - 0 - 0.9999999999999999 - 1.2121098756790158 - - 0 - 0 - 0 - 1 items: type: number description: >- 可选。用于将输入点云转换至上述对齐坐标系的 4×4 齐次变换矩阵（4 行 4 列数字），使 Z 轴朝上、地面与 X-Y 平面平行，并尽量使主要墙体在水平面上的走向与 X 轴或 Y 轴平行。不传表示输入点云已完成对齐，不做变换。约定：列向量乘法 `p' = T p`；平移在第 4 列；右手系；Z-up（[ScanNet Alignment](https://github.com/ScanNet/ScanNet/tree/master/Alignment)）；单位米。 分块示意：左上 `R` 为 3×3 旋转，右侧 `t` 为平移，底行固定为 `[0, 0, 0, 1]`。 ``` T = [ R(3×3) t(3×1) ] [ 0(1×3) 1 ] ``` 对应请求体下标： ``` [ [ r00, r01, r02, tx ], [ r10, r11, r12, ty ], [ r20, r21, r22, tz ], [ 0, 0, 0, 1 ] ] ``` format: double description: 创建空间理解任务请求体。面向室内点云；坐标系为米、右手系、Z-up。 spatialunderstanding_SpatialUnderstandingTaskAsyncOperation: required: - taskId type: object properties: taskId: type: string description: 任务 id。填入 `GET /spatial-understanding/v1/tasks/{taskId}` 即可轮询状态与结果。 example: A1b2C3d4E5 description: 创建任务受理结果，含 `taskId`。用该 id 查询详情直至任务完成。 spatialunderstanding_ApiError: required: - code - details - message - status type: object properties: code: type: integer description: HTTP状态码 format: int32 example: 403 message: type: string description: 面向开发者的错误消息（英文），用户可见的本地化消息请使用localizedMessage字段 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错误响应对象，包含完整的错误信息、状态码和帮助信息 spatialunderstanding_Code: type: string description: REST API标准状态码，符合Google API设计规范，用于统一的错误码表示 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: 错误原因标识符，使用大写蛇形命名法（UPPER_SNAKE_CASE），最多63个字符 example: RESOURCE_NOT_FOUND message: type: string description: 针对此错误的人类可读说明，提供具体的错误上下文 nullable: true example: The requested design with ID 12345 does not exist domain: type: string description: 错误域，通常是生成错误的服务名称 nullable: true example: restapi.qunhe.com metaData: type: object additionalProperties: type: string description: 错误的附加元数据，键值对格式，键最多64个字符，符合模式 /[a-zA-Z0-9-_]/ nullable: true example: '{"instanceLimitPerRequest":"100","currentInstanceCount":"150"}' description: 错误的附加元数据，键值对格式，键最多64个字符，符合模式 /[a-zA-Z0-9-_]/ nullable: true example: instanceLimitPerRequest: '100' currentInstanceCount: '150' description: 错误详情对象，提供错误的详细上下文信息，包括原因、域和元数据 spatialunderstanding_Help: required: - desc - url type: object properties: desc: type: string description: 链接内容的描述，说明此帮助文档的用途 example: 如何解决权限拒绝错误 url: type: string description: 帮助文档的URL链接 example: https://docs.example.com/errors/permission-denied description: 帮助信息对象，提供解决错误的文档链接和说明 nullable: true spatialunderstanding_LocalizedMessage: required: - locale - message type: object properties: locale: type: string description: 消息的语言环境标识 example: zh_CN message: type: string description: 本地化后的错误消息文本，面向最终用户 example: 您没有访问此资源的权限 description: 本地化消息对象，提供特定语言环境的错误消息 nullable: true spatialunderstanding_SpatialUnderstandingTaskListQueryRequest: type: object properties: pageNum: minimum: 0 type: integer description: 页码，从 1 起；`0` 与 `1` 均视为第一页。 format: int32 example: 1 pageSize: maximum: 100 minimum: 0 type: integer description: 每页条数，最大 100；为 0 或未传时按 20 条计。 format: int32 example: 20 statusList: type: array description: 按任务状态过滤（大写字符串）；为空表示不按状态过滤。 items: $ref: '#/components/schemas/spatialunderstanding_SpatialUnderstandingTaskStatus' description: 分页查询空间理解任务列表的请求体：`pageNum` 从 1 起（`0` 与 `1` 均视为第一页）；`pageSize` 为每页条数（1-100，缺省或 0 时按 20 条计）。仅查询当前账号下的任务数据。 spatialunderstanding_SpatialUnderstandingTaskStatus: type: string description: 空间理解任务状态。**进行中**：`PENDING` 排队中；`RUNNING` 执行中。**终态**：`SUCCEEDED` 成功；`FAILED` 失败；`TIMEOUT` 超时。 example: SUCCEEDED enum: - PENDING - RUNNING - SUCCEEDED - FAILED - TIMEOUT spatialunderstanding_SpatialUnderstandingTask: type: object properties: taskId: type: string description: 任务 id，与创建接口返回值一致。 example: A1b2C3d4E5 status: $ref: '#/components/schemas/spatialunderstanding_SpatialUnderstandingTaskStatus' modelVersion: type: string description: 本次任务实际使用的模型版本。创建时不可指定，由服务端使用当前默认版本。 example: spatiallm-pointcloud-1.2-20260910 result: $ref: '#/components/schemas/spatialunderstanding_SpatialUnderstandingTaskResult' errorCode: type: string description: >- 失败分类码；仅 `FAILED` 或 `TIMEOUT` 时返回。`MODEL_SUBMIT_FAILED`：任务提交失败；`MODEL_TASK_FAILED`：任务执行失败；`RESULT_TRANSFER_FAILED`：结果写入失败；`TIMEOUT`：超时。 example: MODEL_TASK_FAILED errorMessage: type: string description: 失败详情；仅 `FAILED` 或 `TIMEOUT` 时返回。 example: task failed createTime: type: integer description: 创建时间，Unix 毫秒。 format: int64 updateTime: type: integer description: 最后更新时间，Unix 毫秒。 format: int64 description: 空间理解任务详情。成功时含 `result`，失败或超时时含 `errorCode`、`errorMessage`。 spatialunderstanding_SpatialUnderstandingTaskPagedList: type: object properties: pageNum: type: integer description: 本次请求使用的页码（从 1 起；请求传 `0` 时原样回写 `0`）。 format: int32 example: 1 pageSize: type: integer description: 本次请求使用的每页条数。 format: int32 example: 20 count: type: integer description: 当前页记录条数。 format: int32 example: 20 totalCount: type: integer description: 符合筛选条件的总记录数。 format: int32 example: 128 hasMore: type: boolean description: 是否还有下一页。 example: false result: type: array description: 当前页的任务记录列表。 items: $ref: '#/components/schemas/spatialunderstanding_SpatialUnderstandingTask' description: 空间理解任务列表分页结果：含本次请求的 `pageNum` / `pageSize`，以及当前页数据与总计。 spatialunderstanding_SpatialUnderstandingTaskResult: type: object properties: resultSslUrl: type: string description: |- 空间理解结果文件的访问地址。UTF-8 纯文本，一行一个实体；服务端不提供解析后的 JSON，请自行下载并解析。 坐标系：单位米，右手系，Z-up（[ScanNet Alignment](https://github.com/ScanNet/ScanNet/tree/master/Alignment)）。 行格式：`{id}={Type}(arg1,arg2,...)`。未知 `Type` 请跳过该行，不要整文件失败。 | Type | 行格式 | | --- | --- | | Wall | `wall_{n}=Wall(ax,ay,az,bx,by,bz,height,thickness)` | | Door | `door_{n}=Door(wall_id,position_x,position_y,position_z,width,height)` | | Window | `window_{n}=Window(wall_id,position_x,position_y,position_z,width,height)` | | Bbox | `bbox_{n}=Bbox(class,position_x,position_y,position_z,angle_z,scale_x,scale_y,scale_z)` | | 类型 | 字段 | 数据类型 | 说明 | | --- | --- | --- | --- | | Wall | `ax, ay, az` | number | 墙体底部基准线起点 A 的三维坐标。 | | Wall | `bx, by, bz` | number | 墙体底部基准线终点 B 的三维坐标。 | | Wall | `height` | number | 墙体高度。 | | Wall | `thickness` | number | 墙体厚度；当前输出为 `0.0`，因为识别的是房间内轮廓的边。 | | Door | `wall_id` | string | 门所属墙体的标识符，例如 `wall_0`，应引用当前文件中已有的墙体。 | | Door | `position_x, position_y, position_z` | number | 门洞中心点的三维坐标。 | | Door | `width` | number | 门洞沿所属墙体方向的宽度。 | | Door | `height` | number | 门洞的垂直高度。 | | Window | `wall_id` | string | 窗所属墙体的标识符，例如 `wall_4`，应引用当前文件中已有的墙体。 | | Window | `position_x, position_y, position_z` | number | 窗洞中心点的三维坐标。 | | Window | `width` | number | 窗洞沿所属墙体方向的宽度。 | | Window | `height` | number | 窗洞的垂直高度。 | | Bbox | `class` | string | 物体类别，例如 `chair`、`sofa`、`carpet`、`coffee_table`。 | | Bbox | `position_x, position_y, position_z` | number | 三维包围盒中心点坐标。 | | Bbox | `angle_z` | number | 包围盒绕 Z 轴的旋转角，即水平方向朝向。 | | Bbox | `scale_x` | number | 包围盒局部 X 轴方向的完整尺寸，非半尺寸。 | | Bbox | `scale_y` | number | 包围盒局部 Y 轴方向的完整尺寸，非半尺寸。 | | Bbox | `scale_z` | number | 包围盒局部 Z 轴方向的完整尺寸，即高度。 | 解析建议：按行读取。`class` 可能含空格（如 `dining chair`），不要按第一个逗号切分；应从右侧取 7 个数字，左侧整段作为 `class`。`class` 一般无引号。数字为浮点。 格式示意： ``` wall_0=Wall(1.6857,-4.4625,0.0,4.6798,-4.4474,0.0,2.73,0.0) door_0=Door(wall_0,3.1734,-4.4550,1.05,1.3852,2.1) window_0=Window(wall_4,5.6622,-1.0338,1.65,0.6883,1.5) bbox_0=Bbox(carpet,-3.009,4.371,-1.401,-1.5708,5.718,6.734,0.109) ``` **常见 class** | class | 中文 | | --- | --- | | 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 | 玄关柜 | | cupboard | 斗柜 | | 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: 空间理解任务产物。仅任务成功时返回。`resultSslUrl` 指向 UTF-8 文本（DSL），含 Wall / Door / Window / Bbox，需自行下载解析。 parameters: rendercloud_SessionId: name: sessionId in: path required: true description: 实时渲染流会话 ID。 schema: type: string responses: rendercloud_BadRequest: description: 请求参数无效。 content: application/+json: schema: $ref: '#/components/schemas/rendercloud_ApiError' examples: invalidArgument: summary: 参数无效 description: 请求体缺少必要字段或字段值不合法。 value: code: 400 message: requestId 不能为空 status: INVALID_ARGUMENT details: reason: INVALID_ARGUMENT domain: render usdContentEmpty: summary: OpenUSD 内容为空 description: 提交渲染或创建实时流时，`usdContent` 为空。 value: code: 400 message: OpenUSD 内容不能为空 status: INVALID_ARGUMENT details: reason: USD_CONTENT_EMPTY domain: render openUsdParseError: summary: OpenUSD 解析失败 description: '`usdContent` 不是合法 Base64，或解码后的 OpenUSD 内容无法解析。' value: code: 400 message: OpenUSD 内容解析失败 status: INVALID_ARGUMENT details: reason: OPENUSD_PARSE_ERROR domain: render rendercloud_NotFound: description: 资源不存在。 content: application/+json: schema: $ref: '#/components/schemas/rendercloud_ApiError' examples: taskNotFound: summary: 任务不存在 description: 轮询离线渲染任务时，`operationId` 对应任务不存在。 value: code: 404 message: 任务不存在 status: NOT_FOUND details: reason: TASK_NOT_FOUND domain: render sessionNotFound: summary: 会话不存在 description: 实时渲染会话不存在、已关闭或已被清理。 value: code: 404 message: 会话不存在 status: NOT_FOUND details: reason: SESSION_NOT_FOUND domain: render rendercloud_Conflict: description: 重复请求。 content: application/+json: schema: $ref: '#/components/schemas/rendercloud_OperationError' examples: duplicateRequest: summary: requestId 重复 description: 同一用户在 1 分钟内重复提交相同 `requestId`。 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: 请求被限流。 content: application/+json: schema: $ref: '#/components/schemas/rendercloud_ApiError' examples: rateLimited: summary: 请求频率超限 description: 用户维度请求频率超过当前接口限制。 value: code: 429 message: 请求频率超限 status: RESOURCE_EXHAUSTED details: reason: RATE_LIMITED domain: render rendercloud_InternalServerError: description: 渲染服务内部错误。 content: application/+json: schema: $ref: '#/components/schemas/rendercloud_ApiError' examples: renderInternalError: summary: 渲染失败 description: 任务创建、OpenUSD 转换、渲染下发或实时会话更新失败。 value: code: 500 message: 渲染失败 status: INTERNAL details: reason: INTERNAL_ERROR domain: render requestBodies: {} securitySchemes: AuthorizationHeader: type: apiKey description: 开放平台访问凭证。API key 鉴权,在 Header 中增加 Authorization，值为平台申请的 API key，无需 Bearer 前缀。 name: Authorization in: header OusTokenV2: type: apiKey description: 由「获取 OUS 上传凭证」返回的 `ousToken`；仅用于请求 `globalDomain` 上的 OUS 接口（与开放平台 `Authorization` 无关）。 name: ous-token-v2 in: header x-tagGroups: - name: 资产 tags: - Asset - name: 世界 tags: - World - SpatialUnderstanding - name: Lux3D tags: - Lux3D - name: 渲染云 tags: - RenderCloudOpenUSDGuide - RenderCloud