Moodboards

Moodboards are style templates that guide the visual direction of your generations. Each moodboard has a master_prompt — a curated description of colors, lighting, mood, and aesthetic — that is blended with your prompt at generation time.

You can apply a moodboard to image generation, image editing, and Creative Director requests using the moodboard_id field.

List Moodboards

Returns all moodboards available to your account. By default this includes your personal moodboards, system presets, and organization moodboards. Use the scope param to filter.

Endpoint

GET /api/v1/moodboards

Query Parameters

Parameter	Type	Description
`scope`	string	Filter by ownership: `"personal"` (your own), `"preset"` or `"global"` (system presets), `"organization"` (org-shared). Omit for all.

Example

# List all moodboards
curl https://api.kolbo.ai/api/v1/moodboards \
  -H "X-API-Key: kolbo_live_..."

# List only your personal moodboards
curl "https://api.kolbo.ai/api/v1/moodboards?scope=personal" \
  -H "X-API-Key: kolbo_live_..."

Response

{
  "success": true,
  "moodboards": [
    {
      "id": "6601a1b2c3d4e5f6a7b8c9d0",
      "name": "Soft Studio",
      "master_prompt": "soft studio lighting, clean white background, subtle shadows, product photography aesthetic",
      "style_guide": "For product shots. Avoid harsh shadows.",
      "thumbnail_url": "https://cdn.kolbo.ai/moodboards/...",
      "is_preset": true,
      "content_scope": "preset",
      "images": ["https://cdn.kolbo.ai/moodboards/ref1.jpg"],
      "created_at": "2025-12-01T00:00:00Z"
    }
  ],
  "count": 12
}

The content_scope field indicates ownership: "personal", "preset" (system), or "organization". is_shared is included when the moodboard has been shared via a public link.

Get Moodboard

Retrieve a single moodboard by ID.

Endpoint

GET /api/v1/moodboards/:id

Example

curl https://api.kolbo.ai/api/v1/moodboards/6601a1b2c3d4e5f6a7b8c9d0 \
  -H "X-API-Key: kolbo_live_..."

Response

{
  "success": true,
  "moodboard": {
    "id": "6601a1b2c3d4e5f6a7b8c9d0",
    "name": "Soft Studio",
    "master_prompt": "soft studio lighting, clean white background, subtle shadows, product photography aesthetic",
    "style_guide": "For product shots. Avoid harsh shadows.",
    "thumbnail_url": "https://cdn.kolbo.ai/moodboards/...",
    "is_preset": true,
    "content_scope": "preset",
    "images": ["https://cdn.kolbo.ai/moodboards/ref1.jpg"],
    "created_at": "2025-12-01T00:00:00Z"
  }
}

Create a Moodboard

POST /api/v1/moodboards

Field	Type	Required	Description
`name`	string	Yes	1–100 chars.
`images`	array	Yes	1–15 items of `{ "type": "url", "url": "…" }`. Use generated-image URLs or `POST /v1/media/upload` output.
`style_guide`	string	No	Style notes (max 500 chars) steering the analysis.

The server uploads/normalizes the images, runs multi-image style analysis, and returns the moodboard with its synthesized master_prompt. Pass the returned id as moodboard_id on generation endpoints.

Update a Moodboard

PUT /api/v1/moodboards/:id

Same fields, all optional. Providing images replaces the whole set and re-runs the style analysis. Owner only.

Delete a Moodboard

DELETE /api/v1/moodboards/:id

Permanent (owner only; system presets are protected). Underlying image files remain in storage.

Using a Moodboard

Pass moodboard_id to any generation request to apply a moodboard's style. The moodboard's master_prompt is automatically combined with your prompt.

Image 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 woman walking through a market",
    "moodboard_id": "6601a1b2c3d4e5f6a7b8c9d0",
    "aspect_ratio": "9:16"
  }'

Image Editing

curl -X POST https://api.kolbo.ai/api/v1/generate/image-edit \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Replace the background with a sunset",
    "source_images": ["https://example.com/photo.jpg"],
    "moodboard_id": "6601a1b2c3d4e5f6a7b8c9d0"
  }'

Creative Director — All Scenes

Apply the same moodboard across every scene:

curl -X POST https://api.kolbo.ai/api/v1/generate/creative-director \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Premium sneaker campaign",
    "scene_count": 4,
    "moodboard_id": "6601a1b2c3d4e5f6a7b8c9d0",
    "aspect_ratio": "16:9"
  }'

Creative Director — Per-Scene Moodboards

Use different moodboards per scene with moodboard_ids (array, one ID per scene):

curl -X POST https://api.kolbo.ai/api/v1/generate/creative-director \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Brand campaign across different moods",
    "scene_count": 3,
    "moodboard_ids": [
      "id-soft-studio",
      "id-dark-cinematic",
      "id-outdoor-golden"
    ]
  }'

JavaScript Example

const API_KEY = "kolbo_live_YOUR_API_KEY";
const BASE = "https://api.kolbo.ai/api";

async function main() {
  // 1. List available moodboards
  const mbRes = await fetch(`${BASE}/v1/moodboards`, {
    headers: { "X-API-Key": API_KEY }
  });
  const { moodboards } = await mbRes.json();

  // 2. Pick the first preset moodboard
  const moodboard = moodboards.find((m) => m.is_preset);
  if (!moodboard) {
    console.log("No preset moodboards found.");
    return;
  }
  console.log("Using moodboard:", moodboard.name);

  // 3. Generate an image with the moodboard applied
  const genRes = await fetch(`${BASE}/v1/generate/image`, {
    method: "POST",
    headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      prompt: "A coffee cup on a wooden table",
      moodboard_id: moodboard.id,
      aspect_ratio: "1:1"
    })
  });
  const { poll_url } = await genRes.json();

  // 4. Poll until the generation completes
  let result;
  do {
    await new Promise((r) => setTimeout(r, 3000));
    const status = await fetch(`${BASE}${poll_url}`, {
      headers: { "X-API-Key": API_KEY }
    });
    result = await status.json();
  } while (result.state === "processing");

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

main();

Python Example

import time
import requests

API_KEY = "kolbo_live_YOUR_API_KEY"
BASE = "https://api.kolbo.ai/api"
HEADERS = {"X-API-Key": API_KEY}

# 1. List available moodboards
mb_res = requests.get(f"{BASE}/v1/moodboards", headers=HEADERS)
moodboards = mb_res.json()["moodboards"]

# 2. Pick the first preset moodboard
moodboard = next((m for m in moodboards if m.get("is_preset")), None)
if not moodboard:
    print("No preset moodboards found.")
    exit()
print("Using moodboard:", moodboard["name"])

# 3. Generate an image with the moodboard applied
gen_res = requests.post(
    f"{BASE}/v1/generate/image",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "prompt": "A coffee cup on a wooden table",
        "moodboard_id": moodboard["id"],
        "aspect_ratio": "1:1",
    },
)
poll_url = gen_res.json()["poll_url"]

# 4. Poll until the generation completes
while True:
    time.sleep(3)
    status = requests.get(f"{BASE}{poll_url}", headers=HEADERS).json()
    if status["state"] != "processing":
        break

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

Tips

System presets (is_preset: true) are available to all users — they're a good starting point.
The moodboard master_prompt is appended to your prompt before enhancement, so it influences the AI's creative direction without overriding your subject.
Moodboards combine well with Visual DNA — use Visual DNA for character/product identity and a moodboard for overall style.
For Creative Director, moodboard_ids takes precedence over moodboard_id if both are provided.

On this page