# Make a slideshow from a topic

> Make a slideshow from a topic with the Wavegrain Carousel API: POST /api/v1/slideshows. Parameters, request body, responses and an example request.

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

`POST /api/v1/slideshows` is part of the [Carousel API](/developers/carousel-api). Every call needs an access key: see [Authentication](/developers/authentication).

Needs the `generate` permission.

Writes a slideshow about the topic in a brand's voice (`brandId`, or your active brand) or with a saved format (`formatId`), finds photos and makes AI images where none fits (`photosOnly: true` makes none). It answers a job at once; follow it with GET /api/v1/jobs/{id}, usually ready in under two minutes.

Refused before anything is spent when it could cost more than `maxCredits`, more than the balance, more than the key's daily limit, or when this month's slideshows are used. Only what it really costs is charged. A link to a post is refused: copy a post with POST /api/v1/slideshows/copies.

## Parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | Your own key for this request, so a retry answers the same job and never pays twice. |

## Request body

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `topic` | string | yes | What the slideshow is about. |
| `formatId` | string | no | A saved format from list_formats. Default: your active brand with the settings below. |
| `brandId` | string | no | Only without formatId: the brand to write for. Default: your active brand. |
| `groupId` | string | no | Only without formatId: an account group (list_accounts) whose notes shape the script. |
| `slideCount` | integer | no | Only without formatId: how many slides. Default 6. |
| `structure` | "hook-proof-cta" \| "listicle" \| "before-after" \| "educational" \| "story" \| "quote" \| "ranking" | no | The kind of post: hook-proof-cta (Hook, proof, then a clear call to action); listicle (A numbered list); before-after (A transformation or comparison); educational (Teaches one idea step by step); story (A first-person narrative arc); quote (Quote or affirmation cards); ranking (Tier list or best-to-worst ranking); get_playbook gives each one's slides. Default: picked from the topic. |
| `outputProfile` | "clean-square" \| "clean-portrait" \| "instagram-feed" \| "instagram-feed-3-4" \| "clean-vertical" \| "tiktok" \| "instagram-reels" | no | Slide size, width:height: clean-square 1:1, clean-portrait 4:5, instagram-feed 4:5 (default), instagram-feed-3-4 3:4, clean-vertical 9:16, tiktok 9:16, instagram-reels 9:16. |
| `styleId` | "clean-ugc" \| "clean-social" \| "quiet-editorial" \| "bold-statement" \| "mens-looksmaxxing" \| "comparison-grid" \| "study-notes" \| "aesthetic-soft" \| "accent-pop" | no | Text look: clean-ugc (Effortless lowercase native look); clean-social (Bold sans in normal case with a strong shadow); quiet-editorial (Serif); bold-statement (Big all-caps hook over a dramatic scene); mens-looksmaxxing (Dark portrait); comparison-grid (Before-after or best-worst decks); study-notes (Small clean caption low on a desk/flatlay); aesthetic-soft (Airy scene); accent-pop (Clean sans with a warm accent color). |
| `hook` | string | no | The cover's hook line, or the idea for it, in the brand's voice. |
| `ctaCardId` | string | no | A CTA card from get_brand to close with. |
| `photosOnly` | boolean | no | true: no AI image, so only the script costs; a slide no photo fits stays empty. |
| `maxCredits` | integer | yes | Most credits this call may spend; refused, spending nothing, if it could cost more. |

## Example request

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

## Responses

| Status | Meaning |
| --- | --- |
| 202 | The job. |
| 400 | The body is not valid (`details` names the field), or the request cannot be done as asked, such as maxCredits below the price. |
| 401 | No access key, or an unknown, revoked or expired one |
| 402 | Not enough credits, the plan ended, or the credits are on hold; nothing was spent. |
| 403 | The key lacks the permission, or the account has no active plan |
| 404 | No such brand, format, group or style of yours. |
| 409 | The Idempotency-Key was used for another request, or that request is still running. |
| 429 | Too many requests, this month's slideshows are used, or the key's daily credit limit is reached; nothing was spent. |
| 500 | Something went wrong on Wavegrain's side; try again, and send the request id if it keeps failing. |
| 503 | Wavegrain could not start the job; nothing was spent. Try again in a minute. |

A successful answer:

```json
{
  "id": "mcpgen_8Qz2Lk",
  "kind": "canvas",
  "state": "writing",
  "creditsReserved": 14
}
```

## More in the Carousel API

- [Estimate a slideshow's price](/developers/api/estimate-slideshow): `POST /api/v1/slideshows/estimate`
- [List slideshows](/developers/api/list-slideshows): `GET /api/v1/slideshows`
- [Make a slideshow in a post's look](/developers/api/copy-post): `POST /api/v1/slideshows/copies`
- [Follow a slideshow job](/developers/api/get-job): `GET /api/v1/jobs/{id}`
- [Get a slideshow](/developers/api/get-slideshow): `GET /api/v1/slideshows/{id}`
- [Download a slideshow](/developers/api/export-slideshow): `POST /api/v1/slideshows/{id}/export`
- [All endpoints](/developers/api)
