Cinematic Presets

Layer a deliberate photographic "Cinema mode" treatment onto image generations and edits.

Cinematic Presets ("Cinema mode") let you compose a deliberate photographic look for an image by picking presets across independent dimensions — camera body, lens, focal length, aperture, angle, shot type, color grade, and lighting. The selected fragments are woven into your prompt before enhancement, so the result reads like an intentional camera setup rather than a list of gear names.

Cinema mode is entirely optional. Apply it only when the user wants a specific cinematic look — omit it for an ordinary generation. It is available on image generation and image editing via the cinematic field.

Dimensions

The catalog is data-driven — always fetch the live set from the endpoint below rather than hardcoding ids. Today the dimensions are:

Dimension	What it controls
`camera`	Camera body / format (e.g. ARRI Alexa, 16mm film, smartphone)
`lens`	Lens character (e.g. anamorphic, vintage prime, macro)
`focal_length`	Focal length / field of view (e.g. 24mm wide, 85mm portrait)
`aperture`	Aperture / depth of field (e.g. f/1.4 shallow, f/8 deep)
`angle`	Camera angle (e.g. low angle, birds-eye, eye level)
`shot_type`	Shot type / framing (e.g. close-up, wide shot, full shot)
`color_palette`	Color grade (e.g. teal & orange, technicolor, classic B&W)
`lighting`	Lighting technique (e.g. rim light, golden hour, low-key)

"Genre" was removed. New dimensions may be added over time — that is why you should discover dimensions and ids dynamically from GET /api/v1/cinematic-presets.

List Cinematic Presets

Returns all active presets grouped by dimension. Each preset carries id, name, description, thumbnail_url, and sort_order.

Endpoint

GET /api/v1/cinematic-presets

Example

curl https://api.kolbo.ai/api/v1/cinematic-presets \
  -H "X-API-Key: kolbo_live_..."

Response

{
  "camera": [
    {
      "id": "6a40...aa01",
      "name": "ARRI Alexa 35",
      "description": "shot on an ARRI Alexa 35 digital cinema camera, wide dynamic range...",
      "thumbnail_url": "https://kolbo-general-media.fra1.cdn.digitaloceanspaces.com/cinema-deck/camera/ARRI_Alexa_35.webp",
      "sort_order": 1
    }
  ],
  "lens": [ ... ],
  "color_palette": [ ... ],
  "lighting": [ ... ]
}

Responses are cached and served with an ETag — send If-None-Match to get a 304 Not Modified.

Applying Cinema Mode

Pass a cinematic object on the generation request. Each key is a dimension; each value is a preset id from the list endpoint. Include only the dimensions the user actually wants.

{
  "prompt": "a lone traveler crossing a desert at dusk",
  "cinematic": {
    "camera": "6a40...aa01",
    "color_palette": "6a40...cc07",
    "lighting": "6a40...dd12"
  }
}

The "Auto" rule

Any dimension you omit (or set to null) is Auto. When at least one dimension is set, the prompt enhancer intelligently completes the unset dimensions in the spirit of the ones you chose (e.g. picking a smartphone camera steers toward a candid, deep-focus everyday look; picking a film camera steers toward a filmic treatment).
Omit the cinematic object entirely for a normal, non-cinematic generation — nothing is injected and the standard enhancement pipeline decides the look.

Validation

At most one preset per dimension.
Each id must belong to its dimension — passing a lighting id in the camera slot returns a 400.
Unknown dimension keys are rejected.

Full Example

# 1. Discover presets
curl https://api.kolbo.ai/api/v1/cinematic-presets -H "X-API-Key: kolbo_live_..."

# 2. Generate with a cinematic look
curl https://api.kolbo.ai/api/v1/generate/image \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a lone traveler crossing a desert at dusk",
    "cinematic": {
      "camera": "6a40...aa01",
      "lens": "6a40...bb03",
      "color_palette": "6a40...cc07",
      "lighting": "6a40...dd12"
    }
  }'

The same cinematic object works on POST /api/v1/generate/image-edit.

On this page