---
title: "Compile a carousel from a slide document"
method: POST
path: "/carousels/compile"
tags: ["Project Management"]
---

# Compile a carousel from a slide document

`POST /carousels/compile`

## Request

- Base URL: `https://blitzreels.com/api/v1`
- URL: `https://blitzreels.com/api/v1/carousels/compile`
- Auth: API key in header `Authorization`

Create or replace a carousel project from declarative slides. The server owns chip layout, safezones, and export frame. POST /projects/{projectId}/carousels/generate is a legacy adapter onto the same compile.

## Request body

- object
  - `platform` 'tiktok_photo' | 'instagram_4x5' | 'linkedin', required
  - `name` string, required
  - `locale` string
  - `project_id` string, uuid
  - `series_id` string, uuid
  - `clear_existing` boolean
  - `slides` object[], required
    - `role` 'hook' | 'body' | 'proof' | 'cta'
    - `lines` string[]
    - `slots` object
    - `visual` object, required
      - `kind` 'creative_source' | 'media_asset' | 'generate' | 'solid' | 'gradient' | 'html' | 'template', required
      - `media_asset_id` string, uuid
      - `prompt` string
      - `model_id` string
      - `color` string
      - `colors` string[]
      - `html` string
      - `template_id` string
      - `source_media_asset_id` string, uuid
      - `creative_artifact_id` string, uuid
      - `crop` object
        - `left` number, required
        - `top` number, required
        - `width` number, required
        - `height` number, required
    - `layout` 'chip_stack_ui' | 'chip_stack_face_safe' | 'chip_stack_top' | 'title_body_card'
    - `layout_overrides` object
      - `top_px` integer
  - `style` object
    - `chip` object
      - `font_family` string
      - `font_weight` union
        - integer
        - string
      - `font_size` integer
      - `color` string
      - `background` string
      - `padding_x` integer
      - `padding_y` integer
      - `radius` integer
      - `max_lines_per_chip` integer

## Response `200`

Successful response

- object
  - `project_id` string, uuid, required
  - `revision` integer, required
  - `platform` 'tiktok_photo' | 'instagram_4x5' | 'linkedin', required
  - `slide_count` integer, required
  - `slides` object[], required
    - `index` integer, required
    - `role` 'hook' | 'body' | 'proof' | 'cta', nullable, required
    - `timeline_item_ids` string[], required
    - `overlay_ids` string[], required
    - `layout_applied` 'chip_stack_ui' | 'chip_stack_face_safe' | 'chip_stack_top' | 'title_body_card', required
    - `chip_band_px` object, required
      - `top` number, required
      - `bottom` number, required
  - `frame` object, required
    - `width` integer, required
    - `height` integer, required
    - `aspect_ratio` string, required
  - `job_id` string, nullable, required
  - `ai_image_run_id` string, nullable, required
  - `warnings` object[], required
    - `code` string, required
    - `message` string, required
    - `field` string
    - `repair` string
  - `next_actions` object[], required
    - `method` 'GET' | 'POST' | 'PATCH' | 'DELETE', required
    - `path` string, required
    - `reason` string, required

## Other responses

- `400`: Invalid input data
- `401`: Authorization not provided
- `403`: Insufficient access
- `500`: Internal server error

---

[API](https://skmtc.dev/blitzreels/apis/blitzreels-api.md) · [All operations](https://skmtc.dev/blitzreels/apis/blitzreels-api/llms.txt) · [OpenAPI document](https://skmtc.dev/blitzreels/apis/blitzreels-api/revisions/35608b12471d?raw)