modelslab-3d-generation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ModelsLab 3D Generation

ModelsLab 3D生成

Transform text descriptions and 2D images into 3D models using AI-powered 3D generation.

借助AI驱动的3D生成技术，将文本描述和2D图像转换为3D模型。

When to Use This Skill

何时使用该技能

Generate 3D models from text descriptions
Convert 2D images to 3D representations
Create 3D assets for games or applications
Prototype 3D objects quickly
Generate 3D product mockups
Create 3D characters from photos

根据文本描述生成3D模型
将2D图像转换为3D模型
为游戏或应用创建3D资源
快速制作3D物体原型
生成3D产品模型
根据照片创建3D角色

Available Endpoints

可用接口

Text to 3D

文本转3D

POST https://modelslab.com/api/v6/3d/text_to_3d

POST https://modelslab.com/api/v6/3d/text_to_3d

Image to 3D

图像转3D

POST https://modelslab.com/api/v6/3d/image_to_3d

POST https://modelslab.com/api/v6/3d/image_to_3d

Text to 3D

文本转3D

python

import requests
import time

def text_to_3d(prompt, api_key, num_inference_steps=50):
    """Generate a 3D object from a text prompt.

    Args:
        prompt: Text description of the 3D object
        api_key: Your ModelsLab API key
        num_inference_steps: Quality (higher = better, slower)

    Returns:
        URL of the 3D model file
    """
    response = requests.post(
        "https://modelslab.com/api/v6/3d/text_to_3d",
        json={
            "key": api_key,
            "prompt": prompt,
            "num_inference_steps": num_inference_steps
        }
    )

    data = response.json()

    if data["status"] == "error":
        raise Exception(f"Error: {data['message']}")

    if data["status"] == "success":
        return data["output"][0]

    # 3D generation is async - poll for results
    request_id = data["id"]
    print(f"3D generation started... Request ID: {request_id}")
    print(f"ETA: {data.get('eta', 'unknown')} seconds")

    return poll_3d_result(request_id, api_key)

def poll_3d_result(request_id, api_key, timeout=600):
    """Poll for 3D generation results."""
    start_time = time.time()

    while time.time() - start_time < timeout:
        fetch = requests.post(
            f"https://modelslab.com/api/v6/3d/fetch/{request_id}",
            json={"key": api_key}
        )
        result = fetch.json()

        if result["status"] == "success":
            return result["output"][0]
        elif result["status"] == "failed":
            raise Exception(result.get("message", "Generation failed"))

        print(f"Status: processing... ({int(time.time() - start_time)}s elapsed)")
        time.sleep(10)

    raise Exception("Timeout waiting for 3D generation")

python

import requests
import time

def text_to_3d(prompt, api_key, num_inference_steps=50):
    """根据文本提示词生成3D物体。

    参数:
        prompt: 3D物体的文本描述
        api_key: 你的ModelsLab API密钥
        num_inference_steps: 生成质量（值越高质量越好，速度越慢）

    返回:
        3D模型文件的URL
    """
    response = requests.post(
        "https://modelslab.com/api/v6/3d/text_to_3d",
        json={
            "key": api_key,
            "prompt": prompt,
            "num_inference_steps": num_inference_steps
        }
    )

    data = response.json()

    if data["status"] == "error":
        raise Exception(f"错误: {data['message']}")

    if data["status"] == "success":
        return data["output"][0]

    # 3D生成为异步操作 - 轮询获取结果
    request_id = data["id"]
    print(f"3D生成已启动... 请求ID: {request_id}")
    print(f"预计完成时间: {data.get('eta', '未知')} 秒")

    return poll_3d_result(request_id, api_key)

def poll_3d_result(request_id, api_key, timeout=600):
    """轮询3D生成结果。"""
    start_time = time.time()

    while time.time() - start_time < timeout:
        fetch = requests.post(
            f"https://modelslab.com/api/v6/3d/fetch/{request_id}",
            json={"key": api_key}
        )
        result = fetch.json()

        if result["status"] == "success":
            return result["output"][0]
        elif result["status"] == "failed":
            raise Exception(result.get("message", "生成失败"))

        print(f"状态: 处理中... ({int(time.time() - start_time)}秒已过)")
        time.sleep(10)

    raise Exception("等待3D生成超时")

