← Files Aholo Lux3DARCHIVED FILE
skills/lux3d/core/contracts/lux3d-generation.v1.json
12.3 KB · Sep 30, 2026 · 23:15 UTC
{
"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
}
}
}
SHA-256: 03a69c5df0350f596e2d50172dba748a0fd84578d63002153e0df4f011dc7fbc