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.
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 for how keys expire and how to revoke one.
Make a slideshow in three steps
- Ask what it costs:
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.
- Make it, with at least that many credits as
maxCredits:
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.
- Follow the job about every 20 seconds until it is ready, then read the slideshow:
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: 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
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.
| 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 shows under "Post a Wavegrain slideshow".
The account owner confirms it in Wavegrain first, unless they trusted your key.
Something wrong or missing? Write to support@wavegrain.com.