Usage

使用示例

model_url = text_to_3d( "A medieval sword with ornate handle and detailed engravings", "your_api_key", num_inference_steps=50 ) print(f"3D model ready: {model_url}")

undefined

model_url = text_to_3d( "一把带有华丽手柄和精细雕刻的中世纪长剑", "your_api_key", num_inference_steps=50 ) print(f"3D模型已就绪: {model_url}")

undefined

Image to 3D

图像转3D

python

def image_to_3d(image_url, api_key):
    """Convert a 2D image into a 3D model.

    Args:
        image_url: URL of the 2D image
        api_key: Your ModelsLab API key

    Returns:
        URL of the generated 3D model
    """
    response = requests.post(
        "https://modelslab.com/api/v6/3d/image_to_3d",
        json={
            "key": api_key,
            "image": image_url
        }
    )

    data = response.json()

    if data["status"] == "error":
        raise Exception(f"Error: {data['message']}")

    if data["status"] == "success":
        return data["output"][0]

    # Poll for results
    request_id = data["id"]
    print(f"Converting image to 3D... Request ID: {request_id}")

    return poll_3d_result(request_id, api_key)

python

def image_to_3d(image_url, api_key):
    """将2D图像转换为3D模型。

    参数:
        image_url: 2D图像的URL
        api_key: 你的ModelsLab API密钥

    返回:
        生成的3D模型的URL
    """
    response = requests.post(
        "https://modelslab.com/api/v6/3d/image_to_3d",
        json={
            "key": api_key,
            "image": image_url
        }
    )

    data = response.json()

    if data["status"] == "error":
        raise Exception(f"错误: {data['message']}")

    if data["status"] == "success":
        return data["output"][0]

    # 轮询获取结果
    request_id = data["id"]
    print(f"正在将图像转换为3D... 请求ID: {request_id}")

    return poll_3d_result(request_id, api_key)

Convert product photo to 3D

将产品照片转换为3D

model_url = image_to_3d( "https://example.com/product-photo.jpg", "your_api_key" ) print(f"3D model: {model_url}")

undefined

model_url = image_to_3d( "https://example.com/product-photo.jpg", "your_api_key" ) print(f"3D模型: {model_url}")

undefined

Using Webhooks

使用Webhook

python

def generate_3d_with_webhook(prompt, api_key, webhook_url, track_id):
    """Generate 3D model and receive results via webhook."""
    response = requests.post(
        "https://modelslab.com/api/v6/3d/text_to_3d",
        json={
            "key": api_key,
            "prompt": prompt,
            "num_inference_steps": 50,
            "webhook": webhook_url,
            "track_id": track_id
        }
    )

    data = response.json()
    print(f"Request submitted: {data['id']}")
    return data["id"]

python

def generate_3d_with_webhook(prompt, api_key, webhook_url, track_id):
    """生成3D模型并通过webhook接收结果。"""
    response = requests.post(
        "https://modelslab.com/api/v6/3d/text_to_3d",
        json={
            "key": api_key,
            "prompt": prompt,
            "num_inference_steps": 50,
            "webhook": webhook_url,
            "track_id": track_id
        }
    )

    data = response.json()
    print(f"请求已提交: {data['id']}")
    return data["id"]

Usage

使用示例

request_id = generate_3d_with_webhook( "A futuristic sci-fi weapon", "your_api_key", "https://yourserver.com/webhook/3d", "model_001" )

undefined

request_id = generate_3d_with_webhook( "一把未来派科幻武器", "your_api_key", "https://yourserver.com/webhook/3d", "model_001" )

undefined

Key Parameters

关键参数

Parameter	Description	Recommended Values
`prompt`	Text description of 3D object	Be specific about shape, style, details
`image`	2D image URL for conversion	Clear, well-lit product photo
`num_inference_steps`	Quality vs speed	30 (fast), 50 (balanced), 100 (quality)
`webhook`	Async callback URL	Your server endpoint
`track_id`	Request identifier	Unique ID for tracking

