---
title: "Render a carousel to PDF plus slide PNGs (tool render_carousel). Schema on GET /api/tools."
method: POST
path: "/api/carousels"
---

# Render a carousel to PDF plus slide PNGs (tool render_carousel). Schema on GET /api/tools.

`POST /api/carousels`

## Request

- Base URL: `https://shapelessai.com`
- URL: `https://shapelessai.com/api/carousels`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shapelessai.com/api/auth/mcp/authorize`, token URL `https://shapelessai.com/api/auth/mcp/token`, scopes: `write`)

## Request body

- object
  - `title` string, required: Short deck title (file naming and accessibility; render it yourself if you want it visible).
  - `css` string, required: The deck's one shared stylesheet: palette, type scale, layout classes. Scope everything under .slide-canvas.
  - `page` object: The canvas every slide is drawn on, in pixels. Default 1080x1350. Pick the shape the post will live in: 1080x1350 4:5 portrait (LinkedIn documents, Instagram portrait); 1080x1080 1:1 square; 1920x1080 16:9 landscape (slides, X, YouTube thumbnails). Anything between 480 and 2560px per side works; design your type scale for the canvas you chose, not for this default.
    - `width` number, required
    - `height` number, required
  - `slides` object[], required: 1-12 slides in order. Multi-slide: slide 1 is the hook read at thumbnail size; the last slide carries ONE call to action. Exactly 1 slide = a single-page infographic: the rendered PNG is the deliverable, designed to be fully read in-feed without a swipe.
    - `headline` string, required: The slide's one-line essence (shown as a text preview while pixels render).
    - `html` string, required: The slide's body markup — everything inside the fixed-size canvas. Static HTML only.
  - `budgetUsd` number: The most this call may spend, in USD (default 2, max 10). Held while the tool runs, released after.

## Response `200`

OK

- ToolResult
  - `tool` string, required
  - `output` unknown, required
  - `media` object[], required: Every media key the output names, with the URL that streams it (read scope). Put a key on a post's mediaKeys.
    - `key` string
    - `url` string, uri
  - `chargedUsd` number, required

## Other responses

- `400`: The input does not match the tool's schema; the message names the field.
- `401`: No credential, or not valid.
- `402`: Not enough credit to hold budgetUsd, or the call costs more than budgetUsd.
- `403`: The key is missing the "write" scope.
- `404`: No such tool on this deployment.
- `422`: The tool refused this input; nothing was charged.
- `429`: Over the key's rate limit (600 requests an hour).
- `502`: The tool failed; nothing was charged.

---

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