Create 3D Reconstruction Project

从真实图片/视频重建 3D 模型（物体或空间）

Endpoint

POST https://openapi.kujiale.com/v2/aholo/project/create-3d-recon
Content-Type: application/json

Authentication

需要签名认证 + appuid 参数。

Request

Query Parameter

Parameter	Required	Type	Description
appuid	Yes	String	第三方用户ID

Request Body

json

{
  "projectName": "龙凤呈祥冠",
  "cover": "https://cdn.kujiale.com/path/to/cover.jpg",
  "scene": "model",
  "taskQuality": "NORMAL",
  "accessLevel": 0,
  "resources": [
    {
      "name": "龙凤呈祥冠.jpg",
      "type": 0,
      "url": "https://cdn.kujiale.com/path/to/input.jpg",
      "meta": {
        "width": 1920,
        "height": 1080,
        "duration": null
      }
    }
  ],
  "uploadSog": false,
  "panorama": false
}

Fields

Field	Required	Type	Description
projectName	Yes	String	项目名称
cover	No	String	封面图 URL
scene	Yes	String	场景类型。model=物体, space=室内
taskQuality	Yes	String	任务质量。LOW/NORMAL/HIGH/ULTRA
accessLevel	No	Int	访问级别，默认 0。0=公开, 1=私有
resources	Yes	Array	输入资源列表
uploadSog	No	Boolean	生成结果是否上传 SOG
panorama	No	Boolean	上传资源是否是全景内容

Resource Object

Field	Required	Type	Description
name	Yes	String	资源名称
type	Yes	Int	资源类型。0=图片, 1=视频
url	Yes	String	资源 URL，来自 Upload
meta	Yes	Object	资源元信息
meta.width	Yes	Int	宽度（像素）
meta.height	Yes	Int	高度（像素）
meta.duration	Yes	Int/null	时长（视频用秒，图片为 null）

Scene Types

Scene	Description	Recommended Input
model	物体重建（工艺品、家具等）	单张或多张物体图片
space	室内空间重建（房间、展厅等）	多角度图片或视频

Quality Levels

Quality	Speed	Quality	Use Case
LOW	快	低	快速预览
NORMAL	中	中	常规使用（推荐）
HIGH	较慢	高	高质量输出
ULTRA	慢	极高	最终交付

Response

json

{
  "c": "0",
  "d": "3FO4K4WF0LMU",
  "m": null,
  "f": ""
}

Field	Type	Description
c	String	状态码，`"0"` 表示成功
d	String	项目ID (projectId)

Code Examples

Python - 物体重建

python

import requests

APPUID = "your_appuid"
BASE_URL = "https://openapi.kujiale.com/v2/aholo"

def create_3d_recon_project(
    image_url,
    project_name,
    scene="model",
    quality="NORMAL",
    is_video=False
):
    """创建 3D 重建项目"""
    
    resource_type = 1 if is_video else 0
    
    payload = {
        "projectName": project_name,
        "cover": image_url,
        "scene": scene,  # model=物体, space=室内
        "taskQuality": quality,  # LOW/NORMAL/HIGH/ULTRA
        "accessLevel": 0,
        "resources": [
            {
                "name": "input.jpg" if not is_video else "input.mp4",
                "type": resource_type,
                "url": image_url,
                "meta": {
                    "width": 1920,
                    "height": 1080,
                    "duration": None if not is_video else 30  # 视频时长（秒）
                }
            }
        ],
        "uploadSog": False,
        "panorama": False
    }
    
    response = requests.post(
        f"{BASE_URL}/project/create-3d-recon",
        params={"appuid": APPUID},
        json=payload
        # 注意：实际需添加签名认证
    )
    
    if response.json()["c"] != "0":
        raise Exception("创建项目失败")
    
    project_id = response.json()["d"]
    
    print(f"✓ 项目创建成功: {project_id}")
    return project_id

# 使用示例 - 物体重建
project_id = create_3d_recon_project(
    image_url="https://cdn.kujiale.com/path/to/object.jpg",
    project_name="工艺品模型",
    scene="model",
    quality="HIGH"
)

# 使用示例 - 室内空间重建
project_id = create_3d_recon_project(
    image_url="https://cdn.kujiale.com/path/to/room.jpg",
    project_name="我的客厅",
    scene="space",
    quality="NORMAL"
)

