Image Generation

POST /api/v1/generate/image

curl -X POST https://api.kolbo.ai/api/v1/generate/image \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A futuristic cityscape at night"}'

curl -X POST https://api.kolbo.ai/api/v1/generate/image \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Product photo of a sneaker on white background",
    "aspect_ratio": "16:9",
    "enhance_prompt": false
  }'

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

# Step 2: Use an identifier from the response
# Example identifiers: "nano-banana-2", "nano-banana-pro", "gpt-image-2". Credit cost is on each model's `credit` field.
curl -X POST https://api.kolbo.ai/api/v1/generate/image \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Product photo of a sneaker on white background",
    "model": "nano-banana-2",
    "aspect_ratio": "16:9"
  }'

curl -X POST https://api.kolbo.ai/api/v1/generate/image \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The character from @Image 1 wearing the jacket from @Image 2",
    "model": "nano-banana-2",
    "reference_images": [
      "https://example.com/character.jpg",
      "https://example.com/jacket.jpg"
    ],
    "aspect_ratio": "1:1"
  }'

curl -X POST https://api.kolbo.ai/api/v1/generate/image \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A flat vector sticker of a coffee cup",
    "model": "gpt-image-2",
    "background": "transparent",
    "output_format": "png"
  }'

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

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}/v1/generate/${generationId}/status`, {
      headers: { "X-API-Key": KOLBO_API_KEY }
    }).then((r) => r.json());
    if (TERMINAL.has(status.state)) return status;
  }
}

// Smart Select (recommended) — omit model, Kolbo picks the best one
async function main() {
  const response = await fetch(`${BASE_URL}/v1/generate/image`, {
    method: "POST",
    headers: {
      "X-API-Key": KOLBO_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ prompt: "A cat wearing a space suit", aspect_ratio: "1:1" })
  });

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

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

  console.log("Image URLs:", result.result.urls); // always an array
}
main();

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

async function main() {
  // Step 1: Fetch available image models
  const modelsRes = await fetch(`${BASE_URL}/v1/models?type=image`, {
    headers: { "X-API-Key": KOLBO_API_KEY }
  });
  const { models } = await modelsRes.json();
  console.log("Available models:", models.map(m => `${m.identifier} (${m.credit} credits)`));
  // Example identifiers: "nano-banana-2", "nano-banana-pro", "gpt-image-2"

  // Step 2: Use a specific model identifier (nano-banana-2 is recommended for most use cases)
  const response = await fetch(`${BASE_URL}/v1/generate/image`, {
    method: "POST",
    headers: {
      "X-API-Key": KOLBO_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      prompt: "A cat wearing a space suit",
      model: "nano-banana-2",
      aspect_ratio: "1:1"
    })
  });

  const started = await response.json();

  // pollUntilDone() from the example above
  const result = await pollUntilDone(started.generation_id, started.poll_interval_hint);
  console.log("Image URLs:", result.result.urls);
}
main();

import requests
import time

KOLBO_API_KEY = "kolbo_live_..."  # Replace with your API key
BASE_URL = "https://api.kolbo.ai/api"
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}/v1/generate/{generation_id}/status",
            headers=HEADERS,
        ).json()
        if status["state"] in TERMINAL:
            return status


# Smart Select (recommended) — omit model, Kolbo picks the best one
started = requests.post(
    f"{BASE_URL}/v1/generate/image",
    headers=HEADERS,
    json={
        "prompt": "A mountain landscape at sunset",
        "aspect_ratio": "16:9"
    }
).json()

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

print("Image URLs:", result["result"]["urls"])  # always a list

import requests

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

# Step 1: Fetch available image models
models = requests.get(
    f"{BASE_URL}/v1/models?type=image",
    headers=HEADERS
).json()["models"]

# Step 2: Pick a model (e.g. the first one)
chosen_model = models[0]["identifier"]
print(f"Using model: {chosen_model}")

# Step 3: Generate with that model
started = requests.post(
    f"{BASE_URL}/v1/generate/image",
    headers=HEADERS,
    json={
        "prompt": "A mountain landscape at sunset",
        "model": chosen_model,
        "aspect_ratio": "16:9"
    }
).json()

# poll_until_done() from the example above
result = poll_until_done(started["generation_id"], started["poll_interval_hint"])
print("Image URLs:", result["result"]["urls"])

{
  "success": true,
  "generation_id": "6890f1a2c3d4e5f60718293a",
  "type": "image",
  "model": "auto",
  "credits_charged": null,
  "poll_url": "/v1/generate/6890f1a2c3d4e5f60718293a/status",
  "poll_interval_hint": 3,
  "session_id": "6601a1b2c3d4e5f6a7b8c9d0",
  "project_id": "6601a1b2c3d4e5f6a7b8c9d1"
}

{
  "success": true,
  "generation_id": "6890f1a2c3d4e5f60718293a",
  "type": "image",
  "state": "completed",
  "progress": 100,
  "result": {
    "urls": [
      "https://media.kolbo.ai/kolbo/images/6890f1a2c3d4e5f60718293a-0.png",
      "https://media.kolbo.ai/kolbo/images/6890f1a2c3d4e5f60718293a-1.png"
    ],
    "thumbnail_url": "https://media.kolbo.ai/kolbo/images/6890f1a2c3d4e5f60718293a-0.png",
    "prompt_used": "a neon-lit ramen bar in the rain, shallow depth of field",
    "model": "nano-banana-2",
    "created_at": "2026-07-27T09:14:02.113Z"
  },
  "session_id": "6601a1b2c3d4e5f6a7b8c9d0",
  "project_id": "6601a1b2c3d4e5f6a7b8c9d1",
  "credits_used": 24,
  "credits_breakdown": [
    { "model": "nano-banana-2", "amount": 24 }
  ]
}

curl -X POST https://api.kolbo.ai/api/v1/generate/image \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A product photo of a sneaker",
    "moodboard_id": "6601a1b2c3d4e5f6a7b8c9d0",
    "aspect_ratio": "1:1"
  }'

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