openapi: 3.0.3 info: title: AHOLO World Open API version: 1.0.0 description: >- AHOLO OpenAPI documentation focused on **world reconstruction** and **world generation (Spatial Gen)**: start **3D Gaussian Splatting (3DGS) world reconstruction** from images or videos, or **generate worlds** from text and/or images, then **poll details** and **paginate lists** by `worldId`. Send `Authorization` as required (see each operation’s security definitions). The default gateway is under **Servers**. The sidebar groups operations by **service** (World, Render Cloud, Lux3D, …), then by **tags** within each service. servers: - url: https://api.aholo3d.com description: Aholo Open Platform HTTPS entry (International) tags: - name: Asset description: >- After you obtain an OUS token, run `ousCos*` direct-upload steps on `globalDomain` (COS) under this tag, then use the public URL in downstream business APIs. - name: World description: 3D Gaussian Splatting world reconstruction APIs - name: RenderCloud description: OpenUSD render cloud APIs x-displayName: Render Cloud - name: Lux3D description: >- Lux3D 3D generation service - create image-to-3D tasks, create text-to-3D tasks, create material transfer tasks, and query task status. x-displayName: Lux3D 3D Generation paths: /global/asset/v1/token: get: tags: - Asset summary: Get OUS upload token description: > This endpoint returns upload credentials only; **actual upload happens on OUS `globalDomain`** (not the open-platform gateway), then continue with `ousCosSingleUpload`, `ousCosBlockUploadInit`, `ousCosBlockUploadPart`, and `ousCosUploadStatus` in the **Upload** tag. **Recommended flow:** 1. Call this endpoint to get `ousToken`, `globalDomain` (e.g. `https://ous-sg.kujiale.com`), and `blockSize`. 2. If file size **≤ `blockSize`**: call `ousCosSingleUpload`; if **> `blockSize`**: call `ousCosBlockUploadInit` then `ousCosBlockUploadPart` as needed. 3. Poll `ousCosUploadStatus` until success and you receive `url`. 4. Use the public URL in downstream APIs, e.g. `resources[].url` for **Create 3DGS world reconstruction**. operationId: getUploadToken responses: '200': description: >- On success, the body is the OUS credential (`ousToken`, `globalDomain`, `blockSize`) for direct or multipart upload on the returned COS host. content: application/json: schema: $ref: '#/components/schemas/asset_UploadTokenOuterOpen' examples: success: summary: Token retrieved description: success value: ousToken: globalDomain: https://ous-sg.kujiale.com blockSize: 1048576 '400': description: Parameter/business validation failed (`ApiError`; legacy biz code in `details.metaData.bizCode`) content: application/json: schema: $ref: '#/components/schemas/asset_ApiError' examples: paramsInvalid: summary: Parameter validation failed description: Code 10001 (PARAMS_INVALID) value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo3d.com message: Invalid request parameters metaData: bizCode: '10001' '401': description: Missing or invalid `Authorization`; authentication failed (`ApiError`). content: application/json: schema: $ref: '#/components/schemas/asset_ApiError' examples: notLoggedIn: summary: Not logged in or authentication failed description: Legacy biz code 10004 (NOT_LOGGED_IN) value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo3d.com message: Not logged in metaData: bizCode: '10004' security: - AuthorizationHeader: [] x-scalar-order: 5 /ous/api/v2/single/upload: post: tags: - Asset summary: OUS single-file upload (≤ blockSize) description: >- Use when file size **≤** `blockSize` from the token response; see `requestBody` and `components.schemas.OusCosSingleUploadForm`. operationId: ousCosSingleUpload requestBody: description: Single-file upload request body. content: multipart/form-data: schema: $ref: '#/components/schemas/asset_OusCosSingleUploadForm' encoding: file: contentType: application/octet-stream required: true responses: '200': description: On success, `c` is `0` and `d` contains `taskId`; then poll `GET /ous/api/v2/upload/status`. content: application/json: schema: $ref: '#/components/schemas/asset_OusV2SingleUploadApiResponse' security: - OusTokenV2: [] servers: - url: https://ous-sg.kujiale.com description: '`globalDomain` returned by OUS; production is often this COS host (see the token response).' x-scalar-order: 6 /ous/api/v2/block/upload/init: post: tags: - Asset summary: OUS multipart upload — initialize description: >- Use when file size **>** `blockSize`. **Typical call**: `POST` with required fields in **URL query** (no JSON body). Example: `…/ous/api/v2/block/upload/init?md5=…&blocks=…&size=…&name=…`. operationId: ousCosBlockUploadInit parameters: - name: md5 in: query required: true schema: type: string description: File MD5, lowercase hex example: e99a18c428cb38d5f260853678922e03 - name: blocks in: query required: true schema: type: integer description: Total part count format: int64 example: 11 - name: size in: query required: true schema: type: integer description: File size in bytes format: int64 example: 5942880 - name: name in: query required: true schema: type: string description: Original file name example: photo.jpg - name: metadata in: query required: false schema: type: string description: Metadata (optional) - name: customPrefix in: query required: false schema: type: string description: Custom storage prefix (optional) - name: customFilename in: query required: false schema: type: string description: Custom file name (optional) responses: '200': description: On success, `c` is `0` and `d` contains `taskId`, `lackBlocks`, `progress`, `deduplicated`. content: application/json: schema: $ref: '#/components/schemas/asset_OusV2BlockInitApiResponse' security: - OusTokenV2: [] servers: - url: https://ous-sg.kujiale.com description: '`globalDomain` returned by OUS; production is often this COS host (see the token response).' x-scalar-order: 7 /ous/api/v2/block/upload/part: post: tags: - Asset summary: OUS multipart upload — upload one part description: Call once per part; see `OusCosBlockUploadPartForm`. operationId: ousCosBlockUploadPart requestBody: description: Single-part upload request body. content: multipart/form-data: schema: $ref: '#/components/schemas/asset_OusCosBlockUploadPartForm' encoding: file: contentType: application/octet-stream required: true responses: '200': description: On success, `c` is `0` and `d` is `null`. For the same file, limit concurrent part uploads to 2. content: application/json: schema: $ref: '#/components/schemas/asset_OusV2BlockPartApiResponse' security: - OusTokenV2: [] servers: - url: https://ous-sg.kujiale.com description: '`globalDomain` returned by OUS; production is often this COS host (see the token response).' x-scalar-order: 8 /ous/api/v2/upload/status: get: tags: - Asset summary: OUS — poll upload status description: >- Poll the upload task; `d` differs for single-file vs multipart (see `oneOf` in the response schema). Send only `ous-token-v2`, no body. Poll about every ≥200ms for ~5s total. operationId: ousCosUploadStatus responses: '200': description: >- On success, `c` is `0`; `d` is single-file or multipart status/result (`status=5` is success; see embedded fields and status table). content: application/json: schema: $ref: '#/components/schemas/asset_OusV2UploadStatusApiResponse' security: - OusTokenV2: [] servers: - url: https://ous-sg.kujiale.com description: '`globalDomain` returned by OUS; production is often this COS host (see the token response).' x-scalar-order: 9 /global/world/v1/reconstructions: post: tags: - World summary: Create 3DGS world reconstruction job description: > Creates an async 3DGS world reconstruction job. On acceptance, returns `WorldAsyncOperation` with `worldId` only (same as **Get world details** `{worldId}`). **Rules**: if `resources` include images (`type=image` or omit `type`), need **≥20** image entries; for video-only, set each `type` to `video`. operationId: createWorld parameters: - name: x-source in: header required: false schema: type: string requestBody: description: Create-job body; when using images, meet the count rules in `CreateWorldRequest`. content: application/json: schema: $ref: '#/components/schemas/world_CreateWorldRequest' examples: createWorldWithVideo: description: 'Single video + indoor scene; set explicit `type: video`' value: name: Living room reconstruction resources: - url: https://cdn.example.com/input/room-001.mp4 type: video taskQuality: high scene: space createWorldWithImages: description: >- Multi-image: need ≥20 `image` entries (or omit `type` to count as image). Example is truncated; real calls need 20+ items. value: name: Living room reconstruction resources: - url: https://cdn.example.com/in/1.jpg type: image - url: https://cdn.example.com/in/2.jpg type: image taskQuality: high scene: space required: true responses: '200': description: 'Accepted: returns `WorldAsyncOperation` with `worldId`.' content: application/json: schema: $ref: '#/components/schemas/world_WorldAsyncOperation' examples: success: summary: Accepted for processing description: success value: worldId: A1b2C3d4E5 '400': description: >- Invalid body/parameters, insufficient credits, etc. (`ApiError`; legacy biz code in `details.metaData.bizCode`) content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: paramsInvalid: summary: Invalid parameters / body description: Code 10001 (PARAMS_INVALID) value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo3d.com message: Invalid request parameters metaData: bizCode: '10001' insufficientCredits: summary: Insufficient credits description: Legacy biz code 11003; may not apply if create does not charge credits. value: code: 400 message: insufficient credits to complete task status: FAILED_PRECONDITION details: reason: BIZ_11003 domain: api.aholo3d.com message: insufficient credits to complete task metaData: bizCode: '11003' taskMattingError: summary: Other task error (example) description: Legacy biz code 11004; may not occur on this path. value: code: 400 message: matting error status: FAILED_PRECONDITION details: reason: BIZ_11004 domain: api.aholo3d.com message: matting error metaData: bizCode: '11004' '401': description: Missing or invalid `Authorization`; authentication failed (`ApiError`). content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: notLoggedIn: summary: Not logged in or authentication failed description: Legacy biz code 10004 (NOT_LOGGED_IN) value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo3d.com message: Not logged in metaData: bizCode: '10004' '429': description: Global task concurrency or rate limit (`ApiError`) content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: taskGlobalRateLimit: summary: Global long-task concurrency limit description: Legacy biz code 11001 value: code: 429 message: task global rate limit status: RESOURCE_EXHAUSTED details: reason: BIZ_11001 domain: api.aholo3d.com message: task global rate limit metaData: bizCode: '11001' security: - AuthorizationHeader: [] x-scalar-order: 10 /global/world/v1/generations: post: tags: - World summary: Create 3DGS world generation job description: >- Creates an async 3DGS world generation job (Spatial Gen). **Indoor** scenes are more mature and stable today; non-indoor input is allowed but still **Beta** and may be materially weaker than indoor—assess risk accordingly. On acceptance returns `WorldAsyncOperation` (`worldId` only). At most **one** image-type resource (`type=image` or omitted counts as image). operationId: generateWorld parameters: - name: x-source in: header required: false schema: type: string requestBody: description: Generation request body; at most one image-type entry (same as `Project3dgsGenCreateWorld`). content: application/json: schema: $ref: '#/components/schemas/world_GenerateWorldRequest' examples: generateWorldRequest: summary: Text + image example description: generateWorldRequest value: name: Living room generation cover: https://cdn.example.com/cover/gen-cover.jpg prompt: Modern minimalist living room resources: - url: https://cdn.example.com/input/room.jpg type: image required: true responses: '200': description: 'Accepted: returns `WorldAsyncOperation` with `worldId`.' content: application/json: schema: $ref: '#/components/schemas/world_WorldAsyncOperation' examples: success: summary: Accepted for processing description: success value: worldId: B2c3D4e5F6 '400': description: Invalid body/parameters or other business errors (`ApiError`) content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: paramsInvalid: summary: Invalid parameters / body description: Code 10001 (PARAMS_INVALID) value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo3d.com message: Invalid request parameters metaData: bizCode: '10001' '401': description: Missing or invalid `Authorization`; authentication failed (`ApiError`). content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: notLoggedIn: summary: Not logged in or authentication failed description: Legacy biz code 10004 (NOT_LOGGED_IN) value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo3d.com message: Not logged in metaData: bizCode: '10004' security: - AuthorizationHeader: [] x-scalar-order: 15 /global/world/v1/{worldId}: get: tags: - World summary: Get world details description: >- Get details by world id. When reconstruction succeeds, splat (ply/spz) URLs may be present; after LOD post-processing, `assets.splats.urls.lodMetaPath` has LOD chunk metadata. operationId: getWorldDetail parameters: - name: worldId in: path description: World id (same as `WorldAsyncOperation.worldId` from create) required: true schema: type: string example: A1b2C3d4E5 responses: '200': description: On success, the body is a world detail object. content: application/json: schema: $ref: '#/components/schemas/world_WorldDetail' examples: success: summary: OK description: success value: worldId: A1b2C3d4E5 name: Living room reconstruction cover: https://cdn.example.com/cover/world-001.jpg scene: space createTime: 1699339916000 updateTime: 1699340120000 status: SUCCEEDED progress: 1 assets: splats: urls: plyPath: https://cdn.example.com/output/world-001.ply spzPath: https://cdn.example.com/output/world-001.spz lodMetaPath: https://cdn.example.com/output/world-001-lod-meta.json semanticsMetadata: {} '400': description: Path parameter validation or other business errors (`ApiError`) content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: paramsInvalid: summary: Path parameter validation failed description: Code 10001 value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo3d.com message: Invalid request parameters metaData: bizCode: '10001' '401': description: Missing or invalid `Authorization`; authentication failed (`ApiError`). content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: notLoggedIn: summary: Not logged in or authentication failed description: Legacy biz code 10004 (NOT_LOGGED_IN) value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo3d.com message: Not logged in metaData: bizCode: '10004' '403': description: Access denied (`ApiError`) content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: noPermission: summary: Forbidden description: Legacy biz code 12003 value: code: 403 message: no permission status: PERMISSION_DENIED details: reason: BIZ_12003 domain: api.aholo3d.com message: no permission metaData: bizCode: '12003' '404': description: World not found (`ApiError`) content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: projectNotExist: summary: World (project) not found description: Legacy biz code 12001 value: code: 404 message: project not exist status: NOT_FOUND details: reason: BIZ_12001 domain: api.aholo3d.com message: project not exist metaData: bizCode: '12001' security: - AuthorizationHeader: [] x-scalar-order: 20 /global/world/v1/list: post: tags: - World summary: Paginated list of my worlds description: Paginated list of 3DGS worlds for the current account. operationId: getMyWorldList requestBody: description: Pagination and filters. content: application/json: schema: $ref: '#/components/schemas/world_WorldListQueryRequest' examples: listWorldRequest: description: 'Example: first page, 20 per page, filter RUNNING and SUCCEEDED.' value: pageNum: 0 pageSize: 20 statusList: - RUNNING - SUCCEEDED required: true responses: '200': description: On success, the body is a paged list (`pageNum`, `pageSize`, rows, etc.). content: application/json: schema: $ref: '#/components/schemas/world_WorldPagedList' examples: success: summary: OK description: success value: pageNum: 0 pageSize: 20 count: 1 totalCount: 1 hasMore: false result: - worldId: A1b2C3d4E5 name: Living room reconstruction cover: https://cdn.example.com/cover/world-001.jpg scene: space createTime: 1699339916000 updateTime: 1699340120000 status: RUNNING progress: 0.45 '400': description: Pagination parameter validation failed (`ApiError`) content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: paramsInvalid: summary: Body / parameter validation failed description: Code 10001 value: code: 400 message: Invalid request parameters status: INVALID_ARGUMENT details: reason: BIZ_10001 domain: api.aholo3d.com message: Invalid request parameters metaData: bizCode: '10001' '401': description: Missing or invalid `Authorization`; authentication failed (`ApiError`). content: application/json: schema: $ref: '#/components/schemas/world_ApiError' examples: notLoggedIn: summary: Not logged in or authentication failed description: Legacy biz code 10004 (NOT_LOGGED_IN) value: code: 401 message: Not logged in status: UNAUTHENTICATED details: reason: BIZ_10004 domain: api.aholo3d.com message: Not logged in metaData: bizCode: '10004' security: - AuthorizationHeader: [] x-scalar-order: 30 /global/rendercloud/v1/openusd-format: get: tags: - RenderCloud summary: RenderCloud OpenUSD format guide description: > This documentation entry explains the OpenUSD/USDA format accepted by `usdContent`. `usdContent` must be transmitted as: ```text usdContent = Base64(UTF-8(USDA text)) ``` Files should start with `#usda 1.0` and use UTF-8 encoding. The service parses cameras, external asset references, and render settings from the scene. Unsupported Prim types or attributes are ignored; syntax errors cause the job or session to fail. ## Use Cases | Scenario | API | `usdContent` | Description | |----------|-----|--------------|-------------| | Offline render submit | `POST /global/rendercloud/v1/jobs` | Full USDA scene | Parses camera, Mesh, 3DGS, and RenderSettings, then starts offline rendering | | Realtime render creation | `POST /global/rendercloud/v1/streams` | Full USDA scene | Parses the full scene and creates a realtime rendering stream | | Realtime render patch | `POST /global/rendercloud/v1/streams/{sessionId}:push` | Patch USDA using `over` | Parses camera-related fields and pushes realtime updates | ## Recommended Top-Level Structure ```usda #usda 1.0 ( defaultPrim = "World" ) def Xform "World" { def Xform "MeshModel1" { ... } def Xform "Cameras" { def Camera "MainCamera" { ... } } } def Scope "Render" { def RenderSettings "MainRenderSettings" { ... } } ``` Use `def` for full scenes. Use `over` for realtime patch updates. ## Stage Metadata | Field | Type | Required | Description | |-------|------|----------|-------------| | `defaultPrim` | `token` string | No | Default root Prim name, for example `"World"` | | `doc` | Triple-quoted string | No | Documentation text; retained after parsing and not used for rendering | Standard Stage fields such as `upAxis` and `metersPerUnit` are ignored if present. ## Xform `def Xform` wraps models or cameras and applies transform matrices to child Prims. | Attribute | USDA Type | Required | Description | |-----------|-----------|----------|-------------| | `matrix4d xformOp:transform` | `matrix4d` | No | 4x4 transform matrix | | `uniform token[] xformOpOrder` | `token[]` | No | Recommended value: `["xformOp:transform"]` | The matrix follows the USD row-vector convention. Translation is stored in the fourth row: ```usda matrix4d xformOp:transform = ( (m00, m01, m02, m03), (m10, m11, m12, m13), (m20, m21, m22, m23), (m30, m31, m32, m33) ) ``` ## External Assets Mesh: ```usda def Mesh "myMesh" ( payload = @manycore:/mesh/{meshId}@ ) { } ``` 3D Gaussian Splatting: ```usda def ParticleField3DGaussianSplat "MyGaussianSplat" ( payload = @manycore:/mesh/{meshId}@ ) { } ``` The `assetPath` in `payload` references an uploaded asset. `meshId` is taken from the final path segment. `targetPrimPath`, such as `` or ``, is optional. ## Camera Full scenes use the first camera found during traversal. Realtime patches use the first `over` node containing camera attributes. | Attribute | USDA Type | Required | Description | |-----------|-----------|----------|-------------| | `token projection` | `token` | No | Projection type, for example `"perspective"` | | `float2 clippingRange` | `(near, far)` | No | Near and far clipping planes | | `float focalLength` | `float` | No | Focal length in mm | | `float focusDistance` | `float` | No | Focus distance | | `float fStop` | `float` | No | Aperture f-number | | `float horizontalAperture` | `float` | No | Horizontal aperture in mm | | `float verticalAperture` | `float` | No | Vertical aperture in mm | | `matrix4d xformOp:transform` | `matrix4d` | No | Camera pose | | `uniform token[] xformOpOrder` | `token[]` | No | Recommended value: `["xformOp:transform"]` | ## RenderSettings `def RenderSettings` should be placed under `def Scope "Render"`. | Attribute | USDA Type | Required | Description | |-----------|-----------|----------|-------------| | `rel camera` | Prim path | No | Active camera path, for example `` | | `int2 resolution` | `(width, height)` | Required for offline rendering | Output resolution | Offline rendering reads the output resolution from `RenderSettings.resolution`, with Camera `resolution` supported as a compatibility fallback. Width and height must be positive, and neither side may exceed the server-side configured limit. The default limit is 4500 pixels. If multiple `RenderSettings` Prims exist, the first one is used. ## Realtime Patch Realtime patch updates only the camera. Use `over` and keep the Prim path consistent with the scene used to create the session. ```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) ) } } } ``` ## Supported Prims | Prim Type | Support | Key Attributes / Metadata | |-----------|---------|---------------------------| | `Xform` | Supported | `xformOp:transform`, `xformOpOrder` | | `Mesh` | Supported | `payload` metadata | | `ParticleField3DGaussianSplat` | Supported | `payload` metadata | | `Camera` | Supported | Camera parameters and pose | | `RenderSettings` | Supported | `camera`, `resolution` | | `Scope` | Supported | Hierarchy container | | Other USD types | Ignored | Not used for rendering | ## Limitations | Item | Description | |------|-------------| | Full USD composition | `references`, `subLayers`, `variantSets`, material networks, and similar composition features are not supported | | Multiple cameras / RenderSettings | The first one found during traversal is used | | Unknown attributes | Ignored without error | | Syntax errors | Unclosed braces or invalid attribute values cause parsing failure | | Missing asset | Rendering may fail or miss the referenced asset | operationId: describeRenderCloudOpenUsdFormat responses: '200': description: OpenUSD format documentation entry. This entry is for documentation display and is not a business API call. content: text/markdown: schema: type: string x-scalar-order: 0 /global/rendercloud/v1/jobs: post: tags: - RenderCloud summary: Submit or poll an OpenUSD offline render job description: > Submit an OpenUSD offline render job or poll the status of an existing job. ## Submit mode When `operationId` is empty, a new job is submitted. `requestId` and Base64-encoded `usdContent` are required. The output resolution is read from OpenUSD `RenderSettings.resolution`, with Camera `resolution` supported as a compatibility fallback. Width and height must be positive, and neither side may exceed the server-side configured limit. The default limit is 4500 pixels. The server returns HTTP 202 with `{operationId, metaData:null, done:false, result:null, error:null}`. The `operationId` is the render task ID. `requestId` is generated by the caller and used for request tracing and records. The server applies a 1-minute idempotency guard for the same user and the same `requestId`. If the same user submits the same `requestId` again within 1 minute, the API returns 409 `ALREADY_EXISTS`. ## Poll mode When `operationId` is present, the same POST endpoint polls the job status. - Processing: `done=false` - Succeeded: `done=true + result.taskId/resultUrl` - Failed: `done=true + error` ## Rendering constraints This API does not accept server-side rendering template parameters. The service selects a fixed offline rendering pipeline according to the OpenUSD content and output resolution. ## REST response statuses | HTTP status | Scenario | Response | |-----------|------|---------| | `202` | Submit mode | Job accepted; returns `operationId` for polling | | `200` | Poll mode | Returns current `Operation`; completed responses include `resultUrl` | | `400` | Invalid argument | Missing `requestId` or `usdContent`; missing/invalid OpenUSD resolution; invalid Base64; or OpenUSD parse failure | | `404` | Not found | No job exists for `operationId` | | `409` | Duplicate request | The same user submitted the same `requestId` again within 1 minute | | `429` | Rate limited | User-level offline render frequency exceeded | | `500` | Internal error | Job creation, conversion, or render dispatch failed | operationId: runRenderCloudOfflineJob requestBody: description: >- Offline render submit or poll request body. Submit with `requestId` and `usdContent`; poll with only `operationId`. required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/rendercloud_OfflineRenderSubmitRequest' - $ref: '#/components/schemas/rendercloud_OperationPollRequest' examples: submit: summary: Submit an offline render job description: Create an offline render job from OpenUSD content. Output resolution is read from OpenUSD resolution. value: requestId: render-req-20260515-0001 usdContent: I3VzZGEgMS4wCg== poll: summary: Poll offline render result description: Use the `operationId` returned by submit to query the job status or result. value: operationId: '1305220918472257536' responses: '200': description: Current offline render operation status. content: application/+json: schema: oneOf: - $ref: '#/components/schemas/rendercloud_OfflineRenderProcessingOperation' - $ref: '#/components/schemas/rendercloud_OfflineRenderSuccessOperation' - $ref: '#/components/schemas/rendercloud_OperationError' examples: processing: summary: Job processing description: The offline render job is still processing. value: operationId: '1305220918472257536' metaData: null done: false result: null error: null success: summary: Render succeeded description: The offline render job finished and returned the rendered image URL. value: operationId: '1305220918472257536' metaData: null done: true result: taskId: '1305220918472257536' resultUrl: https://example.com/render/result.png error: null failed: summary: Render failed description: The offline render job failed and returned an error. value: operationId: '1305220918472257536' metaData: null done: true result: null error: code: 500 message: >- code: INTERNAL, details: ErrorDetails(reason=INTERNAL_ERROR, message=null, domain=render, metaData=null) status: INTERNAL details: reason: INTERNAL_ERROR domain: render '202': description: Offline render job accepted and still processing. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_OfflineRenderProcessingOperation' examples: processing: summary: Job processing description: The offline render job has been created but is not finished yet. value: operationId: '1305220918472257536' metaData: null done: false result: null error: null '400': $ref: '#/components/responses/rendercloud_BadRequest' '404': $ref: '#/components/responses/rendercloud_NotFound' '409': $ref: '#/components/responses/rendercloud_Conflict' '429': $ref: '#/components/responses/rendercloud_TooManyRequests' '500': $ref: '#/components/responses/rendercloud_InternalServerError' x-scalar-order: 1 /global/rendercloud/v1/streams: post: tags: - RenderCloud summary: Create or poll an OpenUSD realtime render stream description: > Create a realtime render session or poll an existing session. ## Submit mode When `operationId` is empty, a new session is created. `requestId` and `usdContent` are required. The server returns HTTP 202 with `{operationId, metaData:null, done:false, result:null, error:null}`. The returned `operationId` is the `sessionId`. ## Poll mode When `operationId` is present, poll the session status. Recommended polling interval is 2 seconds; timeout is 120 seconds. When `status` is `ACTIVE`, `result` contains `host`, `nodeId`, `streamId`, and `token`, which are required to open the WebSocket Streaming connection. ## REST response statuses | HTTP status | Scenario | Response | |-----------|------|---------| | `202` | Submit mode | Session is being created; returns `operationId` for polling | | `200` | Poll mode | Current `Operation`; processing is `done=false`, success is `done=true + result`, failure is `done=true + error` | | `400` | Invalid argument | Request body is missing required fields or contains invalid values | | `404` | Not found | `operationId` or session does not exist | | `429` | Rate limited | Request frequency exceeded | | `500` | Internal error | Internal server error | ## WebSocket Streaming protocol ### Connection URL ``` wss://{host}/streaming/ws/session?nid={encodeURIComponent(nodeId)}&token={encodeURIComponent(token)} ``` Set `ws.binaryType = 'blob'` when creating the WebSocket; otherwise image frames cannot be received as Blob objects. ### Handshake Immediately after WebSocket `onopen`, send: ```json {"type":3,"slaveInit":{"masterStreamingId":"{streamId}","receiveImage":true}} ``` | Field | Value | Description | |------|-----|------| | type | fixed `3` | Slave initialization message | | slaveInit.masterStreamingId | `{streamId}` | The streamId returned by this API | | slaveInit.receiveImage | fixed `true` | Receive rendered images | ### Server messages JSON status messages are received when `typeof event.data === 'string'`. Binary image messages are JPEG Blob objects. Convert the Blob with `FileReader.readAsDataURL(blob)` before assigning it to an `` source. Status codes: | code | Meaning | Connection state change | |------|------|-------------| | `"0"` | Initialized | Success | | `"1000"` | Node overloaded | Error | | `"1001"` | Initialization failed | Error | | `"1003"` | Slave limit exceeded | SlaveExceeded | | `"2001"` | Engine render error | No connection state change; only render failure callback | | `"2002"` | Engine process error | No connection state change; only render failure callback | Close the WebSocket first, then call the DELETE API to end the server-side session. operationId: createRenderCloudRealtimeStream requestBody: description: >- Realtime render stream creation or poll request body. Create with `requestId` and `usdContent`; poll with only `operationId`. required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/rendercloud_RealtimeSessionSubmitRequest' - $ref: '#/components/schemas/rendercloud_OperationPollRequest' examples: submit: summary: Create a realtime render stream description: Create a realtime render stream from OpenUSD content. value: requestId: stream-req-20260515-0001 usdContent: I3VzZGEgMS4wCg== poll: summary: Poll realtime render stream description: Use the `operationId` returned by creation to query stream status. value: operationId: '1305220918472257536' responses: '200': description: >- Realtime render stream polling result. When status is ACTIVE, result contains WebSocket connection parameters. content: application/+json: schema: oneOf: - $ref: '#/components/schemas/rendercloud_RealtimeSessionProcessingOperation' - $ref: '#/components/schemas/rendercloud_RealtimeSessionSuccessOperation' - $ref: '#/components/schemas/rendercloud_OperationError' examples: processing: summary: Creating description: The realtime render stream is still initializing. value: operationId: '1305220918472257536' metaData: null done: false result: null error: null success: summary: Created description: The realtime render stream is ready and returns connection parameters. value: operationId: '1305220918472257536' metaData: null done: true result: sessionId: '1305220918472257536' status: ACTIVE currentQueuePosition: 0 host: stream.example.com nodeId: node-01 streamId: stream-1305220918472257536 token: stream-token error: null failed: summary: Creation failed description: The realtime render stream failed to initialize. value: operationId: '1305220918472257536' metaData: null done: true result: null error: code: 500 message: >- code: INTERNAL, details: ErrorDetails(reason=INTERNAL_ERROR, message=null, domain=render, metaData=null) status: INTERNAL details: reason: INTERNAL_ERROR domain: render '202': description: Session creation is in progress. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_RealtimeSessionProcessingOperation' examples: processing: summary: Session creating description: The submit response. `operationId` is the sessionId. value: operationId: '1305220918472257536' metaData: null done: false result: null error: null '400': $ref: '#/components/responses/rendercloud_BadRequest' '404': $ref: '#/components/responses/rendercloud_NotFound' '429': $ref: '#/components/responses/rendercloud_TooManyRequests' '500': $ref: '#/components/responses/rendercloud_InternalServerError' x-scalar-order: 2 /global/rendercloud/v1/streams/{sessionId}:push: post: tags: - RenderCloud summary: Push incremental OpenUSD content to a realtime render stream description: > Apply incremental scene updates to an established realtime render session. This API is used after the WebSocket Streaming session is ready. It pushes Base64-encoded incremental OpenUSD content to the server. The server converts the content into render operations and dispatches it to the realtime render pipeline. ## Requirements - `sessionId` must be the `operationId` returned by `/rendercloud/v1/streams` after creation. - Session status must be `ACTIVE`, otherwise the update is rejected. - `requestId` is generated by the caller for idempotency and request records. - `usdContent` is Base64-encoded incremental OpenUSD content. ## REST response statuses | HTTP status | Scenario | Response | |-----------|------|---------| | `200` | Updated | Returns session ID and current session status | | `400` | Invalid argument | Missing `requestId` or `usdContent`, or invalid request body | | `404` | Not found | No session exists for `sessionId` | | `429` | Rate limited | User-level realtime render frequency exceeded | | `500` | Internal error | Session is not ACTIVE, forwarding failed, or update was rejected by the render pipeline | operationId: pushRenderCloudRealtimeStreamUpdate parameters: - $ref: '#/components/parameters/rendercloud_SessionId' requestBody: description: Realtime render stream incremental update request body. required: true content: application/json: schema: $ref: '#/components/schemas/rendercloud_RealtimeSessionUpdateRequest' examples: update: summary: Push incremental content description: Push incremental OpenUSD content to an existing realtime render stream. value: requestId: stream-update-20260515-0001 usdContent: I3VzZGEgMS4wCg== responses: '200': description: Incremental content pushed successfully. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_RealtimeSessionUpdateResponse' examples: success: summary: Updated description: Session remains ACTIVE and incremental content has been sent to the realtime render pipeline. value: sessionId: '1305220918472257536' status: ACTIVE '400': $ref: '#/components/responses/rendercloud_BadRequest' '404': $ref: '#/components/responses/rendercloud_NotFound' '429': $ref: '#/components/responses/rendercloud_TooManyRequests' '500': $ref: '#/components/responses/rendercloud_InternalServerError' x-scalar-order: 3 /global/rendercloud/v1/streams/{sessionId}: delete: tags: - RenderCloud summary: Close a realtime render stream description: > Close the specified realtime render session and release server-side resources. When closing a realtime render stream, close the WebSocket first, then call this API to end the server-side session. The server releases resources related to the realtime rendering session. ## REST response statuses | HTTP status | Scenario | Response | |-----------|------|---------| | `200` | Closed | `closed=true` means the server found and closed the session; `closed=false` means the session no longer exists or was already cleaned up | | `404` | Not found | The node that owns the session reports that the session does not exist | | `429` | Rate limited | User-level realtime render frequency exceeded | | `500` | Internal error | Forwarding failed or an internal server error occurred | operationId: closeRenderCloudRealtimeStream parameters: - $ref: '#/components/parameters/rendercloud_SessionId' responses: '200': description: Realtime render stream closed. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_RealtimeSessionCloseResponse' examples: closed: summary: Closed description: The server found and closed the session. value: sessionId: '1305220918472257536' closed: true alreadyGone: summary: Session already gone description: The session was already closed, timed out, cleaned up, or is not on the current node. value: sessionId: '1305220918472257536' closed: false '404': $ref: '#/components/responses/rendercloud_NotFound' '429': $ref: '#/components/responses/rendercloud_TooManyRequests' '500': $ref: '#/components/responses/rendercloud_InternalServerError' x-scalar-order: 4 /global/rendercloud/v1/mesh-upload-process/task/create: post: tags: - RenderCloud summary: Create Mesh upload and process task description: | Create a Mesh upload and process task to parse and process the original Mesh URL. This API submits a Mesh upload and process task. The server parses and processes the original Mesh. ## REST response statuses | HTTP status | Scenario | Response | |-----------|------|---------| | `200` | Task created | Returns task ID | | `400` | Invalid argument | `originMeshUrl` missing or invalid | | `500` | Internal error | Task creation or processing failed | operationId: createMeshUploadAndProcessTask requestBody: description: Mesh upload and process task request body. required: true content: application/json: schema: $ref: '#/components/schemas/rendercloud_MeshUploadProcessRequest' examples: submit: summary: Create Mesh upload and process task description: Submit original Mesh URL for parsing and processing. value: originMeshUrl: https://example.com/mesh/original.glb responses: '200': description: Mesh upload and process task created successfully. content: application/json: schema: $ref: '#/components/schemas/rendercloud_TaskCreateResponse' examples: success: summary: Task created description: Returns task ID for subsequent queries. value: success: true data: 1272794 errorMsg: null '400': description: Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/rendercloud_CommonErrorResponse' examples: invalidArgument: summary: Invalid argument description: originMeshUrl missing or invalid. value: success: false data: null errorMsg: originMeshUrl cannot be empty '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/rendercloud_CommonErrorResponse' examples: internalError: summary: Internal error description: Task creation or processing failed. value: success: false data: null errorMsg: System error x-scalar-order: 5 /global/rendercloud/v1/mesh-upload-process/task/get: get: tags: - RenderCloud summary: Query RenderCloud task status description: | Query the status and result of a specified RenderCloud task. This API queries task execution status and results. It filters out data that should not be exposed to users and wraps the output data. ## Requirements - `taskid` must be the task ID returned by the task creation API ## REST response statuses | HTTP status | Scenario | Response | |-----------|------|---------| | `200` | Query succeeded | Returns task details | | `400` | Invalid argument | `taskid` missing or invalid | | `404` | Not found | Specified task ID does not exist | | `500` | Internal error | Query failed | operationId: getRenderCloudInstanceInAholo parameters: - name: taskid in: query required: true description: Task ID. schema: type: integer format: int64 responses: '200': description: Task query succeeded. content: application/json: schema: $ref: '#/components/schemas/rendercloud_TaskQueryResponse' examples: processing: summary: Task processing description: Task is executing. value: success: true data: taskId: 1272794 status: 1 outputs: null errorMsg: null success: summary: Task completed description: Task execution completed, returns processing result. value: success: true data: taskId: 1272794 status: 3 outputs: - content: YYZN2MZVAIQLEPTULM888888 sourceReferId: '607583273' errorMsg: null '400': description: Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/rendercloud_CommonErrorResponse' examples: invalidArgument: summary: Invalid argument description: taskid missing or invalid. value: success: false data: null errorMsg: taskid cannot be empty '404': description: Task not found. content: application/json: schema: $ref: '#/components/schemas/rendercloud_CommonErrorResponse' examples: notFound: summary: Task not found description: Specified task ID does not exist. value: success: false data: null errorMsg: Task not found '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/rendercloud_CommonErrorResponse' examples: internalError: summary: Internal error description: Query failed. value: success: false data: null errorMsg: System error x-scalar-order: 6 /global/lux3d/v1/generate/img-to-3d/task/create: post: tags: - Lux3D summary: Create Image-to-3D Task (International) description: > Create an image-to-3D task. Input an image and output an async task. Returns task ID (taskid) on success, which can be used to query task status and results. This is the international endpoint with /global path prefix. If version parameter is not provided, v2.0-preview is used by default. operationId: createImgTo3dTaskGlobal requestBody: description: Image-to-3D task request body. content: application/json: schema: $ref: '#/components/schemas/lux3d_ImgTo3dRequest' examples: createTaskDefault: summary: Create image-to-3D task (default version) value: img: data:image/png;base64,BASE64_IMAGE_STRING createTaskV10: summary: Create image-to-3D task (v1.0-pro version) value: img: data:image/png;base64,BASE64_IMAGE_STRING version: v1.0-pro required: true responses: '200': description: Returns task ID on success. content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: Task created successfully value: d: 1256173 m: null c: null '401': description: Missing or invalid Authorization header, authentication failed content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] servers: - url: https://api.aholo3d.com description: International Region x-scalar-order: 2 /global/lux3d/v1/generate/text-to-3d/task/create: post: tags: - Lux3D summary: Create Text-to-3D Task (International) description: > Create a text-to-3D task. Input text or text+image and output an async task. Returns task ID (taskid) on success, which can be used to query task status and results. This is the international endpoint with /global path prefix. If version parameter is not provided, v2.0-preview is used by default. operationId: createTextTo3dTaskGlobal requestBody: description: Text-to-3D task request body. content: application/json: schema: $ref: '#/components/schemas/lux3d_TextTo3dRequest' examples: textOnlyDefault: summary: Text-only generation (default version) value: prompt: Generate a high-quality 3D wooden chair model style: photorealistic textOnlyV10: summary: Text-only generation (v1.0-pro version) value: prompt: Generate a high-quality 3D wooden chair model style: photorealistic version: v1.0-pro textWithImage: summary: Text with reference image generation value: prompt: Generate a high-quality 3D wooden chair model style: photorealistic img: data:image/png;base64,BASE64_IMAGE_STRING required: true responses: '200': description: Returns task ID on success. content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: Task created successfully value: d: 1256173 m: null c: null '401': description: Missing or invalid Authorization header, authentication failed content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] servers: - url: https://api.aholo3d.com description: International Region x-scalar-order: 4 /global/lux3d/v1/generate/material-transfer/task/create: post: tags: - Lux3D summary: Create Material Transfer Task (International) description: > Create a material transfer task. Input an image and model URL, output an async task with the repainted model. Returns task ID (taskid) on success, which can be used to query task status and results. This is the international endpoint with /global path prefix. If version parameter is not provided, v2.0-preview is used by default. operationId: createMaterialTransferTaskGlobal requestBody: description: Material transfer task request body. content: application/json: schema: $ref: '#/components/schemas/lux3d_MaterialTransferRequest' examples: createTaskDefault: summary: Create material transfer task (default version) value: img: data:image/png;base64,BASE64_IMAGE_STRING meshUrl: https://example.com/model.glb createTaskV10: summary: Create material transfer task (v1.0-pro version) value: img: data:image/png;base64,BASE64_IMAGE_STRING meshUrl: https://example.com/model.glb version: v1.0-pro required: true responses: '200': description: Returns task ID on success. content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' examples: success: summary: Task created successfully value: d: 1256173 m: null c: null '401': description: Missing or invalid Authorization header, authentication failed content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskCreateResponse' security: - AuthorizationHeader: [] servers: - url: https://api.aholo3d.com description: International Region x-scalar-order: 5 /global/lux3d/v1/generate/task/get: get: tags: - Lux3D summary: Query Generation Task (International) description: > Query image-to-3D, text-to-3D or material transfer task status and results by taskid. The output content in the query result is valid for 2 hours. It is recommended to retrieve and save the results as soon as the task succeeds. It is recommended to poll the task status every 10-15 seconds. This is the international endpoint with /global path prefix. Version output differences: - v1.0-pro: First-generation model with complete PBR material properties output, supports transparent material generation. Single format output, returns only lux3d format model URL - v2.0-preview (default): New model architecture with enhanced text and texture detail preservation, no transparent materials. Multiple format output, returns .zip, .glb, .usdz formats operationId: getTaskGlobal parameters: - name: taskid in: query description: Task ID required: true schema: type: string example: '1389513' responses: '200': description: Returns task status and results on success. content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskQueryResponse' examples: running: summary: Task in progress value: d: taskId: 1389513 outputs: [] status: 1 m: null c: null successV10: summary: Task succeeded (v1.0-pro single format output) value: d: taskId: 1256173 outputs: - content: https://cdn.example.com/output/model.lux3d status: 3 m: null c: null successV20: summary: Task succeeded (v2.0-preview multiple format output) 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: Task failed value: d: taskId: 1389513 outputs: [] status: 4 m: null c: null '401': description: Missing or invalid Authorization header, authentication failed content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskQueryResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/lux3d_TaskQueryResponse' security: - AuthorizationHeader: [] servers: - url: https://api.aholo3d.com description: International Region x-scalar-order: 6 components: schemas: asset_UploadTokenOuterOpen: type: object properties: ousToken: type: string description: 'Upload token. For OUS host requests set header `ous-token-v2: `.' example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... globalDomain: type: string description: OUS global host (no path); upload/part requests go here. example: https://ous-sg.kujiale.com blockSize: type: integer description: Part size threshold (bytes); larger files use multipart. format: int64 example: 1048576 description: OUS credential for direct upload on `globalDomain`; header `ous-token-v2`; full flow under **Upload** `ousCos*`. asset_ApiError: required: - code - details - message - status type: object properties: code: type: integer description: HTTP status code format: int32 example: 403 message: type: string description: Developer-facing error message (English); use `localizedMessage` for user-visible localized text. example: Permission denied to access this resource status: $ref: '#/components/schemas/asset_Code' details: $ref: '#/components/schemas/asset_ErrorDetails' localizedMessage: $ref: '#/components/schemas/asset_LocalizedMessage' help: $ref: '#/components/schemas/asset_Help' description: API error response with status, details, and optional help. asset_Code: type: string description: REST API status code per Google API design guidelines. example: PERMISSION_DENIED enum: - OK - CANCELLED - UNKNOWN - INVALID_ARGUMENT - DEADLINE_EXCEEDED - NOT_FOUND - ALREADY_EXISTS - PERMISSION_DENIED - UNAUTHENTICATED - RESOURCE_EXHAUSTED - FAILED_PRECONDITION - ABORTED - OUT_OF_RANGE - UNIMPLEMENTED - INTERNAL - UNAVAILABLE - DATA_LOSS - PARTIAL_ELEMENT_UPDATE_FAILED asset_ErrorDetails: required: - reason type: object properties: reason: maxLength: 63 pattern: '[A-Z][A-Z0-9_]+[A-Z0-9]' type: string description: Error reason identifier in UPPER_SNAKE_CASE (max 63 characters). example: RESOURCE_NOT_FOUND message: type: string description: Human-readable explanation with error context. nullable: true example: The requested design with ID 12345 does not exist domain: type: string description: Error domain, usually the service that produced the error. nullable: true example: restapi.qunhe.com metaData: type: object additionalProperties: type: string description: Additional metadata as key/value pairs (keys up to 64 chars, pattern /[a-zA-Z0-9-_]/). nullable: true example: '{"instanceLimitPerRequest":"100","currentInstanceCount":"150"}' description: Additional metadata as key/value pairs (keys up to 64 chars, pattern /[a-zA-Z0-9-_]/). nullable: true example: instanceLimitPerRequest: '100' currentInstanceCount: '150' description: 'Error details: reason, domain, and metadata.' asset_Help: required: - desc - url type: object properties: desc: type: string description: Description of the linked help document. example: How to resolve permission denied errors url: type: string description: URL of the help document example: https://docs.example.com/errors/permission-denied description: Help link and description for resolving the error. nullable: true asset_LocalizedMessage: required: - locale - message type: object properties: locale: type: string description: Locale identifier for the message example: zh_CN message: type: string description: Localized error text for end users example: You do not have permission to access this resource description: Localized message for a specific locale. nullable: true asset_OusCosSingleUploadForm: required: - file - md5 type: object properties: md5: type: string description: File MD5, lowercase hex example: d41d8cd98f00b204e9800998ecf8427e file: type: string description: Full file body to upload format: binary description: '`multipart/form-data` fields (client supplies boundary).' asset_OusCosBlockUploadInitRequest: required: - blocks - md5 - name - size type: object properties: md5: type: string description: Whole-file MD5, lowercase hex example: e99a18c428cb38d5f260853678922e03 blocks: minimum: 1 type: integer description: Total parts ≈ ceil(fileSize / blockSize); `blockSize` from token. format: int64 example: 11 size: minimum: 1 type: integer description: File size in bytes format: int64 example: 10616832 name: type: string description: Original file name example: photo.jpg metadata: type: string description: Metadata (optional) customPrefix: type: string description: Custom storage prefix (optional) customFilename: type: string description: Custom file name (optional) description: Multipart init parameter semantics (same as **query** on `POST …/block/upload/init`; not a JSON body). asset_OusCosBlockUploadPartForm: required: - block - file type: object properties: block: minimum: 1 type: integer description: Part index from 1 up to `blocks` from init format: int32 example: 1 file: type: string description: Binary bytes for this part format: binary description: '`multipart/form-data` fields `block` + `file`' asset_OusV2UploadTaskStatus: type: integer description: |- Read `d.status` when polling `GET /ous/api/v2/upload/status`. **Guide**: `5` success (use `url`); `6`/`8` terminal failure—stop polling; others keep polling. | Value | Meaning | Terminal | |---|---|---| | 0 | Draft | No | | 1 | Basic checks done | No | | 2 | Content checks done | No | | 3 | Queued | No | | 4 | Uploading | No | | 5 | Success | **Yes** | | 6 | Failed | **Yes** | | 7 | Reviewing | No | | 8 | Aborted | **Yes** | format: int32 enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 asset_OusV2BusinessErrorCode: type: integer description: |- Use `errorCode` in non-success responses for retries/metrics (field names vary). | Code | Meaning | Suggestion | |---|---|---| | 1 | Config error | Check upload config | | 2 | Bad file size | Check size / parts | | 3 | Bad format | Change format / retry | | 4 | Bad content | Change content | | 5 | Safety check failed | Change asset | | 6 | Upload throttled | Backoff / fewer concurrent | | 7 | Uploading | Poll / retry later | | 8 | Part failed | Retry parts / restart | | 9 | Server limit | Backoff | | 10 | Pool full | Backoff | | 11 | Metadata too large | Shrink metadata | | 12 | Token issue | Re-fetch token / re-init | | 13 | Task issue | New task | format: int32 enum: - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 13 asset_OusV2BlockInitData: required: - taskId type: object properties: taskId: type: integer description: Task id; bound to the token for subsequent status polling. format: int64 example: 123456789 lackBlocks: type: array description: Missing part indexes (`a-b` ranges); `null` if not resuming. nullable: true items: type: string example: 1-3 progress: type: number description: Progress [0,1]; `null` if N/A. format: double nullable: true example: 0.6 deduplicated: type: boolean description: 'Dedup: `true` means file exists—skip parts, poll `status`.' nullable: true example: false description: Multipart init result (V2). asset_OusV2BlockInitApiResponse: required: - c - d type: object properties: c: type: string description: Business code; `0` is success. example: '0' m: type: string description: Message; may be empty. example: '' d: $ref: '#/components/schemas/asset_OusV2BlockInitData' description: 'Init 200 body: when `c` is `0`, `d` has multipart task info.' asset_OusV2SingleUploadData: required: - taskId type: object properties: taskId: type: string description: Upload task id; bound to the token for subsequent status polling. example: task_id description: Returned on single-file success. asset_OusV2SingleUploadApiResponse: required: - c - d type: object properties: c: type: string description: Business code; `0` is success. example: '0' m: type: string description: Message; may be empty. example: '' d: $ref: '#/components/schemas/asset_OusV2SingleUploadData' description: Single-file upload HTTP 200 body (`c` is `0`, `d` contains `taskId`). asset_OusV2BlockPartApiResponse: required: - c - d type: object properties: c: type: string description: Business code; `0` is success. example: '0' m: type: string description: Message; may be empty. d: description: On success `d` is `null`. nullable: true description: Part upload success; `d` null when `c` is 0. Failures see `OusV2BusinessErrorCode` (e.g. 6). asset_OusV2StatusPollDataSingle: type: object properties: status: $ref: '#/components/schemas/asset_OusV2UploadTaskStatus' uploadKey: type: string description: Object key path. example: heihei/2026/02/03/NGA5S6IKBIDN3RSQAAAAAAA8.jpg url: type: string description: Public resource URL. format: uri md5: type: string description: File MD5, lowercase hex. obsTaskId: type: string description: OUS task/object id. example: 3FO4K029K4A3 description: Typical `d` for **single-file** status polling; see `OusV2UploadTaskStatus`. asset_OusV2StatusBlockProgress: type: object properties: obsId: type: string description: Multipart sub-task id. status: $ref: '#/components/schemas/asset_OusV2UploadTaskStatus' progressPercent: type: integer description: Progress percent. format: int32 example: 100 lackBlocks: type: array description: Missing parts (same encoding as init). items: type: string description: Aggregated multipart progress in `d.blockUpload`; see `OusV2UploadTaskStatus`. asset_OusV2StatusPollDataBlock: type: object properties: obsTaskId: type: string description: Task id. status: $ref: '#/components/schemas/asset_OusV2UploadTaskStatus' uploadKey: type: string url: type: string format: uri md5: type: string errorCode: nullable: true allOf: - $ref: '#/components/schemas/asset_OusV2BusinessErrorCode' errorMsg: type: string nullable: true blockUpload: $ref: '#/components/schemas/asset_OusV2StatusBlockProgress' errorInfo: type: string description: Extra error detail; may be null. nullable: true description: Typical `d` for **multipart** polling; see `OusV2UploadTaskStatus` / `OusV2BusinessErrorCode`. asset_OusV2UploadStatusApiResponse: required: - c - d type: object properties: c: type: string description: Business code; `0` is success. example: '0' m: type: string description: Message; may be empty. d: description: '`oneOf` single-file vs multipart shapes.' oneOf: - $ref: '#/components/schemas/asset_OusV2StatusPollDataSingle' - $ref: '#/components/schemas/asset_OusV2StatusPollDataBlock' description: Status poll response; `d` is one of single/multipart shapes; `d.status` in `OusV2UploadTaskStatus`. world_CreateWorldRequest: required: - resources - scene - taskQuality type: object properties: name: type: string description: Display name example: Living room reconstruction cover: type: string description: Cover image URL (optional) example: https://cdn.example.com/cover/custom-cover.jpg resources: minItems: 1 type: array description: >- Input resources (≥1). With images, need ≥20 image entries (`type=image` or omit); video-only: set `type=video`. items: $ref: '#/components/schemas/world_WorldResourceItem' taskQuality: $ref: '#/components/schemas/world_WorldOpenApiTaskQuality' scene: $ref: '#/components/schemas/world_WorldOpenApiProjectScene' description: > Body for **Create 3DGS world reconstruction**. `scene` is `model` or `space`; see `WorldOpenApiTaskQuality` for `taskQuality` (`low` fast preview / `normal` standard / `high` professional). **Counts**: if any image-type resource (`type=image` or omit `type`), need **≥20** image entries; for video-only, set `type=video` on each (no 20-image rule). world_WorldOpenApiProjectScene: type: string description: 'Scene type: `model` object scene; `space` indoor.' example: space enum: - model - space world_WorldOpenApiResourceType: type: string description: 'Resource type: `image` → IMAGES, `video` → VIDEO. Omitted counts as image; legacy `images` accepted.' example: image enum: - image - video world_WorldOpenApiTaskQuality: type: string description: 'Reconstruction quality tier: `low` fast preview; `normal` standard; `high` professional.' example: high enum: - low - normal - high world_WorldResourceItem: required: - url type: object properties: url: minLength: 1 type: string description: Media URL; must match `type` and downstream rules. example: https://cdn.example.com/input/room-001.jpg type: $ref: '#/components/schemas/world_WorldOpenApiResourceType' description: 'One input resource. For reconstruction: omit `type` → image; video-only → `video`.' world_WorldAsyncOperation: required: - worldId type: object properties: worldId: type: string description: World id; use as `{worldId}` in `GET /global/world/v1/{worldId}` to poll status and outputs. example: A1b2C3d4E5 description: 'Async create acceptance: returns `worldId` for polling details until a terminal state.' world_ApiError: required: - code - details - message - status type: object properties: code: type: integer description: HTTP status code format: int32 example: 403 message: type: string description: Developer-facing error message (English); use `localizedMessage` for user-visible localized text. example: Permission denied to access this resource status: $ref: '#/components/schemas/world_Code' details: $ref: '#/components/schemas/world_ErrorDetails' localizedMessage: $ref: '#/components/schemas/world_LocalizedMessage' help: $ref: '#/components/schemas/world_Help' description: API error response with status, details, and optional help. world_Code: type: string description: REST API status code per Google API design guidelines. example: PERMISSION_DENIED enum: - OK - CANCELLED - UNKNOWN - INVALID_ARGUMENT - DEADLINE_EXCEEDED - NOT_FOUND - ALREADY_EXISTS - PERMISSION_DENIED - UNAUTHENTICATED - RESOURCE_EXHAUSTED - FAILED_PRECONDITION - ABORTED - OUT_OF_RANGE - UNIMPLEMENTED - INTERNAL - UNAVAILABLE - DATA_LOSS - PARTIAL_ELEMENT_UPDATE_FAILED world_ErrorDetails: required: - reason type: object properties: reason: maxLength: 63 pattern: '[A-Z][A-Z0-9_]+[A-Z0-9]' type: string description: Error reason identifier in UPPER_SNAKE_CASE (max 63 characters). example: RESOURCE_NOT_FOUND message: type: string description: Human-readable explanation with error context. nullable: true example: The requested design with ID 12345 does not exist domain: type: string description: Error domain, usually the service that produced the error. nullable: true example: restapi.qunhe.com metaData: type: object additionalProperties: type: string description: Additional metadata as key/value pairs (keys up to 64 chars, pattern /[a-zA-Z0-9-_]/). nullable: true example: '{"instanceLimitPerRequest":"100","currentInstanceCount":"150"}' description: Additional metadata as key/value pairs (keys up to 64 chars, pattern /[a-zA-Z0-9-_]/). nullable: true example: instanceLimitPerRequest: '100' currentInstanceCount: '150' description: 'Error details: reason, domain, and metadata.' world_Help: required: - desc - url type: object properties: desc: type: string description: Description of the linked help document. example: How to resolve permission denied errors url: type: string description: URL of the help document example: https://docs.example.com/errors/permission-denied description: Help link and description for resolving the error. nullable: true world_LocalizedMessage: required: - locale - message type: object properties: locale: type: string description: Locale identifier for the message example: zh_CN message: type: string description: Localized error text for end users example: You do not have permission to access this resource description: Localized message for a specific locale. nullable: true world_WorldListQueryRequest: type: object properties: pageNum: minimum: 0 type: integer description: Page index (0-based). format: int32 example: 0 pageSize: maximum: 100 minimum: 0 type: integer description: Page size (max 100); defaults to 20 when 0 or omitted. format: int32 example: 20 statusList: type: array description: Filter by reconstruction status; empty means no status filter. items: $ref: '#/components/schemas/world_WorldOpenApiTaskStatus' description: >- List body: `pageNum` from 0, `pageSize` 1–100 (default 20 when 0 or omitted). Returns 3DGS worlds for the current account only. world_WorldOpenApiTaskStatus: type: string description: >- Task status — in progress: `PENDING` queued, `PREPROCESSING` preprocessing, `RUNNING` running. Terminal: `SUCCEEDED`, `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 chunk metadata download URL (`output.lodMetaPath`); present after successful LOD post-processing, else null. example: https://cdn.example.com/output/world-001-lod-meta.json description: '3DGS splat download URLs: PLY / SPZ and optional LOD metadata (same fields as task output).' world_WorldAssetBundle: type: object properties: splats: $ref: '#/components/schemas/world_WorldSplatBundle' lodMetaPath: type: string description: >- LOD chunk metadata download URL (`lodMetaPath`). Present after successful LOD post-processing; otherwise null. example: https://cdn.example.com/output/world-001-lod-meta.json semanticsMetadata: $ref: '#/components/schemas/world_WorldSemanticsMetadata' description: >- Reconstruction outputs; on success, splats are filled and LOD metadata sits with ply/spz URLs under `splats.urls`. world_WorldDetail: required: - worldId type: object properties: worldId: type: string description: World id; create APIs return the same value in `WorldAsyncOperation.worldId`. example: A1b2C3d4E5 name: type: string description: World name example: Living room reconstruction cover: type: string description: Cover image URL. example: https://cdn.example.com/cover/world-001.jpg scene: $ref: '#/components/schemas/world_WorldOpenApiProjectScene' createTime: type: integer description: Created at, Unix milliseconds. format: int64 example: 1699339916000 updateTime: type: integer description: Updated at, Unix milliseconds. format: int64 example: 1699340120000 status: $ref: '#/components/schemas/world_WorldOpenApiTaskStatus' progress: type: number description: Reconstruction progress in [0.0, 1.0]. format: float example: 0.65 assets: $ref: '#/components/schemas/world_WorldAssetBundle' description: >- World record: `worldId`, `scene`, `status`; `createTime` / `updateTime` are Unix ms. Details may include splat URLs when outputs are ready. world_WorldPagedList: type: object properties: pageNum: type: integer description: Page index used for this request (0-based). format: int32 example: 0 pageSize: type: integer description: Page size used for this request. format: int32 example: 20 count: type: integer description: Rows on this page. format: int32 example: 20 totalCount: type: integer description: Total matching rows. format: int32 example: 128 hasMore: type: boolean description: Whether another page exists. example: false result: type: array description: Rows for this page (WorldOpen mapping; list uses withResult=false by default). items: $ref: '#/components/schemas/world_WorldDetail' description: Paged list with `pageNum` / `pageSize`, current page rows, and totals. world_WorldSemanticsMetadata: type: object description: Semantics metadata placeholder; may be `{}`. world_WorldSplatBundle: type: object properties: urls: $ref: '#/components/schemas/world_SplatFileUrls' description: 3DGS splat output files. world_GenerateWorldRequest: type: object properties: name: type: string description: Project / world display name example: Living room generation cover: type: string description: Cover image URL (optional)。 example: https://cdn.example.com/cover/gen-cover.jpg resources: type: array description: Resources; provide `prompt` and/or resources. At most one image; omit `type` → image. items: $ref: '#/components/schemas/world_WorldResourceItem' prompt: type: string description: Text prompt; can combine with `resources`. example: Modern minimalist sunlit living room description: >- Body for world generation: text-only, one image, or both. Indoor scenes are more mature; non-indoor is Beta (see POST operation). Require non-empty `prompt` or ≥1 resource; at most one image-type resource (`type=image` or omitted counts as image). rendercloud_OfflineRenderSubmitRequest: type: object description: Offline render submit request body. Do not pass `operationId` when submitting. additionalProperties: false required: - requestId - usdContent properties: requestId: type: string description: Caller-generated request tracing ID. The server does not use this field for offline render task idempotency. minLength: 1 usdContent: type: string description: Base64-encoded OpenUSD text or binary content. minLength: 1 rendercloud_OperationPollRequest: type: object description: Long-running operation polling request body. Use the returned `operationId` after a successful submit. additionalProperties: false required: - operationId properties: operationId: type: string description: Operation ID returned by submit. minLength: 1 rendercloud_OfflineRenderResponse: type: object description: Offline render result. Returned only when `Operation.done=true` and the job succeeded. additionalProperties: false properties: taskId: type: string description: Offline render task ID. resultUrl: type: string format: uri description: Rendered image URL. rendercloud_RealtimeSessionSubmitRequest: type: object description: Realtime render stream creation request body. Do not pass `operationId` when creating. additionalProperties: false required: - requestId - usdContent properties: requestId: type: string description: Caller-generated idempotency key. minLength: 1 usdContent: type: string description: Base64-encoded OpenUSD text or binary content. minLength: 1 rendercloud_RealtimeSessionQueryResponse: type: object description: Realtime render stream query result. When `status=ACTIVE`, it contains WebSocket connection parameters. additionalProperties: false properties: sessionId: type: string description: Realtime render stream session ID. status: $ref: '#/components/schemas/rendercloud_RenderCloudSessionStatus' currentQueuePosition: type: integer format: int32 description: Current queue position. `0` means the session is ready. host: type: string description: Realtime render stream host. nodeId: type: string description: Value of the `nid` query parameter in the WebSocket URL. streamId: type: string description: Value of `slaveInit.masterStreamingId` in the WebSocket handshake message. token: type: string description: Authentication token required to establish the realtime render stream. rendercloud_RealtimeSessionUpdateRequest: type: object description: Realtime render stream incremental update request body. additionalProperties: false required: - requestId - usdContent properties: requestId: type: string description: Caller-generated idempotency key. minLength: 1 usdContent: type: string description: Base64-encoded incremental OpenUSD content. minLength: 1 rendercloud_RealtimeSessionUpdateResponse: type: object description: Realtime render stream incremental update response body. additionalProperties: false properties: sessionId: type: string description: Realtime render stream session ID. status: $ref: '#/components/schemas/rendercloud_RenderCloudSessionStatus' rendercloud_RealtimeSessionCloseResponse: type: object description: Realtime render stream close response body. additionalProperties: false properties: sessionId: type: string description: Realtime render stream session ID. closed: type: boolean description: Whether the server found and closed the session. rendercloud_OfflineRenderProcessingOperation: type: object description: Offline render processing state. additionalProperties: false required: - operationId - metaData - done - result - error properties: operationId: $ref: '#/components/schemas/rendercloud_OperationId' metaData: $ref: '#/components/schemas/rendercloud_OperationMetaData' done: type: boolean enum: - false result: type: object nullable: true description: Null while processing. error: type: object nullable: true description: Null while processing. rendercloud_OfflineRenderSuccessOperation: type: object description: Offline render success state. additionalProperties: false required: - operationId - metaData - done - result - error properties: operationId: $ref: '#/components/schemas/rendercloud_OperationId' metaData: $ref: '#/components/schemas/rendercloud_OperationMetaData' done: type: boolean enum: - true result: $ref: '#/components/schemas/rendercloud_OfflineRenderResponse' error: type: object nullable: true description: Null on success. rendercloud_RealtimeSessionProcessingOperation: type: object description: Realtime render stream creation processing state. additionalProperties: false required: - operationId - metaData - done - result - error properties: operationId: $ref: '#/components/schemas/rendercloud_OperationId' metaData: $ref: '#/components/schemas/rendercloud_OperationMetaData' done: type: boolean enum: - false result: type: object nullable: true description: Null while processing. error: type: object nullable: true description: Null while processing. rendercloud_RealtimeSessionSuccessOperation: type: object description: Realtime render stream creation success state. additionalProperties: false required: - operationId - metaData - done - result - error properties: operationId: $ref: '#/components/schemas/rendercloud_OperationId' metaData: $ref: '#/components/schemas/rendercloud_OperationMetaData' done: type: boolean enum: - true result: $ref: '#/components/schemas/rendercloud_RealtimeSessionQueryResponse' error: type: object nullable: true description: Null on success. rendercloud_OperationError: type: object description: Long-running operation failure state. additionalProperties: false required: - operationId - metaData - done - result - error properties: operationId: $ref: '#/components/schemas/rendercloud_OperationId' metaData: $ref: '#/components/schemas/rendercloud_OperationMetaData' done: type: boolean enum: - true result: type: object nullable: true description: Null on failure. error: $ref: '#/components/schemas/rendercloud_ApiError' rendercloud_OperationId: type: string description: Long-running operation ID. rendercloud_OperationMetaData: type: object nullable: true description: Long-running operation metadata. This API usually returns null. additionalProperties: true rendercloud_Int2: type: object description: Two-dimensional integer vector. Used for output resolution, where `x` is width and `y` is height. additionalProperties: false required: - x - 'y' properties: x: type: integer format: int32 minimum: 1 description: Image width in pixels. 'y': type: integer format: int32 minimum: 1 description: Image height in pixels. rendercloud_RenderCloudSessionStatus: type: string description: | Realtime render stream session status. - `INITIALIZING`: The session has been created and the backend is establishing the streaming connection. - `ACTIVE`: The streaming connection is ready and can render normally. - `FAILED`: Initialization or operation failed. - `CLOSED`: The session has been closed. enum: - RENDER_CLOUD_SESSION_STATUS_UNSPECIFIED - INITIALIZING - ACTIVE - FAILED - CLOSED rendercloud_ApiError: type: object description: >- Standard OpenAPI gateway error response. For async operation failures, this object is returned in `Operation.error`. additionalProperties: true required: - code - message - status properties: code: type: integer format: int32 description: HTTP semantic error code. example: 500 message: type: string description: Human-readable error message. It may include error details forwarded by the gateway. example: 'code: INTERNAL, details: ErrorDetails(reason=INTERNAL_ERROR, message=null, domain=render, metaData=null)' status: type: string description: Standard error status. enum: - INVALID_ARGUMENT - NOT_FOUND - RESOURCE_EXHAUSTED - INTERNAL example: INTERNAL details: $ref: '#/components/schemas/rendercloud_ErrorDetails' rendercloud_ErrorDetails: type: object description: Extended error details forwarded by the gateway. additionalProperties: true properties: reason: type: string description: Error reason. example: INTERNAL_ERROR domain: type: string description: Error domain. Examples use a generic value and do not expose internal service domains. example: render rendercloud_MeshUploadProcessRequest: type: object description: Mesh upload and process task request body. additionalProperties: false properties: originMeshUrl: type: string format: uri description: Original Mesh file URL address. example: https://example.com/mesh/original.glb rendercloud_TaskCreateResponse: type: object description: Task creation response body, following standard Result format. additionalProperties: false properties: success: type: boolean description: Whether successful. example: true data: type: integer format: int64 description: Created task ID. example: 1305220918472257500 errorMsg: type: string nullable: true description: Error message, null when successful. example: null rendercloud_TaskQueryResponse: type: object description: Task query response body, following standard Result format. additionalProperties: false properties: success: type: boolean description: Whether successful. example: true data: $ref: '#/components/schemas/rendercloud_AiGenerateBusInstanceOpenDto' errorMsg: type: string nullable: true description: Error message, null when successful. example: null rendercloud_CommonErrorResponse: type: object description: Common error response body. additionalProperties: false properties: success: type: boolean description: Whether successful. example: false data: type: object nullable: true description: Data, null on error. example: null errorMsg: type: string description: Error message. example: Invalid parameter rendercloud_AiGenerateBusInstanceOpenDto: type: object description: RenderCloud task details. additionalProperties: false properties: taskId: type: integer format: int64 description: Task ID. example: 1272794 userId: type: integer format: int64 description: User ID. example: 12345 status: type: integer format: int32 description: | Task status: - `0`: INIT - Initializing - `1`: RUNNING - Running - `3`: SUCCESS - Success - `4`: FAIL - Failed example: 3 outputs: type: array nullable: true description: Task output asset list, null while processing. items: $ref: '#/components/schemas/rendercloud_AiGraphicAssetDto' example: - content: YYZN2MZVAIQLEPTULM888888 sourceReferId: '607583273' rendercloud_AiGraphicAssetDto: type: object description: AI asset object. additionalProperties: false properties: sourceReferId: type: string description: Source asset reference ID (e.g., product ID). example: '607583273' content: type: string description: | Asset content: - For Mesh upload task input: original Mesh URL - For Mesh upload task output: parsed meshId example: YYZN2MZVAIQLEPTULM888888 lux3d_ImgTo3dRequest: required: - img type: object properties: img: minLength: 1 type: string description: Image Base64, recommended to use complete Data URL format, e.g. data:image/png;base64,... example: data:image/png;base64,BASE64_IMAGE_STRING version: type: string description: Lux3D version, supports v2.0-preview (default), v1.0-pro. If not provided, v2.0-preview is used by default enum: - v2.0-preview - v1.0-pro default: v2.0-preview example: v2.0-preview description: Image-to-3D task request body. lux3d_TextTo3dRequest: required: - prompt type: object properties: prompt: minLength: 1 type: string description: Text prompt example: Generate a high-quality 3D wooden chair model style: type: string description: >- Style type, supports photorealistic (default), cartoon, anime, hand_painted, cyberpunk, fantasy, glass. If not provided, photorealistic is used by default enum: - photorealistic - cartoon - anime - hand_painted - cyberpunk - fantasy - glass default: photorealistic example: photorealistic img: type: string description: Reference image, recommended to use complete Data URL format (optional) example: data:image/png;base64,BASE64_IMAGE_STRING version: type: string description: Lux3D version, supports v2.0-preview (default), v1.0-pro. If not provided, v2.0-preview is used by default enum: - v2.0-preview - v1.0-pro default: v2.0-preview example: v2.0-preview description: Text-to-3D task request body. lux3d_MaterialTransferRequest: required: - img - meshUrl type: object properties: img: minLength: 1 type: string description: Image URL or Base64 for material reference example: data:image/png;base64,BASE64_IMAGE_STRING meshUrl: minLength: 1 type: string description: Model GLB file URL example: https://example.com/model.glb version: type: string description: Lux3D version, supports v2.0-preview (default), v1.0-pro. If not provided, v2.0-preview is used by default enum: - v2.0-preview - v1.0-pro default: v2.0-preview example: v2.0-preview description: Material transfer task request body. lux3d_TaskCreateResponse: type: object properties: d: type: integer description: Returns taskid format: int64 example: 1256173 nullable: true m: type: string description: Message nullable: true c: type: string description: Status code nullable: true description: Task creation response body. lux3d_TaskOutput: type: object properties: content: type: string description: Result content (model file URL) nullable: true example: https://cdn.example.com/output/model.lux3d description: Task output item. lux3d_TaskQueryData: type: object properties: taskId: type: integer description: Task ID format: int64 example: 1389513 outputs: type: array description: >- Output list. v1.0-pro version returns single format output (lux3d), v2.0-preview version returns multiple format output (.zip, .glb, .usdz) items: $ref: '#/components/schemas/lux3d_TaskOutput' status: type: integer description: 'Task status: 0-initialized, 1-in progress, 3-success, 4-failed' format: int32 enum: - 0 - 1 - 3 - 4 example: 3 description: Task query data. lux3d_TaskQueryResponse: type: object properties: d: $ref: '#/components/schemas/lux3d_TaskQueryData' m: type: string description: Message nullable: true c: type: string description: Status code nullable: true description: Task query response body. parameters: rendercloud_SessionId: name: sessionId in: path required: true description: Realtime rendering stream session ID. schema: type: string responses: rendercloud_BadRequest: description: Invalid request arguments. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_ApiError' examples: invalidArgument: summary: Invalid argument description: The request body is missing required fields or contains invalid field values. value: code: 400 message: requestId cannot be empty status: INVALID_ARGUMENT details: reason: INVALID_ARGUMENT domain: render usdContentEmpty: summary: OpenUSD content is empty description: '`usdContent` is empty when submitting a render or creating a realtime stream.' value: code: 400 message: OpenUSD content cannot be empty status: INVALID_ARGUMENT details: reason: USD_CONTENT_EMPTY domain: render openUsdParseError: summary: OpenUSD parse failed description: '`usdContent` is not valid Base64 or the decoded OpenUSD content cannot be parsed.' value: code: 400 message: OpenUSD content parse failed status: INVALID_ARGUMENT details: reason: OPENUSD_PARSE_ERROR domain: render rendercloud_NotFound: description: Resource not found. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_ApiError' examples: taskNotFound: summary: Task not found description: No offline render task exists for the `operationId` when polling. value: code: 404 message: Task not found status: NOT_FOUND details: reason: TASK_NOT_FOUND domain: render sessionNotFound: summary: Session not found description: The realtime render session does not exist, has been closed, or has been cleaned up. value: code: 404 message: Session not found status: NOT_FOUND details: reason: SESSION_NOT_FOUND domain: render rendercloud_Conflict: description: Duplicate request. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_OperationError' examples: duplicateRequest: summary: Duplicate requestId description: The same user submitted the same `requestId` again within 1 minute. value: operationId: null metaData: null done: true result: null error: code: 409 message: requestId has already been submitted within 60 seconds status: ALREADY_EXISTS details: reason: OFFLINE_RENDER_DUPLICATE_REQUEST domain: render rendercloud_TooManyRequests: description: The request was rate limited. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_ApiError' examples: rateLimited: summary: Rate limited description: The user-level request frequency exceeds the current API limit. value: code: 429 message: Rate limited status: RESOURCE_EXHAUSTED details: reason: RATE_LIMITED domain: render rendercloud_InternalServerError: description: Internal render service error. content: application/+json: schema: $ref: '#/components/schemas/rendercloud_ApiError' examples: renderInternalError: summary: Render failed description: Task creation, OpenUSD conversion, render dispatch, or realtime session update failed. value: code: 500 message: Render failed status: INTERNAL details: reason: INTERNAL_ERROR domain: render requestBodies: {} securitySchemes: AuthorizationHeader: type: apiKey description: >- Open platform credential. API key auth: set header `Authorization` to your platform **API key** (no `Bearer` prefix). name: Authorization in: header OusTokenV2: type: apiKey description: >- `ousToken` from **Get OUS upload token**; use only on OUS `globalDomain`; independent of gateway `Authorization`. name: ous-token-v2 in: header x-tagGroups: - name: Asset tags: - Asset - name: World tags: - World - name: Render Cloud tags: - RenderCloud - name: Lux3D tags: - Lux3D