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
)

E コマース用 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 Binary）
• .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 を使用します