3D Generation

Generate 3D models (.glb, .fbx, .obj, .usdz) from text descriptions or reference images.

No Smart Select for 3D — unlike image and video generation, omitting the model field does not trigger Smart Select. Instead, built-in defaults are used (Meshy v6 for text/single-image, Meshy v5 for multi-image). Use GET /api/v1/models?type=three_d to discover available models.

Model identifiers are Kolbo-specific — they do not match upstream provider names. Always fetch available models from GET /api/v1/models?type=three_d first. Never guess or hardcode identifiers.

Endpoint

POST /api/v1/generate/3d

Request Body

Field	Type	Required	Description
`prompt`	string	Yes (text mode)	Text description of the 3D model
`mode`	string	No	`"text"`, `"single"`, or `"multi"`. Auto-resolved from `reference_images` if omitted (0 images = text, 1 = single, 2+ = multi).
`reference_images`	array	No	URLs of reference images. 1 image = single-image mode, 2+ = multi-image mode.
`texture_prompt`	string	No	Prompt for texture generation
`model`	string	No	Model identifier from `GET /api/v1/models?type=three_d`. Omit to use built-in defaults.
`topology`	string	No	Mesh topology type
`target_polycount`	number	No	Target polygon count
`enable_tpose`	boolean	No	Enable T-pose for character models
`enable_pbr`	boolean	No	Enable PBR materials
`enable_prompt_expansion`	boolean	No	Enable prompt expansion
`seed`	number	No	Random seed for reproducibility
`resolution`	string	No	Output resolution
`texture_size`	string	No	Texture size

Three Modes

3D generation supports three modes, determined automatically from the number of reference images:

Mode	Reference Images	Description
`text`	0 (none)	Generate from text prompt only
`single`	1	Generate from one reference image, optionally with a text prompt
`multi`	2+	Generate from multiple reference images for more accurate reconstruction

Examples

Text Mode (Prompt Only)

curl -X POST https://api.kolbo.ai/api/v1/generate/3d \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A medieval sword with ornate handle"}'

Single-Image Mode

curl -X POST https://api.kolbo.ai/api/v1/generate/3d \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "reference_images": ["https://example.com/shoe-front.jpg"],
    "prompt": "White running shoe",
    "enable_pbr": true
  }'

Multi-Image Mode

curl -X POST https://api.kolbo.ai/api/v1/generate/3d \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "reference_images": [
      "https://example.com/shoe-front.jpg",
      "https://example.com/shoe-side.jpg",
      "https://example.com/shoe-back.jpg"
    ],
    "texture_prompt": "Photorealistic sneaker texture"
  }'

With Specific Model

To choose a specific model, first fetch identifiers from GET /api/v1/models?type=three_d, then pass the identifier value:

# Step 1: List available 3D models
curl "https://api.kolbo.ai/api/v1/models?type=three_d" \
  -H "X-API-Key: kolbo_live_..."

# Step 2: Use an identifier from the response
curl -X POST https://api.kolbo.ai/api/v1/generate/3d \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A medieval sword with ornate handle",
    "model": "meshy-v6",
    "enable_pbr": true,
    "target_polycount": 30000
  }'

Response

Generation Started

{
  "success": true,
  "generation_id": "3d_abc123",
  "type": "three_d",
  "model": "meshy-v6",
  "credits_charged": 20,
  "poll_url": "/api/v1/generate/3d_abc123/status",
  "poll_interval_hint": 8
}

Completed Status

{
  "success": true,
  "generation_id": "3d_abc123",
  "type": "three_d",
  "state": "completed",
  "progress": 100,
  "result": {
    "urls": [
      "https://cdn.kolbo.ai/3d/model.glb",
      "https://cdn.kolbo.ai/3d/model.fbx",
      "https://cdn.kolbo.ai/3d/model.obj",
      "https://cdn.kolbo.ai/3d/model.usdz"
    ],
    "thumbnail_url": "https://cdn.kolbo.ai/3d/preview.png",
    "mode": "text",
    "prompt_used": "A medieval sword with ornate handle",
    "model": "meshy-v6",
    "created_at": "2026-04-10T14:20:00Z"
  }
}

JavaScript Example

const KOLBO_API_KEY = "kolbo_live_..."; // Replace with your API key
const BASE_URL = "https://api.kolbo.ai";

