Image Generation

Generate images from text prompts using 20+ AI models including Flux, Midjourney, DALL-E, Ideogram, and more.

Smart Select (recommended): Omit the model field and Kolbo automatically picks the best model for your prompt. This is the simplest way to get started and works great for most use cases.

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

Endpoint

POST /api/v1/generate/image

Request Body

Field	Type	Required	Description
`prompt`	string	Yes	Text description of the image
`model`	string	No	Model identifier from `GET /api/v1/models?type=image`. Omit to use Smart Select (recommended).
`aspect_ratio`	string	No	`"1:1"`, `"16:9"`, `"9:16"`, etc. (default: `"1:1"`)
`enhance_prompt`	boolean	No	Enhance prompt for better results (default: `true`)
`num_images`	number	No	Number of images to generate (default: `1`)
`reference_images`	array	No	Array of image URLs used as style/content reference. The model uses these to guide composition, style, or subject. Check `max_reference_images` on the model.
`visual_dna_ids`	array	No	Visual DNA IDs for character/product consistency (max 3)
`moodboard_id`	string	No	Moodboard ID to apply a style template. The moodboard's master prompt is combined with yours to guide the visual direction.

Examples

Basic (Smart Select)

The simplest approach — just send a prompt and Kolbo picks the best model:

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

With Aspect Ratio and Options

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

Choosing a Specific Model

If you need a specific model, fetch the list first, then use the identifier value:

# 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" (8 credits), "nano-banana-pro" (15 credits), "nano-banana-2/4k" (16 credits)
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"
  }'

With Reference Images

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 portrait in the same style as the reference",
    "reference_images": ["https://example.com/style-ref.jpg"],
    "aspect_ratio": "1:1"
  }'

JavaScript

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

async function generateImage(prompt, options = {}) {
  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, ...options })
  });

  const { generation_id, poll_url } = await response.json();

  // Poll for result
  let result;
  do {
    await new Promise((r) => setTimeout(r, 3000));
    const status = await fetch(`${BASE_URL}${poll_url}`, {
      headers: { "X-API-Key": KOLBO_API_KEY }
    });
    result = await status.json();
  } while (result.state === "processing");

  return result;
}

// Smart Select (recommended) — omit model, Kolbo picks the best one
async function main() {
  const result = await generateImage("A cat wearing a space suit", {
    aspect_ratio: "1:1"
  });
  console.log("Image URLs:", result.result.urls);
}
main();

JavaScript — Choosing a Specific Model

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.credits} credits)`));
  // Example identifiers: "nano-banana-2" (8 credits), "nano-banana-pro" (15 credits), "nano-banana-2/4k" (16 credits)

  // 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 { poll_url } = await response.json();

  // Poll for result
  let result;
  do {
    await new Promise((r) => setTimeout(r, 3000));
    const status = await fetch(`${BASE_URL}${poll_url}`, {
      headers: { "X-API-Key": KOLBO_API_KEY }
    });
    result = await status.json();
  } while (result.state === "processing");

  console.log("Image URLs:", result.result.urls);
}
main();

Python

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}

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

# Poll for result
while True:
    time.sleep(3)
    status = requests.get(
        f"{BASE_URL}{gen['poll_url']}",
        headers=HEADERS
    ).json()
    if status["state"] != "processing":
        break

print("Image URLs:", status["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/api"
HEADERS = {"X-API-Key": KOLBO_API_KEY}

# Step 1: Fetch available image models
models_response = requests.get(
    f"{BASE_URL}/v1/models?type=image",
    headers=HEADERS
)
models = models_response.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
response = requests.post(
    f"{BASE_URL}/v1/generate/image",
    headers=HEADERS,
    json={
        "prompt": "A mountain landscape at sunset",
        "model": chosen_model,
        "aspect_ratio": "16:9"
    }
)
gen = response.json()

# Poll for result
while True:
    time.sleep(3)
    status = requests.get(
        f"{BASE_URL}{gen['poll_url']}",
        headers=HEADERS
    ).json()
    if status["state"] != "processing":
        break

print("Image URLs:", status["result"]["urls"])

Response

Generation Started

{
  "success": true,
  "generation_id": "abc123",
  "type": "image",
  "model": "auto",
  "credits_charged": 2,
  "poll_url": "/v1/generate/abc123/status",
  "poll_interval_hint": 3
}

Completed Status

{
  "success": true,
  "generation_id": "abc123",
  "type": "image",
  "state": "completed",
  "progress": 100,
  "result": {
    "urls": ["https://cdn.kolbo.ai/images/..."],
    "model": "auto",
    "prompt_used": "Enhanced version of your prompt",
    "created_at": "2026-03-05T10:30:00Z"
  }
}

With Moodboard

Apply a moodboard to guide the visual style of your generation:

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

Use GET /api/v1/moodboards to list available moodboards. See Moodboards for details.

Finding Models

Use the Models endpoint to discover available image models:

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

On this page