参数	说明	推荐值
`prompt`	3D物体的文本描述	明确说明形状、风格、细节
`image`	用于转换的2D图像URL	清晰、光线充足的产品照片
`num_inference_steps`	质量与速度的平衡	30（快速）、50（平衡）、100（高质量）
`webhook`	异步回调URL	你的服务器端点
`track_id`	请求标识符	用于追踪的唯一ID

Best Practices

最佳实践

1. Craft Effective 3D Prompts

1. 撰写有效的3D提示词

✗ Bad: "a chair"
✓ Good: "A modern office chair with ergonomic design, armrests, five wheels, mesh back"

Include: Type, style, materials, key features, details

✗ 不佳: "一把椅子"
✓ 优秀: "一把符合人体工程学设计的现代办公椅，带扶手、五轮、网布靠背"

包含：类型、风格、材质、关键特性、细节

2. Image to 3D Requirements

2. 图像转3D的要求

Use clear, well-lit images
Single object on plain background works best
Multiple angles help (if supported)
High resolution input recommended

使用清晰、光线充足的图像
单一物体搭配纯色背景效果最佳
多角度图像会有帮助（若支持）
推荐使用高分辨率输入

3. Set Realistic Expectations

3. 设定合理预期

3D generation takes 5-15 minutes
Quality depends on input quality
Complex objects may need refinement
Best for simple to moderate complexity

3D生成需要5-15分钟
质量取决于输入质量
复杂物体可能需要后期优化
最适合简单到中等复杂度的物体

4. Always Use Async Pattern

4. 始终使用异步模式

python

undefined

python

undefined

3D generation is ALWAYS async

3D生成始终为异步操作

if data["status"] == "processing": result = poll_3d_result(data["id"], api_key)

undefined

if data["status"] == "processing": result = poll_3d_result(data["id"], api_key)

undefined

5. Handle Long Wait Times

5. 处理长时间等待

python

undefined

python

undefined

Use longer timeouts for 3D

为3D生成设置更长的超时时间

poll_3d_result(request_id, api_key, timeout=900) # 15 minutes

poll_3d_result(request_id, api_key, timeout=900) # 15分钟

Or use webhooks

或使用webhook

generate_3d_with_webhook(prompt, api_key, webhook_url, track_id)

undefined

generate_3d_with_webhook(prompt, api_key, webhook_url, track_id)

undefined

Common Use Cases

常见使用场景

Game Assets

游戏资源

python

undefined

python

undefined

Generate weapon

生成武器

sword = text_to_3d( "Fantasy sword with glowing blue blade, ornate gold handle, medieval style", api_key, num_inference_steps=75 )

sword = text_to_3d( "一把带有发光蓝色剑刃、华丽金色手柄的中世纪风格奇幻长剑", api_key, num_inference_steps=75 )

Generate character prop

生成角色道具

shield = text_to_3d( "Round wooden shield with iron rim and clan emblem in center", api_key )

undefined

shield = text_to_3d( "一个圆形木质盾牌，带铁制边缘，中心有家族徽章", api_key )

undefined

Product Prototyping

产品原型制作

python

undefined

python

undefined

Create product mockup

创建产品模型

prototype = text_to_3d( "Modern wireless earbuds with charging case, minimalist design, matte white finish", api_key, num_inference_steps=100 )

undefined

prototype = text_to_3d( "一款现代无线耳机，带充电盒，极简设计，哑光白色外观", api_key, num_inference_steps=100 )

undefined

E-commerce 3D Models

电商3D模型

python

undefined

python

undefined

Convert product photo to 3D

将产品照片转换为3D

def create_product_3d_view(product_image_url, api_key): """Generate 3D model from product photo.""" model = image_to_3d(product_image_url, api_key) print(f"3D product view ready: {model}") return model

product_3d = create_product_3d_view( "https://example.com/product.jpg", api_key )

undefined

def create_product_3d_view(product_image_url, api_key): """根据产品照片生成3D模型。""" model = image_to_3d(product_image_url, api_key) print(f"3D产品视图已就绪: {model}") return model

product_3d = create_product_3d_view( "https://example.com/product.jpg", api_key )

undefined

Architectural Elements

建筑元素

python

undefined

