{ "contractId": "lux3d-generation/v1", "module": "M02", "status": "implementation-baseline", "apiDocumentationVersion": "OpenAPI 2.0", "authority": { "policy": "The two lux3dWebDoc files are authoritative. Legacy docs and clients are drift references only.", "primarySources": [ { "region": "cn", "path": "lux3dWebDoc/cn.md", "sha256": "AEDF72819CB3AC76DF23415915908E58BDFA75DFEA51B086FC93F51D6D182C18" }, { "region": "international", "path": "lux3dWebDoc/intl.md", "sha256": "8072B18F62A5E3915AEDC402E23FFD9D145DB753DF190EFBF0555A141BDFA45A" } ], "reviewedOn": "2026-09-08", "regionalSemanticParity": true }, "transport": { "regions": { "cn": { "host": "https://api.aholo3d.cn", "pathPrefix": "", "effectiveBaseUrl": "https://api.aholo3d.cn", "apiKeyPage": "https://labs.aholo3d.cn/api-keys", "assetUploadDocs": "https://labs.aholo3d.cn/api-docs/api-reference#tag/asset" }, "international": { "host": "https://api.aholo3d.com", "pathPrefix": "/global", "effectiveBaseUrl": "https://api.aholo3d.com/global", "apiKeyPage": "https://labs.aholo3d.com/api-keys", "assetUploadDocs": "https://labs.aholo3d.com/api-docs/en/api-reference#tag/asset" } }, "regionIsolation": { "required": true, "apiKeysInterchangeable": false, "knownBaseUrlMismatchRejected": true }, "authentication": { "type": "apiKey", "in": "header", "name": "Authorization", "prefix": null, "bearerPrefixForbidden": true, "environmentByRegion": { "cn": "LUX3D_CN_API_KEY", "international": "LUX3D_GLOBAL_API_KEY" }, "legacyEnvironment": { "key": "LUX3D_API_KEY", "regionBinding": "LUX3D_API_KEY_REGION", "matchingRegionRequired": true } }, "requestPolicy": { "createMaxAttempts": 1, "createBlindRetry": false, "queryMaxAttempts": 3, "recommendedPollIntervalSeconds": { "minimum": 10, "maximum": 15 }, "unknownSubmissionRecovery": "Persist the local state and reconcile with task history before deciding whether to submit again.", "serverIdempotencyKey": null, "localDuplicatePrevention": "Atomically reserve the state file before POST; a second run using the same state path is rejected.", "localSubmissionClassification": { "submission_blocked": "Client-side validation or missing configuration prevented the POST.", "submission_rejected": "A complete API envelope returned a non-zero business code.", "submission_unknown": "POST transport or response processing failed without a trustworthy acceptance result." } }, "artifactTtlSeconds": 7200, "assetPreparation": { "status": "external-prerequisite", "contractIncluded": false, "rule": "img, imgs, meshUrl, and modelUrl must be reachable HTTP(S) URLs; upload local files through the regional Asset API first." } }, "responseEnvelope": { "requiredFields": [ "f", "c", "m", "d" ], "success": { "f": null, "c": "0", "m": "" }, "createData": { "type": "long", "meaning": "taskid", "minimum": 1, "booleanAllowed": false } }, "taskLifecycle": { "businessId": "LUX_3D", "statuses": { "0": "initialized", "1": "running", "3": "succeeded", "4": "failed", "6": "cancelled" }, "outputsFinalOnlyAtStatus": 3, "outputItem": { "contentRequired": false, "contentTypeWhenPresent": "string", "nonStringContentRejected": true }, "queryHealthIsNotTaskStatus": true, "invalidOutputAfterSuccess": { "lastKnownProviderStatus": 3, "localWorkflowStatus": "output_invalid", "queryHealth": "ok" } }, "concurrency": { "scope": "per-account-shared", "sharedCreateOperations": [ "image-to-3d", "text-to-3d", "material-transfer", "multimodal-image", "four-view" ], "excludedCreateOperations": [ "multi-format-export" ], "limits": { "free": 2, "pro": 5 }, "limitErrorCode": "GENERATION_CONCURRENCY_LIMIT_EXCEEDED" }, "sharedFields": { "faceCount": { "type": "integer", "minimum": 10000, "maximum": 300000, "default": 200000, "affectsPly": false }, "generationOutputFormat": { "type": "array", "items": [ "zip", "glb", "ply" ], "uniqueItems": true }, "style": { "type": "string", "values": [ "photorealistic", "cartoon", "anime", "hand_painted", "cyberpunk", "fantasy", "glass" ], "default": "photorealistic" } }, "versionProfiles": { "G1": { "appliesTo": [ "image-to-3d", "text-to-3d" ], "versionConditionalFields": [ "version", "faceCount", "outputFormat", "aiPredictSize", "customSize" ], "forbiddenFields": [ "enablePbr" ], "customSize": { "type": "number", "exclusiveMinimum": 0, "unit": "millimetre", "takesPrecedenceOver": "aiPredictSize" }, "outputRule": "Always ZIP then PBR GLB; append PLY when outputFormat contains ply." }, "G1-Turbo": { "appliesTo": [ "image-to-3d", "text-to-3d" ], "versionConditionalFields": [ "version", "faceCount", "outputFormat", "enablePbr", "aiPredictSize" ], "forbiddenFields": [ "customSize" ], "defaultOutputFormat": [ "zip" ], "plyOnlyForbidsEnablePbr": true, "outputRule": "Return the requested non-duplicated ZIP, GLB, and PLY combination, including PLY-only." }, "v3.0-standard": { "appliesTo": [ "material-transfer" ], "customSize": { "type": "number", "exclusiveMinimum": 0, "unit": "millimetre", "conflictsWith": { "aiPredictSize": true } } } }, "endpoints": { "image-to-3d": { "method": "POST", "path": "/lux3d/v1/generate/img-to-3d/task/create", "kind": "create", "request": { "required": [ "version" ], "oneOfRequired": [ "img", "imgs" ], "mutuallyExclusive": [ "img", "imgs" ], "imgs": { "minimumItems": 1, "maximumItems": 32, "ordered": true }, "versions": [ "G1", "G1-Turbo" ] } }, "text-to-3d": { "method": "POST", "path": "/lux3d/v1/generate/text-to-3d/task/create", "kind": "create", "request": { "required": [ "prompt", "version" ], "optional": [ "style", "img", "faceCount", "outputFormat", "enablePbr", "aiPredictSize", "customSize" ], "versions": [ "G1", "G1-Turbo" ] } }, "material-transfer": { "method": "POST", "path": "/lux3d/v1/generate/material-transfer/task/create", "kind": "create", "request": { "required": [ "img", "meshUrl", "version" ], "meshUrl": { "type": "string", "format": "uri", "pathSuffix": ".glb" }, "version": "v3.0-standard", "outputFormat": [ "zip", "glb", "usdz", "obj_zip", "fbx_zip" ], "aiPredictSize": { "type": "boolean", "whenTrue": "Predict model size automatically; customSize must be omitted.", "whenFalseOrOmitted": "Preserve the original size unless customSize is provided." }, "customSize": { "type": "number", "exclusiveMinimum": 0, "unit": "millimetre", "requiresAiPredictSize": "false-or-omitted" } }, "fixedOutputSlots": [ "zip", "glb", "usdz", "obj_zip", "fbx_zip" ], "emptySlotMarker": "NOT_REQUESTED" }, "multimodal-image": { "method": "POST", "path": "/lux3d/v1/generate/multimodal-to-image/task/create", "kind": "create", "exposure": "internal-support", "standaloneUserCapability": false, "cliExposed": false, "workflowRunnerExposed": false, "request": { "atLeastOneRequired": [ "img", "prompt" ] }, "output": { "count": 1, "content": "image-url" } }, "four-view": { "method": "POST", "path": "/lux3d/v1/generate/image-to-four-view/task/create", "kind": "create", "request": { "atLeastOneRequired": [ "img", "prompt" ] }, "output": { "count": 1, "encoding": "json-array-string", "viewOrder": [ "front-three-quarter", "opposite-three-quarter", "side", "back" ] } }, "multi-format-export": { "method": "POST", "path": "/lux3d/v1/multi-format-export/task/create", "kind": "create", "request": { "required": [ "modelUrl" ], "modelUrlSuffixes": [ ".zip", ".glb" ], "zipMustComeFromLux3d": true, "outputFormat": [ "usdz", "obj_zip", "fbx_zip", "stl", "3mf" ], "glbRequiresOutputFormat": true, "zipDefaultOutputFormat": [ "glb" ] }, "fixedOutputSlots": [ "zip", "glb", "usdz", "obj_zip", "fbx_zip", "stl", "3mf" ], "emptySlotMarkers": [ "NOT_REQUESTED", "null" ] }, "get-task": { "method": "GET", "path": "/lux3d/v1/generate/task/get", "kind": "query", "query": { "taskid": { "required": true, "type": "long", "minimum": 1, "booleanAllowed": false } }, "ownership": "authenticated-account-only", "response": { "required": [ "bizId", "taskId", "status" ], "bizId": "LUX_3D", "taskId": { "type": "long", "minimum": 1, "booleanAllowed": false, "mustEqualRequestedTaskId": true }, "status": [ 0, 1, 3, 4, 6 ], "outputsRequired": false } }, "list-tasks": { "method": "GET", "path": "/lux3d/v1/generate/task/list", "kind": "query", "query": { "page": { "type": "integer", "minimum": 1, "default": 1 }, "pagesize": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "status": { "type": "integer", "values": [ 0, 1, 3, 4, 6 ] }, "starttime": { "type": "long", "unit": "unix-milliseconds", "inclusive": true }, "endtime": { "type": "long", "unit": "unix-milliseconds", "exclusive": true } } } }, "outOfScopePlaceholders": { "assetUpload": { "status": "external-prerequisite", "endpoint": null }, "cancelTask": { "status": "not-defined-in-lux3dWebDoc", "endpoint": null }, "serverIdempotency": { "status": "not-defined-in-lux3dWebDoc", "headerOrField": null }, "callContextUniqueIdPropagation": { "status": "pending-M02-design", "postRequestLocation": "json-body", "getRequestLocation": "query-if-needed", "generationRecordField": "pending" }, "commercialization": { "status": "owned-by-M03", "contractRef": "lux3d-commerce/v1", "contractPath": "lux3d-commerce.v1.json", "endpoint": null } } }