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

NameInTypeRequiredNotes
Idempotency-KeyheaderstringnoYour own key for this request, so a retry answers the same job and never pays twice.

Request body

FieldTypeRequiredNotes
topicstringyesWhat the slideshow is about.
formatIdstringnoA saved format from list_formats. Default: your active brand with the settings below.
brandIdstringnoOnly without formatId: the brand to write for. Default: your active brand.
groupIdstringnoOnly without formatId: an account group (list_accounts) whose notes shape the script.
slideCountintegernoOnly without formatId: how many slides. Default 6.
structure"hook-proof-cta" | "listicle" | "before-after" | "educational" | "story" | "quote" | "ranking"noThe 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"noSlide 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"noText 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).
hookstringnoThe cover's hook line, or the idea for it, in the brand's voice.
ctaCardIdstringnoA CTA card from get_brand to close with.
photosOnlybooleannotrue: no AI image, so only the script costs; a slide no photo fits stays empty.
maxCreditsintegeryesMost 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

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

Something wrong or missing? Write to support@wavegrain.com.