openapi: 3.0.3 info: title: AHOLO Open API version: 1.0.0 description: >- 本文档为 AHOLO OpenAPI 说明，**侧重世界重建与世界生成**：从图片、视频等资源发起 **3D 高斯溅射（3DGS）世界重建**，或使用文案与图片发起 **世界生成（Spatial Gen）**，并支持按 worldId **查询详情**与**分页列表**等。请在请求头按平台约定携带 `Authorization`（见各接口安全定义）。默认网关地址见 **Servers**。 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: RenderCloud description: OpenUSD 渲染云接口 x-displayName: 渲染云 - name: Lux3D description: Lux3D 3D生成服务：创建图生3D任务、创建文生3D任务、创建模型材质重绘任务、查询任务状态。 x-displayName: Lux3D 3D生成 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 /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}` 一致。**输入规则**：若 `resources` 中含有图片类资源（`type=image` 或省略 `type`），则图片类条数须 **至少 20 条**；仅使用视频时请将每条资源的 `type` 设为 `video`（此时不按「至少 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`' value: name: 客厅重建 resources: - url: https://cdn.example.com/input/room-001.mp4 type: video taskQuality: high scene: space createWorldWithImages: description: 多图：须 ≥20 条 image（或省略 type 按图计），此处为结构示意，真实调用需补全 20+ 条 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 /world/v1/generations: post: tags: - World summary: 创建 3DGS 世界生成任务 description: >- 异步创建一条3DGS 世界生成任务（Spatial Gen）。当前 **室内空间** 场景效果更成熟、更稳定，建议优先用于室内。也允许提交 **非室内** 类文案或素材，但非室内生成仍处于 **Beta**，质量与一致性可能明显弱于室内，请按需评估风险。受理成功后返回 `WorldAsyncOperation`（仅含 `worldId`）。若 `resources` 中含图片类资源（`type` 为 image 或未传时按图片处理），最多允许 1 张图片。 operationId: generateWorld parameters: - name: x-source in: header required: false schema: type: string requestBody: description: 生成世界请求体。图片类输入至多 1 条（与 `Project3dgsGenCreateWorld` 校验一致）。 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 /world/v1/{worldId}: get: tags: - World summary: 查询世界详情 description: >- 根据世界 id 查询详情。重建成功且产出可用时，响应中包含 splat（ply/spz）等重建产物的下载地址；若已完成 LOD 后处理，`assets.splats.urls.lodMetaPath` 将包含 LOD 分块元数据文件的下载地址。 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: success: summary: 查询成功 description: success 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: {} '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 /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 /rendercloud/v1/openusd-format: get: tags: - RenderCloud summary: 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 Scope "Render" { def RenderSettings "MainRenderSettings" { ... } } ``` 支持 `def` 定义完整场景，也支持 `over` 在实时增量推送中覆盖已有 Prim。 ## Stage 元数据 | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | `defaultPrim` | `token` 字符串 | 否 | 默认根 Prim 名称，如 `"World"` | | `doc` | 三引号字符串 | 否 | 文档说明；解析后保留，不参与渲染 | `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` 取路径最后一段。`targetPrimPath`（如 ``、``）可选。 ## Camera 完整场景中使用遍历顺序遇到的第一个相机；实时 Patch 中使用第一个带相机属性的 `over` 节点。 | 属性 | 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` 时，使用第一个。 ## 实时增量 Patch 实时增量推送只更新相机，不重建完整场景。Patch 使用 `over`，路径应与创建会话时的 Prim 层级一致。 ```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) ) } } } ``` ## 已支持 Prim / 属性 | Prim 类型 | 支持 | 关键属性 / 元数据 | |-----------|------|-------------------| | `Xform` | 支持 | `xformOp:transform`, `xformOpOrder` | | `Mesh` | 支持 | 元数据 `payload` | | `ParticleField3DGaussianSplat` | 支持 | 元数据 `payload` | | `Camera` | 支持 | 相机参数和位姿 | | `RenderSettings` | 支持 | `camera`, `resolution` | | `Scope` | 支持 | 作为层级容器 | | 其他 USD 类型 | 忽略 | 不参与渲染 | ## 限制与常见错误 | 项 | 说明 | |----|------| | 非完整 USD | 不支持 `references`、`subLayers`、`variantSets`、材质网络等标准 USD 合成能力 | | 多相机 / 多 RenderSettings | 使用遍历顺序遇到的第一个 | | 未知属性 | 忽略，不报错 | | 语法错误 | 未闭合 `{}`、非法属性值等会导致解析失败 | | 资产不存在 | `payload` 中引用的资产不存在时，渲染可能失败或缺少对应资产 | operationId: describeRenderCloudOpenUsdFormat responses: '200': description: OpenUSD 格式说明文档条目。该条目用于展示文档，不对应需要调用的业务接口。 content: text/markdown: schema: type: string x-scalar-order: 0 /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: 1 /rendercloud/v1/streams: post: tags: - RenderCloud summary: 创建或轮询 OpenUSD 实时渲染流 description: | 创建新的实时渲染会话或轮询已有会话状态。 ## 提交模式 当请求中 `operationId` 为空时，创建新会话。需要提供 `requestId` 和 `usdContent`。 返回 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`；轮询时仅传 `operationId`。 required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/rendercloud_RealtimeSessionSubmitRequest' - $ref: '#/components/schemas/rendercloud_OperationPollRequest' examples: submit: summary: 创建实时渲染流 description: 使用 OpenUSD 内容创建实时渲染流。 value: requestId: stream-req-20260515-0001 usdContent: I3VzZGEgMS4wCg== 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: 2 /rendercloud/v1/streams/{sessionId}:push: post: tags: - RenderCloud summary: 推送实时渲染流增量 OpenUSD 内容 description: | 对已建立的实时渲染会话进行增量场景更新。 该接口用于在 WebSocket Streaming 会话就绪后，向服务端推送增量 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: 实时渲染流增量更新请求体。 required: true content: application/json: schema: $ref: '#/components/schemas/rendercloud_RealtimeSessionUpdateRequest' examples: update: summary: 推送增量内容 description: 向已创建的实时渲染流推送增量 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: 3 /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: 4 /rendercloud/v1/mesh-upload-process/task/create: post: tags: - RenderCloud summary: 创建 Mesh 上传解析任务 description: | 创建 Mesh 上传解析任务，用于将原始 Mesh URL 进行解析处理。 该接口用于提交 Mesh 上传解析任务，服务端会对原始 Mesh 进行解析处理。 ## 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 进行解析处理。 value: originMeshUrl: https://example.com/mesh/original.glb 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: 5 /rendercloud/v1/mesh-upload-process/task/get: get: tags: - RenderCloud summary: 查询 RenderCloud 任务状态 description: | 查询指定的 RenderCloud 任务状态和结果。 该接口用于查询任务执行状态和结果。查询时会剔除一些不应该给用户看的数据， 并对输出数据进行包装处理。 ## 调用要求 - `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: 6 /lux3d/v1/generate/img-to-3d/task/create: post: tags: - Lux3D summary: 创建图生3D任务 description: | 创建图生3D任务，输入图片，输出异步任务。请求成功后返回任务 ID taskid，后续可通过查询接口获取任务状态和结果。 若不传 version 参数，系统默认使用 v2.0-preview 版本。 operationId: createImgTo3dTask requestBody: description: 图生3D任务请求体。 content: application/json: schema: $ref: '#/components/schemas/lux3d_ImgTo3dRequest' examples: createTaskDefault: summary: 创建图生3D任务（默认版本） value: img: data:image/png;base64,BASE64_IMAGE_STRING createTaskV10: summary: 创建图生3D任务（v1.0-pro版本） value: img: data:image/png;base64,BASE64_IMAGE_STRING version: v1.0-pro required: true responses: '200': description: 成功时返回任务ID。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: 任务创建成功 value: d: 1256173 m: null c: 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 /lux3d/v1/generate/text-to-3d/task/create: post: tags: - Lux3D summary: 创建文生3D任务 description: | 创建文生3D任务，输入文本或文本+图片，输出异步任务。请求成功后返回任务 ID taskid，后续可通过查询接口获取任务状态和结果。 若不传 version 参数，系统默认使用 v2.0-preview 版本。 operationId: createTextTo3dTask requestBody: description: 文生3D任务请求体。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TextTo3dRequest' examples: textOnlyDefault: summary: 纯文本生成（默认版本） value: prompt: 生成一个高质量的3D木椅模型 style: photorealistic textOnlyV10: summary: 纯文本生成（v1.0-pro版本） value: prompt: 生成一个高质量的3D木椅模型 style: photorealistic version: v1.0-pro textWithImage: summary: 文本+参考图生成 value: prompt: 生成一个高质量的3D木椅模型 style: photorealistic img: data:image/png;base64,BASE64_IMAGE_STRING required: true responses: '200': description: 成功时返回任务ID。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: 任务创建成功 value: d: 1256173 m: null c: 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 /lux3d/v1/generate/material-transfer/task/create: post: tags: - Lux3D summary: 创建模型材质重绘任务 description: | 创建模型材质重绘任务，输入图片和模型URL，输出重绘后的模型对应的异步任务。请求成功后返回任务 ID taskid，后续可通过查询接口获取任务状态和结果。 若不传 version 参数，系统默认使用 v2.0-preview 版本。 operationId: createMaterialTransferTask requestBody: description: 模型材质重绘任务请求体。 content: application/json: schema: $ref: '#/components/schemas/lux3d_MaterialTransferRequest' examples: createTaskDefault: summary: 创建材质重绘任务（默认版本） value: img: data:image/png;base64,BASE64_IMAGE_STRING meshUrl: https://example.com/model.glb createTaskV10: summary: 创建材质重绘任务（v1.0-pro版本） value: img: data:image/png;base64,BASE64_IMAGE_STRING meshUrl: https://example.com/model.glb version: v1.0-pro required: true responses: '200': description: 成功时返回任务ID。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: 任务创建成功 value: d: 1256173 m: null c: 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 /lux3d/v1/generate/task/get: get: tags: - Lux3D summary: 查询生成任务 description: | 根据 taskid 查询图生3D、文生3D或模型材质重绘任务状态和结果。查询结果中的输出内容有效期为 2 小时，建议在任务成功后尽快获取并保存结果。 建议每 10-15 秒轮询查询任务状态。 版本输出差异： - v1.0-pro：首版大模型，具有完整的 PBR 材质属性输出，支持透明材质生成。单格式输出，仅返回 lux3d 格式模型 URL - v2.0-preview（默认）：全新模型架构，重点拓展了对文字、纹理细节的保持能力，不含透明材质。多格式输出，返回 .zip、.glb、.usdz 三种格式 operationId: getTask parameters: - name: taskid in: query description: 任务ID required: true schema: type: string example: '1389513' responses: '200': description: 成功时返回任务状态和结果。 content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskQueryResponse' examples: running: summary: 任务进行中 value: d: taskId: 1389513 outputs: [] status: 1 m: null c: null successV10: summary: 任务成功（v1.0-pro 单格式输出） value: d: taskId: 1256173 outputs: - content: https://cdn.example.com/output/model.lux3d status: 3 m: null c: null successV20: summary: 任务成功（v2.0-preview 多格式输出） value: d: taskId: 1389513 outputs: - content: https://cdn.example.com/output/result.zip - content: https://cdn.example.com/output/model.glb - content: https://cdn.example.com/output/model.usdz status: 3 m: null c: null failed: summary: 任务失败 value: d: taskId: 1389513 outputs: [] status: 4 m: null c: null '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: 5 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 条。含图片时须至少 20 条图片类（`type=image` 或省略 type）；纯视频请显式 `type=video`。 items: $ref: '#/components/schemas/world_WorldResourceItem' taskQuality: $ref: '#/components/schemas/world_WorldOpenApiTaskQuality' scene: $ref: '#/components/schemas/world_WorldOpenApiProjectScene' description: >- 创建 3DGS 世界重建任务的请求体。`scene` 仅支持 model 与 space；`taskQuality` 含义见 `WorldOpenApiTaskQuality`（low 极速预览 / normal 标准 / high 专业）。 **资源条数**：若 `resources` 中出现图片类资源（`type=image` 或省略 `type`，后者按图片计），则图片类至少 **20 条**；若仅使用视频，请为每条资源设置 `type=video`（不触发「至少 20 张图」规则）。 world_WorldOpenApiProjectScene: type: string description: 项目场景类型。model：物体场景；space：室内场景。 example: space enum: - model - space world_WorldOpenApiResourceType: type: string description: >- 输入资源类型，对应业务 ResourceTypeEnum.type。image：图片（映射 IMAGES）；video：视频（映射 VIDEO）。未传时后端按图片类型（IMAGES）处理；兼容历史 JSON 值 `images`。 example: image enum: - image - video 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 及下游处理一致。 example: https://cdn.example.com/input/room-001.jpg type: $ref: '#/components/schemas/world_WorldOpenApiResourceType' description: 单条输入资源（地址与类型）。用于「创建重建任务」时：未传 `type` 按 **图片** 计；纯走视频请传 `video`。 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' lodMetaPath: type: string description: LOD 分块元数据文件的下载地址（对应后端 lodMetaPath）。任务成功且已完成 LOD 后处理时存在，否则为 null。 example: https://cdn.example.com/output/world-001-lod-meta.json semanticsMetadata: $ref: '#/components/schemas/world_WorldSemanticsMetadata' description: 世界重建产物容器。详情接口在任务成功时填充 splats；LOD 元数据与同级的 ply/spz 下载地址一起在 `splats.urls` 中。 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 等资源的下载地址。 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 description: 语义元数据结构占位（相机位姿、比例、偏移等）；当前接口响应中可为空对象，无固定字段。 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 时按图片处理。 items: $ref: '#/components/schemas/world_WorldResourceItem' prompt: type: string description: 文本提示词；可与 resources 同时提供。 example: 现代简约风格，阳光充足的客厅 description: |- 创建 3DGS「生成世界」任务的请求体；支持纯文案、单张图片或图文组合。室内场景效果更成熟；非室内为 Beta（详见同路径 POST 说明）。 至少需提供非空 prompt 或至少一条资源；其中图片类资源（type为 image 或未传时按图片处理）至多 1 张。 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 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 地址。 example: https://example.com/mesh/original.glb 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 lux3d_ImgTo3dRequest: required: - img type: object properties: img: minLength: 1 type: string description: 图片 Base64，建议使用完整 Data URL 格式，例如 data:image/png;base64,... example: data:image/png;base64,BASE64_IMAGE_STRING version: type: string description: Lux3D 版本，支持 v2.0-preview（默认）、v1.0-pro。不传则默认使用 v2.0-preview enum: - v2.0-preview - v1.0-pro default: v2.0-preview example: v2.0-preview description: 图生3D任务请求体。 lux3d_TextTo3dRequest: required: - prompt type: object properties: prompt: minLength: 1 type: string description: 文本提示词 example: 生成一个高质量的3D木椅模型 style: type: string description: >- 风格类型，支持 photorealistic（写实，默认值）、cartoon（卡通）、anime（二次元）、hand_painted（手绘）、cyberpunk（赛博朋克）、fantasy（奇幻）、glass（玻璃质感）。不传则默认使用 photorealistic enum: - photorealistic - cartoon - anime - hand_painted - cyberpunk - fantasy - glass default: photorealistic example: photorealistic img: type: string description: 参考图，建议使用完整 Data URL 格式（可选） example: data:image/png;base64,BASE64_IMAGE_STRING version: type: string description: Lux3D 版本，支持 v2.0-preview（默认）、v1.0-pro。不传则默认使用 v2.0-preview enum: - v2.0-preview - v1.0-pro default: v2.0-preview example: v2.0-preview description: 文生3D任务请求体。 lux3d_MaterialTransferRequest: required: - img - meshUrl type: object properties: img: minLength: 1 type: string description: 图片链接或 Base64，用于材质参考图 example: data:image/png;base64,BASE64_IMAGE_STRING meshUrl: minLength: 1 type: string description: 模型 GLB 文件地址 example: https://example.com/model.glb version: type: string description: Lux3D 版本，支持 v2.0-preview（默认）、v1.0-pro。不传则默认使用 v2.0-preview enum: - v2.0-preview - v1.0-pro default: v2.0-preview example: v2.0-preview description: 模型材质重绘任务请求体。 lux3d_TaskCreateResponse: type: object properties: d: type: integer description: 返回 taskid format: int64 example: 1256173 nullable: true m: type: string description: 提示信息 nullable: true c: type: string description: 状态码 nullable: true description: 任务创建响应体。 lux3d_TaskOutput: type: object properties: content: type: string description: 结果内容（模型文件 URL） nullable: true example: https://cdn.example.com/output/model.lux3d description: 任务输出项。 lux3d_TaskQueryData: type: object properties: taskId: type: integer description: 任务ID format: int64 example: 1389513 outputs: type: array description: 输出列表。v1.0-pro 版本返回单格式输出（lux3d），v2.0-preview 版本返回多格式输出（.zip、.glb、.usdz） items: $ref: '#/components/schemas/lux3d_TaskOutput' status: type: integer description: 任务状态：0-初始化，1-进行中，3-成功，4-失败 format: int32 enum: - 0 - 1 - 3 - 4 example: 3 description: 任务查询数据。 lux3d_TaskQueryResponse: type: object properties: d: $ref: '#/components/schemas/lux3d_TaskQueryData' m: type: string description: 提示信息 nullable: true c: type: string description: 状态码 nullable: true description: 任务查询响应体。 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 - name: 渲染云 tags: - RenderCloud - name: Lux3D tags: - Lux3D