async function generate3D(body) {
  const response = await fetch(`${BASE_URL}/api/v1/generate/3d`, {
    method: "POST",
    headers: {
      "X-API-Key": KOLBO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  const data = await response.json();
  if (!data.success) throw new Error(data.error);

  const pollUrl = data.poll_url;

  // Poll for result
  while (true) {
    await new Promise((r) => setTimeout(r, 10000));
    const statusRes = await fetch(`${BASE_URL}${pollUrl}`, {
      headers: { "X-API-Key": KOLBO_API_KEY },
    });
    const status = await statusRes.json();

    if (status.state === "completed") {
      console.log("3D model URLs:", status.result.urls);
      console.log("Thumbnail:", status.result.thumbnail_url);
      return status.result;
    }
    if (status.state === "failed") {
      throw new Error(status.error || "Generation failed");
    }
    console.log(`Progress: ${status.progress}%`);
  }
}

async function main() {
  // Text mode — prompt only
  const textResult = await generate3D({
    prompt: "A low-poly tree with autumn leaves",
    enable_pbr: true,
  });
  console.log("Text mode result:", textResult.urls);

  // Single-image mode — one reference image
  const singleResult = await generate3D({
    reference_images: ["https://example.com/chair-photo.jpg"],
    prompt: "Wooden dining chair",
  });
  console.log("Single-image result:", singleResult.urls);

  // Multi-image mode — multiple reference images
  const multiResult = await generate3D({
    reference_images: [
      "https://example.com/mug-front.jpg",
      "https://example.com/mug-side.jpg",
    ],
    texture_prompt: "Ceramic mug with glossy finish",
  });
  console.log("Multi-image result:", multiResult.urls);
}

main().catch(console.error);

JavaScript — Choosing a Specific Model

const KOLBO_API_KEY = "kolbo_live_..."; // Replace with your API key
const BASE_URL = "https://api.kolbo.ai";

async function main() {
  // Step 1: Fetch available 3D models
  const modelsRes = await fetch(`${BASE_URL}/api/v1/models?type=three_d`, {
    headers: { "X-API-Key": KOLBO_API_KEY },
  });
  const { models } = await modelsRes.json();
  console.log("Available 3D models:", models.map(m => `${m.identifier} (${m.credit} credits)`));

  // Step 2: Generate with a specific model
  const response = await fetch(`${BASE_URL}/api/v1/generate/3d`, {
    method: "POST",
    headers: {
      "X-API-Key": KOLBO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "A futuristic helmet with visor",
      model: models[0].identifier,
      enable_pbr: true,
    }),
  });

  const data = await response.json();
  if (!data.success) throw new Error(data.error);

  // Poll for result
  while (true) {
    await new Promise((r) => setTimeout(r, 10000));
    const statusRes = await fetch(`${BASE_URL}${data.poll_url}`, {
      headers: { "X-API-Key": KOLBO_API_KEY },
    });
    const status = await statusRes.json();

    if (status.state === "completed") {
      console.log("3D model URLs:", status.result.urls);
      return;
    }
    if (status.state === "failed") {
      throw new Error(status.error || "Generation failed");
    }
    console.log(`Progress: ${status.progress}%`);
  }
}

main().catch(console.error);

Python Example

import requests
import time

KOLBO_API_KEY = "kolbo_live_..."  # Replace with your API key
BASE_URL = "https://api.kolbo.ai"
HEADERS = {"X-API-Key": KOLBO_API_KEY}


def generate_3d(body):
    """Generate a 3D model and poll until complete."""
    response = requests.post(
        f"{BASE_URL}/api/v1/generate/3d",
        headers=HEADERS,
        json=body,
    )
    data = response.json()
    if not data.get("success"):
        raise Exception(data.get("error", "Request failed"))

    poll_url = data["poll_url"]

    while True:
        time.sleep(10)
        status = requests.get(
            f"{BASE_URL}{poll_url}",
            headers=HEADERS,
        ).json()

        if status["state"] == "completed":
            return status["result"]
        if status["state"] == "failed":
            raise Exception(status.get("error", "Generation failed"))
        print(f"Progress: {status.get('progress', 0)}%")


# Text mode — prompt only
result = generate_3d({"prompt": "A low-poly tree with autumn leaves", "enable_pbr": True})
print("3D model URLs:", result["urls"])
print("Thumbnail:", result["thumbnail_url"])

# Single-image mode
result = generate_3d({
    "reference_images": ["https://example.com/chair-photo.jpg"],
    "prompt": "Wooden dining chair",
})
print("Single-image URLs:", result["urls"])

# Multi-image mode
result = generate_3d({
    "reference_images": [
        "https://example.com/mug-front.jpg",
        "https://example.com/mug-side.jpg",
    ],
    "texture_prompt": "Ceramic mug with glossy finish",
})
print("Multi-image URLs:", result["urls"])

Python — Choosing a Specific Model

import requests
import time

KOLBO_API_KEY = "kolbo_live_..."  # Replace with your API key
BASE_URL = "https://api.kolbo.ai"
HEADERS = {"X-API-Key": KOLBO_API_KEY}

# Step 1: Fetch available 3D models
models_response = requests.get(f"{BASE_URL}/api/v1/models?type=three_d", headers=HEADERS)
models = models_response.json()["models"]
print("Available 3D models:")
for m in models:
    print(f"  {m['identifier']} ({m['credit']} credits)")

# Step 2: Generate with a specific model
chosen_model = models[0]["identifier"]
response = requests.post(
    f"{BASE_URL}/api/v1/generate/3d",
    headers=HEADERS,
    json={
        "prompt": "A futuristic helmet with visor",
        "model": chosen_model,
        "enable_pbr": True,
    },
)
data = response.json()
if not data.get("success"):
    raise Exception(data.get("error", "Request failed"))

# Poll for result
poll_url = data["poll_url"]
while True:
    time.sleep(10)
    status = requests.get(f"{BASE_URL}{poll_url}", headers=HEADERS).json()

    if status["state"] == "completed":
        print("3D model URLs:", status["result"]["urls"])
        print("Thumbnail:", status["result"]["thumbnail_url"])
        break
    if status["state"] == "failed":
        raise Exception(status.get("error", "Generation failed"))
    print(f"Progress: {status.get('progress', 0)}%")

Tips

3D generation typically takes 1-3 minutes depending on complexity
Multi-image mode produces more accurate geometry but takes longer
Enable PBR materials (enable_pbr: true) for realistic rendering in game engines
Output formats include .glb (universal), .fbx (game engines), .obj (legacy), and .usdz (Apple AR)
Use the thumbnail_url in the response for quick previews without loading the full 3D model

Finding Models

Use the Models endpoint to discover available 3D models:

curl "https://api.kolbo.ai/api/v1/models?type=three_d" \
  -H "X-API-Key: kolbo_live_..."

On this page