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

Rate limit: 120 requests/minute per user on all five moodboard routes (list, get, create, update, delete). The bucket is shared with the other SDK media-library routes, and failed requests do not count against it.

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",
      "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"],
      "owner": { "userId": "65ab…", "name": "", "avatar": null },
      "is_mine": true,
      "created_at": "2025-12-01T00:00:00Z"
    }
  ],
  "count": 12
}

The content_scope field indicates ownership: personal, preset (system), or organization. owner / is_mine are attribution: is_mine is true only for a non-preset board you created, which is also the condition for updating or deleting it. System presets and boards another user created (organization boards, cast boards, teammates' boards surfaced through project_id) come back with is_mine: false and owner.userId set to their creator; owner.name and owner.avatar are filled when known (the project owner's boards) and are otherwise "" / null. 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

Access is granted when you own the board, when it is a system preset, when it is scoped to your active organization, or when it is shared through a project you have edit/full/owner permission on. Otherwise 403 ("Access denied"). A malformed id returns 400, a missing one 404.

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"],
    "owner": { "userId": "65ab…", "name": "Dana Levi", "avatar": "https://…" },
    "is_mine": true,
    "created_at": "2025-12-01T00:00:00Z"
  }
}

Create a Moodboard

POST /api/v1/moodboards

Accepts JSON or multipart/form-data.

* You may instead upload image files directly as multipart parts and omit images entirely — in that case only name and style_guide are validated (other form fields, including project_id and shareWithOrganization, are still honored). Uploaded files must have an image/* MIME type, are capped at 10 MB each, and at most 15 files per request.

Account cap: 50 moodboards per user. Creating past that returns 400.

The server uploads/normalizes the images and runs multi-image style analysis to synthesize the master_prompt. Creation is synchronous — the request stays open through the analysis. Success is HTTP 201.

Pass the returned id as moodboard_id on generation endpoints.

Update a Moodboard

PUT /api/v1/moodboards/:id

Owner only — a board you do not own returns 403, a missing one 404, and system presets (is_preset: true) return 403. Same narrow response shape as create, minus image_count: the update path returns the moodboard document, which does not carry the image list, so that key is omitted.

Delete a Moodboard

DELETE /api/v1/moodboards/:id

Permanent, owner only; system presets return 403. Underlying image files remain in storage. Response: { "success": true, "id": "…" }.

Errors on the CRUD routes

The create / update / delete wrappers flatten every failure to { "success": false, "error": "…", "details": … }. There is no separate code field — error carries whichever value the underlying controller supplied:

Only create emits the four uppercase codes; update and delete surface the underlying exception text instead. Branch on the HTTP status, not on error.

MCP Tools

The matching @kolbo/mcp tools are list_moodboards, get_moodboard, create_moodboard, update_moodboard, and delete_moodboard. They take image URLs only (image_urls) and wrap them into { "type": "url", "url": … } descriptors for you — for local files, call upload_media first and pass the returned URLs. create_moodboard also takes an optional project_id, and list_moodboards / get_moodboard take project_id to reach boards shared through a project. Note that list_moodboards defaults to scope: "personal" on the MCP side, while the REST route returns everything accessible when scope is omitted.

Using a Moodboard

Pass moodboard_id on POST /v1/generate/image, POST /v1/generate/image-edit, or POST /v1/generate/creative-director to apply a moodboard's style. These are the only SDK generation routes that read moodboard_id; other routes ignore it. The moodboard's master_prompt is automatically combined with your prompt.

#Name mentions

Instead of moodboard_id, you can write #Name in the prompt itself and the server resolves it to a moodboard you can access. Rules enforced by the parser:

• An explicit moodboard_id in the body always wins over a # mention.
• At most one moodboard is applied per generation. If several # mentions resolve, the first by position wins and the rest are stripped.
• A #token that does not resolve to an accessible moodboard is left completely untouched in the prompt (so hashtags and markdown headings are safe). Purely numeric tokens (#2026) and ##-style markdown headings are never treated as mentions.
• Confirmed mentions are stripped from the prompt text — the moodboard is applied through its master_prompt, not by leaving the tag in the sentence.
• Like @, the # capture runs past single spaces, so #Brand Mood make her smile first captures the whole phrase. When that fails to match, the server retries progressively shorter word prefixes (longest first) and trims the stripped span back to #<actual name>, leaving the rest of the sentence intact. Single-token moodboard names avoid the round trip.

#Name mentions also work on Elements (POST /v1/generate/elements), which has no moodboard_id field: the resolved board's master_prompt is appended to the prompt after enhancement. The name lookup covers only your own, organization and preset boards — a board you can reach only through a project is not resolved by #Name here. On first-last-frame generation, confirmed #Name mentions are only stripped from the prompt — the moodboard is not applied.

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 folded into your prompt by the enhancement pass, so it influences 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[i] is used for scene i when present, otherwise the request falls back to moodboard_id for that scene. Both are validated as ObjectIds.

Related