modelslab-3d-generation

ModelsLab 3D 生成

使用 AI 驱动的 3D 生成功能，将文本描述和 2D 图像转换为 3D 模型。

何时使用此技能

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

可用端点

文本转 3D

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

图像转 3D

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

文本转 3D

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")

# 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}")

图像转 3D

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)

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

使用 Webhook

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"]

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

关键参数

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

最佳实践

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. 图像转 3D 的要求

• 使用清晰、光线充足的图像
• 单个对象搭配纯色背景效果最佳
• 多个角度有帮助（如果支持）
• 建议使用高分辨率输入

3. 设定合理预期

• 3D 生成需要 5-15 分钟
• 质量取决于输入质量
• 复杂对象可能需要进一步完善
• 最适合简单到中等复杂度的对象

4. 始终使用异步模式

# 3D generation is ALWAYS async
if data["status"] == "processing":
    result = poll_3d_result(data["id"], api_key)

5. 处理较长的等待时间

# Use longer timeouts for 3D
poll_3d_result(request_id, api_key, timeout=900)  # 15 minutes

# Or use webhooks
generate_3d_with_webhook(prompt, api_key, webhook_url, track_id)

常见用例

游戏资产

# Generate weapon
sword = text_to_3d(
    "Fantasy sword with glowing blue blade, ornate gold handle, medieval style",
    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
)

产品原型制作

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

电商 3D 模型

# Convert product photo to 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
)

建筑元素

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

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

批量生成

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

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

错误处理

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

输出格式

API 会以常见格式返回 3D 模型文件：

• .glb（glTF 二进制格式）
• .obj（Wavefront OBJ）
• .fbx（Filmbox）

请查看响应以了解具体格式详情。

性能提示

1. 使用 Webhook：不要持续轮询
2. 批量处理相似请求：一同生成多个模型
3. 缓存结果：存储生成的模型以供重复使用
4. 从简单开始：先用简单对象进行测试
5. 监控生成时间：跟踪并优化

企业版 API

如需专用资源：

# 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"

资源

• 3D API 文档：https://docs.modelslab.com/3d-api/overview
• 文本转 3D：https://docs.modelslab.com/3d-api/text-to-3d
• 图像转 3D：https://docs.modelslab.com/3d-api/image-to-3d
• 获取 API 密钥：https://modelslab.com/dashboard

相关技能

• modelslab-image-generation - 为图像转 3D 生成图像
• modelslab-webhooks - 处理异步 3D 生成
• modelslab-sdk-usage - 使用官方 SDK