# Carousel API

> Make carousels and slideshows over HTTPS from a topic or in the look of a post, follow the job, read every slide and download the ZIP, at app credit prices.

> Index of these docs: https://wavegrain.com/developers/llms.txt

The carousel API lets a program make slideshows with Wavegrain without an AI chat: from a topic in your brand's voice, or in the look of a post you link to.
It works like the app and the MCP server, with the same prices, limits and checks, so a slideshow costs the same whichever way you ask for it.

## Authentication

Send an access key in the `Authorization` header: `Authorization: Bearer wg_pat_...`.
Make the key in Wavegrain, Settings, Connect an AI agent, and tick the permissions it needs:

| Permission | Lets the key |
| --- | --- |
| `read` | Price a slideshow, follow a job, list and read slideshows |
| `write` | Download a slideshow as a ZIP |
| `generate` | Make slideshows, which spends credits |

Each key has a daily credit limit you set in Settings; a request that could pass it is refused before anything is spent.
See [Authentication](/developers/authentication) for how keys expire and how to revoke one.

## Make a slideshow in three steps

1. Ask what it costs:

```bash
curl -X POST https://wavegrain.com/api/v1/slideshows/estimate \
  -H "Authorization: Bearer $WAVEGRAIN_KEY" -H "Content-Type: application/json" \
  -d '{"slideCount": 6}'
```

The answer's `credits` is the most it can cost.

2. Make it, with at least that many credits as `maxCredits`:

```bash
curl -X POST https://wavegrain.com/api/v1/slideshows \
  -H "Authorization: Bearer $WAVEGRAIN_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: rice-tips-2026-11-12" \
  -d '{"topic": "Three ways to keep rice fluffy", "slideCount": 6, "maxCredits": 14}'
```

It answers `202` with a job: `{ "id": "gen_...", "state": "writing", "creditsReserved": 14 }`.
Only what it really costs is charged; slides that get a real photo cost nothing for their image.

3. Follow the job about every 20 seconds until it is ready, then read the slideshow:

```bash
curl https://wavegrain.com/api/v1/jobs/gen_... -H "Authorization: Bearer $WAVEGRAIN_KEY"
curl https://wavegrain.com/api/v1/slideshows/<slideshowId> -H "Authorization: Bearer $WAVEGRAIN_KEY"
```

Instead of asking, you can add a [webhook](/developers/webhooks): Wavegrain then sends `slideshow.ready`, `slideshow.needs_images` or `slideshow.failed` to your server, with the job's id in `jobId`.
A job is `writing`, then `making_images`, then `ready`.
`needs_images` means it is made but some slides (`emptySlides`) have no image yet; give them one in Wavegrain before you download it.
`failed` says why in `message`.

## What a slideshow takes

| Field | Meaning |
| --- | --- |
| `topic` | What it is about. A link to a post is refused: copy a post instead (below). |
| `brandId` | The brand whose voice, colours and call to action it uses. Default: your active brand. `GET https://wavegrain.com/api/v1/accounts` lists your brands. |
| `formatId` | A saved format, which sets the brand, kind of post, slide count and size; then leave the other settings out. |
| `slideCount` | 3 to 10 slides. Default 6. |
| `structure`, `outputProfile`, `styleId`, `hook`, `ctaCardId`, `groupId` | The kind of post, the size, the look, the opening line, the last slide's card, and an account group whose notes shape the words. |
| `photosOnly` | `true`: real photos only, no AI images, so only the words cost. |
| `maxCredits` | The most you allow it to spend. Required. |

## Copy a post's look

```bash
curl -X POST https://wavegrain.com/api/v1/slideshows/copies \
  -H "Authorization: Bearer $WAVEGRAIN_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://www.instagram.com/p/...", "topic": "Three ways to keep rice fluffy", "maxCredits": 8}'
```

It copies the layout, type and colours of an Instagram post or reel, a TikTok photo post or an X post, never its words, photos or branding, and writes a new slideshow in your brand's voice.
The look is free; the slideshow costs credits only when it is made, and `aiImages` (0 to 2) allows AI images when no real photo fits.
The answer is a job, as above; the slideshow it makes is `tailored` and comes with a numbered preview sheet (`sheetUrl`).

## Read and download

`GET https://wavegrain.com/api/v1/slideshows` lists your slideshows, newest first, with `limit` and `cursor`.
`GET https://wavegrain.com/api/v1/slideshows/{id}` answers every slide's image (`imageUrl`) and words (`text`), the caption, the approval and the link that opens it in Wavegrain.
`POST https://wavegrain.com/api/v1/slideshows/{id}/export` answers a ZIP link that works without a key for a short time; it is refused with `409` while a slide has no image or its text does not fit, and the message names the slides.

## Retry safely

Send an `Idempotency-Key` header with each `POST /slideshows` and `POST /slideshows/copies`: 1 to 255 characters of your own.
The same key and body answer the first job for 24 hours and charge nothing again; another body under the key answers `409`.

## Errors

Every error has the shape described in [Limits and errors](/developers/limits-and-errors).

| Status | When |
| --- | --- |
| `400` | The body is not valid, or `maxCredits` is below the price; nothing was spent. |
| `402` | Not enough credits, the plan ended, or the credits are on hold. |
| `403` | The key lacks the permission. |
| `404` | No such slideshow, job, brand, format, group or style of yours. |
| `409` | The `Idempotency-Key` was used for another request, or a slideshow cannot be downloaded yet. |
| `429` | Too many requests, this month's slideshows are used, or the key's daily credit limit is reached. |
| `503` | Wavegrain could not start the job; nothing was spent. Try again in a minute. |

## Post it

Post it to your connected accounts with `POST https://wavegrain.com/api/v1/posts` and its `slideshowId`, as the [Posting API](/developers/posting-api) shows under "Post a Wavegrain slideshow".
The account owner confirms it in Wavegrain first, unless they trusted your key.
