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.
POST /api/v1/slideshows is part of the Carousel API. Every call needs an access key: see 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
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:
{
"id": "mcpgen_8Qz2Lk",
"kind": "canvas",
"state": "writing",
"creditsReserved": 14
}
More in the Carousel API
- Estimate a slideshow's price:
POST /api/v1/slideshows/estimate - List slideshows:
GET /api/v1/slideshows - Make a slideshow in a post's look:
POST /api/v1/slideshows/copies - Follow a slideshow job:
GET /api/v1/jobs/{id} - Get a slideshow:
GET /api/v1/slideshows/{id} - Download a slideshow:
POST /api/v1/slideshows/{id}/export - All endpoints
Something wrong or missing? Write to support@wavegrain.com.