# 使用示例 - 视频重建
project_id = create_3d_recon_project(
    image_url="https://cdn.kujiale.com/path/to/scan.mp4",
    project_name="视频扫描重建",
    scene="space",
    quality="NORMAL",
    is_video=True
)

Python - 多图片重建

python

def create_3d_recon_multi_image(image_urls, project_name, scene="model"):
    """多图片重建（多角度输入）"""
    
    resources = []
    for i, url in enumerate(image_urls):
        resources.append({
            "name": f"image_{i}.jpg",
            "type": 0,
            "url": url,
            "meta": {
                "width": 1920,
                "height": 1080,
                "duration": None
            }
        })
    
    payload = {
        "projectName": project_name,
        "cover": image_urls[0],  # 第一张作为封面
        "scene": scene,
        "taskQuality": "HIGH",
        "accessLevel": 0,
        "resources": resources,
        "uploadSog": False,
        "panorama": False
    }
    
    response = requests.post(
        f"{BASE_URL}/project/create-3d-recon",
        params={"appuid": APPUID},
        json=payload
    )
    
    return response.json()["d"]

# 多角度图片重建物体
project_id = create_3d_recon_multi_image(
    image_urls=[
        "https://cdn.kujiale.com/front.jpg",
        "https://cdn.kujiale.com/side.jpg",
        "https://cdn.kujiale.com/back.jpg"
    ],
    project_name="多角度物体重建",
    scene="model"
)

JavaScript

javascript

const APPUID = 'your_appuid';
const BASE_URL = 'https://openapi.kujiale.com/v2/aholo';

async function create3dReconProject(imageUrl, projectName, options = {}) {
  const payload = {
    projectName: projectName,
    cover: imageUrl,
    scene: options.scene || 'model',
    taskQuality: options.quality || 'NORMAL',
    accessLevel: 0,
    resources: [
      {
        name: options.isVideo ? 'input.mp4' : 'input.jpg',
        type: options.isVideo ? 1 : 0,
        url: imageUrl,
        meta: {
          width: 1920,
          height: 1080,
          duration: options.isVideo ? options.duration : null
        }
      }
    ],
    uploadSog: false,
    panorama: options.panorama || false
  };
  
  const response = await fetch(
    `${BASE_URL}/project/create-3d-recon?appuid=${APPUID}`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload)
    }
  );
  
  const data = await response.json();
  
  if (data.c !== '0') {
    throw new Error('创建项目失败');
  }
  
  return data.d; // projectId
}

// 使用示例
const projectId = await create3dReconProject(
  'https://cdn.kujiale.com/path/to/object.jpg',
  '工艺品模型',
  { scene: 'model', quality: 'HIGH' }
);

cURL

bash

curl -X POST "https://openapi.kujiale.com/v2/aholo/project/create-3d-recon?appuid=your_appuid" \
  -H "Content-Type: application/json" \
  -d '{
    "projectName": "龙凤呈祥冠",
    "scene": "model",
    "taskQuality": "NORMAL",
    "resources": [
      {
        "name": "object.jpg",
        "type": 0,
        "url": "https://cdn.kujiale.com/path/to/object.jpg",
        "meta": {"width": 1920, "height": 1080, "duration": null}
      }
    ]
  }'

Notes

项目类型: 重建项目 (projectType=0)
适用场景: 真实物体/空间的数字化重建
多图片: 多角度输入可提高重建质量
全景: 如果输入是全景图/全景视频，设置 panorama=true

Error Codes

Code	Description
-1	调用失败

Create 3D Reconstruction Project #

Endpoint #

Authentication #

Request #

Query Parameter #

Request Body #

Fields #

Resource Object #

Scene Types #

Quality Levels #

Response #

Code Examples #

Python - 物体重建 #

Python - 多图片重建 #

JavaScript #

cURL #

Notes #

Error Codes #

Create 3D Reconstruction Project

Endpoint

Authentication

Request

Query Parameter

Request Body

Fields

Resource Object

Scene Types

Quality Levels

Response

Code Examples

Python - 物体重建

Python - 多图片重建

JavaScript

cURL

Notes

Error Codes