lux3d_api.md

API 调用
概述
Lux3D 当前提供 2 个接口，用于完成图生 3D 的异步生成流程：

创建任务
查询任务
调用流程如下：

API Key -> 解析 appuid/appkey/appsecret -> 生成 sign -> 创建任务 -> 查询任务 -> 获取 lux3d_url
建议每 10-15 秒轮询查询任务状态。

鉴权说明
API 调用使用签名方式鉴权。

开发者申请到的 API Key 并不是直接作为请求参数透传给接口，而是需要先解析出以下信息：

appuid
appkey
appsecret
随后按以下规则生成签名：

sign = MD5(appsecret + appkey + appuid + timestamp)
其中：

timestamp 为毫秒级时间戳
sign 作为 query 参数参与接口调用
目前 Lux3D 不提供独立的服务端接口帮助开发者解析 API Key。 如果使用 API 方式接入，开发者需要在本地或自己的服务中先完成 API Key 解析，再使用解析结果调用 Lux3D API。

API Key 解析结果
根据当前实现，API Key 可解析出以下结构：

version:appkey:appsecret:appuid
编码方式为 Base64。

API Key 解析示例
以下示例展示如何从 API Key 中解析出 appkey、appsecret 和 appuid。

JavaScript
const apiKey = "YOUR_API_KEY";
const decoded =
  typeof atob === "function"
    ? atob(apiKey)
    : Buffer.from(apiKey, "base64").toString("utf-8");
const [version, appkey, appsecret, appuid] = decoded.split(":");

if (!version || !appkey || !appsecret || !appuid) {
  throw new Error("Invalid API Key format");
}
Python
import base64

api_key = "YOUR_API_KEY"
decoded = base64.b64decode(api_key).decode("utf-8")
version, appkey, appsecret, appuid = decoded.split(":")
签名生成示例
以下示例展示如何基于解析结果生成 sign。

JavaScript
const appkey = "YOUR_APPKEY";
const appsecret = "YOUR_APPSECRET";
const appuid = "YOUR_APPUID";
const timestamp = Date.now().toString();
const sign = CryptoJS.MD5(appsecret + appkey + appuid + timestamp).toString();
Python
import hashlib
import time

appkey = "YOUR_APPKEY"
appsecret = "YOUR_APPSECRET"
appuid = "YOUR_APPUID"
timestamp = str(int(time.time() * 1000))
sign = hashlib.md5((appsecret + appkey + appuid + timestamp).encode("utf-8")).hexdigest()
接口列表
接口	方法	说明
https://api.luxreal.ai/global/lux3d/generate/task/create	POST	创建图生 3D 任务
https://api.luxreal.ai/global/lux3d/generate/task/get	GET	查询图生 3D 任务状态与结果
创建图生 3D 任务
描述
创建图生 3D 任务。

请求成功后返回任务 ID busid，后续可通过查询接口获取任务状态和结果。

API
POST https://api.luxreal.ai/global/lux3d/generate/task/create
Query 参数
参数	是否必须	类型	说明
appuid	是	string	第三方用户 ID
appkey	是	string	由 API Key 解析得到
timestamp	是	long	毫秒级时间戳
sign	是	string	签名结果
Request Body
{
  "img": ""
}
Body 参数说明
参数	是否必须	类型	说明
img	是	string	图片 Base64，建议使用 Data URL 格式，例如 data:image/png;base64,...
响应
{
  "d": "",
  "m": null,
  "c": null
}
响应字段说明
参数	是否必须	类型	说明
d	是	long	返回 busid
m	是	string	null
c	是	string	null
示例
curl -X POST "https://api.luxreal.ai/global/lux3d/generate/task/create?appuid=YOUR_APPUID&appkey=YOUR_APPKEY&timestamp=YOUR_TIMESTAMP&sign=YOUR_SIGN" \
  -H "Content-Type: application/json" \
  -d '{
    "img": "data:image/png;base64,BASE64_IMAGE_STRING"
  }'
查询图生 3D 任务
描述
根据 busid 查询任务状态和结果。

查询结果中的输出内容有效期为 2 小时，建议在任务成功后尽快获取并保存结果。

API
GET https://api.luxreal.ai/global/lux3d/generate/task/get
Query 参数
参数	是否必须	类型	说明
appuid	是	string	第三方用户 ID
appkey	是	string	由 API Key 解析得到
timestamp	是	long	毫秒级时间戳
sign	是	string	签名结果
busid	是	long	任务 ID
响应
{
  "d": {
    "busId": "",
    "outputs": [
      {
        "content": null
      }
    ],
    "status": ""
  },
  "m": null,
  "c": null
}
响应字段说明
参数	是否必须	类型	说明
d.busId	是	long	主线 ID
d.status	是	int	0 初始化，1 进行中，3 成功，4 失败
d.outputs	否	list<object>	输出列表
d.outputs[].content	否	string	结果内容
m	是	string	null
c	是	string	null
示例
curl -X GET "https://api.luxreal.ai/global/lux3d/generate/task/get?appuid=YOUR_APPUID&appkey=YOUR_APPKEY&timestamp=YOUR_TIMESTAMP&sign=YOUR_SIGN&busid=123456789"