3D Generation

POST /api/v1/generate/3d

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"}'

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"],
    "texture_prompt": "Clean white running shoe",
    "enable_pbr": true
  }'

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"
  }'

# 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": "MODEL_IDENTIFIER",
    "enable_pbr": true,
    "target_polycount": 30000
  }'

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/knight-full-body.png"],
    "model": "MESHY_V7_IMAGE_TO_3D_IDENTIFIER",
    "enable_rigging": true,
    "rigging_height_meters": 1.8,
    "enable_animation": true,
    "animation_action_id": 92
  }'

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/vase.png"],
    "model": "TRELLIS_2_IDENTIFIER",
    "resolution": 1536,
    "t2_texture_size": 4096,
    "decimation_target": 200000,
    "seed": 42
  }'

{
  "success": true,
  "generation_id": "6612f0a1b2c3d4e5f6a7b8c9",
  "type": "three_d",
  "model": "auto",
  "credits_charged": null,
  "poll_url": "/v1/generate/6612f0a1b2c3d4e5f6a7b8c9/status",
  "poll_interval_hint": 8,
  "session_id": "6601a1b2c3d4e5f6a7b8c9d0",
  "project_id": "6601a1b2c3d4e5f6a7b8c9d0"
}

{
  "success": true,
  "generation_id": "6612f0a1b2c3d4e5f6a7b8c9",
  "type": "three_d",
  "state": "completed",
  "progress": 100,
  "session_id": "6601a1b2c3d4e5f6a7b8c9d0",
  "project_id": "6601a1b2c3d4e5f6a7b8c9d0",
  "result": {
    "urls": [
      "https://media.kolbo.ai/3d/model.glb",
      "https://media.kolbo.ai/3d/model.fbx",
      "https://media.kolbo.ai/3d/model.obj",
      "https://media.kolbo.ai/3d/model.usdz"
    ],
    "thumbnail_url": "https://media.kolbo.ai/3d/preview.png",
    "mode": "text",
    "prompt_used": "A medieval sword with ornate handle",
    "model": null,
    "created_at": "2026-04-10T14:20:00Z"
  },
  "credits_used": 60,
  "credits_breakdown": [
    { "model": "MODEL_IDENTIFIER", "amount": 60 }
  ]
}

curl -X POST https://api.kolbo.ai/api/v1/generate/6612f0a1b2c3d4e5f6a7b8c9/cancel \
  -H "X-API-Key: kolbo_live_..."

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 started = await response.json();
  if (!started.success) throw new Error(started.error);

  const status = await pollUntilDone(started.generation_id, started.poll_interval_hint);
  if (status.state !== "completed") throw new Error(status.error || status.state);

  console.log("3D model URLs:", status.result.urls); // every format, one array
  console.log("Thumbnail:", status.result.thumbnail_url);
  return status.result;
}

const TERMINAL = new Set(["completed", "failed", "cancelled"]);

// Minimal loop. A production client should also handle transient HTTP errors and
// an overall timeout — see /docs/developer-api/polling-and-cancellation.
async function pollUntilDone(generationId, intervalSeconds) {
  while (true) {
    await new Promise((r) => setTimeout(r, intervalSeconds * 1000));
    const status = await fetch(
      `${BASE_URL}/api/v1/generate/${generationId}/status`,
      { headers: { "X-API-Key": KOLBO_API_KEY } }
    ).then((r) => r.json());
    if (TERMINAL.has(status.state)) return status;
  }
}

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"],
    texture_prompt: "Oiled walnut wood grain",
  });
  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);

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

async function main() {
  // Step 1: Fetch text-to-3D models (a text prompt needs one)
  const modelsRes = await fetch(`${BASE_URL}/api/v1/models?type=3d_text_to_model`, {
    headers: { "X-API-Key": KOLBO_API_KEY },
  });
  const { models } = await modelsRes.json();
  console.log("Text-to-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 started = await response.json();
  if (!started.success) throw new Error(started.error);

  // pollUntilDone() from the example above
  const status = await pollUntilDone(started.generation_id, started.poll_interval_hint);
  if (status.state !== "completed") throw new Error(status.error || status.state);

  console.log("3D model URLs:", status.result.urls);
}

main().catch(console.error);

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}


TERMINAL = {"completed", "failed", "cancelled"}


def poll_until_done(generation_id, interval_seconds):
    """Minimal loop. Add transient-error retries and an overall timeout for
    production — see /docs/developer-api/polling-and-cancellation."""
    while True:
        time.sleep(interval_seconds)
        status = requests.get(
            f"{BASE_URL}/api/v1/generate/{generation_id}/status",
            headers=HEADERS,
        ).json()
        if status["state"] in TERMINAL:
            return status


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

    status = poll_until_done(started["generation_id"], started["poll_interval_hint"])
    if status["state"] != "completed":
        raise Exception(status.get("error", status["state"]))
    return status["result"]


# 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"],
    "texture_prompt": "Oiled walnut wood grain",
})
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"])

import requests

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 text-to-3D models (a text prompt needs one)
models = requests.get(
    f"{BASE_URL}/api/v1/models?type=3d_text_to_model", headers=HEADERS
).json()["models"]
print("Text-to-3D models:")
for m in models:
    print(f"  {m['identifier']} ({m['credit']} credits)")

# Step 2: Generate with a specific model — generate_3d() from the example above
# already handles the submit-then-poll round trip.
result = generate_3d({
    "prompt": "A futuristic helmet with visor",
    "model": models[0]["identifier"],
    "enable_pbr": True,
})
print("3D model URLs:", result["urls"])
print("Thumbnail:", result["thumbnail_url"])

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