python

undefined

Generate furniture

生成家具

furniture = text_to_3d( "Modern minimalist coffee table, glass top, wooden legs, Scandinavian design", api_key )

furniture = text_to_3d( "一款现代极简主义咖啡桌，玻璃桌面，木质桌腿，斯堪的纳维亚风格", api_key )

Generate decorations

生成装饰品

vase = text_to_3d( "Ceramic vase with geometric pattern, blue and white colors, modern style", api_key )

undefined

vase = text_to_3d( "一个带有几何图案的陶瓷花瓶，蓝白配色，现代风格", api_key )

undefined

Batch Generation

批量生成

python

def generate_multiple_3d_models(prompts, api_key):
    """Generate multiple 3D models in batch."""
    request_ids = []

    # Submit all requests
    for i, prompt in enumerate(prompts):
        response = requests.post(
            "https://modelslab.com/api/v6/3d/text_to_3d",
            json={
                "key": api_key,
                "prompt": prompt,
                "webhook": "https://yourserver.com/webhook/3d",
                "track_id": f"batch_{i}"
            }
        )
        request_ids.append(response.json()["id"])
        print(f"Submitted: {prompt}")

    print(f"All {len(prompts)} requests submitted")
    return request_ids

python

def generate_multiple_3d_models(prompts, api_key):
    """批量生成多个3D模型。"""
    request_ids = []

    # 提交所有请求
    for i, prompt in enumerate(prompts):
        response = requests.post(
            "https://modelslab.com/api/v6/3d/text_to_3d",
            json={
                "key": api_key,
                "prompt": prompt,
                "webhook": "https://yourserver.com/webhook/3d",
                "track_id": f"batch_{i}"
            }
        )
        request_ids.append(response.json()["id"])
        print(f"已提交: {prompt}")

    print(f"所有{len(prompts)}个请求已提交")
    return request_ids

Generate multiple assets

生成多个资源

models = generate_multiple_3d_models([ "Medieval sword", "Knight's helmet", "Wooden shield", "Battle axe" ], api_key)

undefined

models = generate_multiple_3d_models([ "中世纪长剑", "骑士头盔", "木质盾牌", "战斧" ], api_key)

undefined

Error Handling

错误处理

python

try:
    model = text_to_3d(prompt, api_key)
    print(f"3D model generated: {model}")
except Exception as e:
    print(f"3D generation failed: {e}")
    # Log error, retry with simpler prompt, notify user

python

try:
    model = text_to_3d(prompt, api_key)
    print(f"3D模型已生成: {model}")
except Exception as e:
    print(f"3D生成失败: {e}")
    # 记录错误，使用更简单的提示词重试，通知用户

Output Formats

输出格式

The API returns 3D model files in common formats:

```
.glb
```
(glTF Binary)
```
.obj
```
(Wavefront OBJ)
```
.fbx
```
(Filmbox)

Check the response for specific format details.

API返回的3D模型文件为常见格式:

```
.glb
```
(glTF二进制格式)
```
.obj
```
(Wavefront OBJ格式)
```
.fbx
```
(Filmbox格式)

可在响应中查看具体格式细节。

Performance Tips

性能优化技巧

Use Webhooks: Don't poll continuously
Batch Similar Requests: Generate multiple models together
Cache Results: Store generated models for reuse
Start Simple: Test with simple objects first
Monitor Generation Time: Track and optimize

使用Webhooks: 不要持续轮询
批量提交相似请求: 同时生成多个模型
缓存结果: 存储已生成的模型以便复用
从简单案例开始: 先测试简单物体
监控生成时间: 追踪并优化

Enterprise API

企业版API

For dedicated resources:

python

undefined

如需专属资源:

python

undefined

Enterprise endpoints

企业版接口

text_to_3d_url = "https://modelslab.com/api/v1/enterprise/3d/text_to_3d" image_to_3d_url = "https://modelslab.com/api/v1/enterprise/3d/image_to_3d"

undefined

text_to_3d_url = "https://modelslab.com/api/v1/enterprise/3d/text_to_3d" image_to_3d_url = "https://modelslab.com/api/v1/enterprise/3d/image_to_3d"

undefined