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:

PermissionLets the key
readPrice a slideshow, follow a job, list and read slideshows
writeDownload a slideshow as a ZIP
generateMake 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

  1. 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.

  1. 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.

  1. 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

FieldMeaning
topicWhat it is about. A link to a post is refused: copy a post instead (below).
brandIdThe brand whose voice, colours and call to action it uses. Default: your active brand. GET https://wavegrain.com/api/v1/accounts lists your brands.
formatIdA saved format, which sets the brand, kind of post, slide count and size; then leave the other settings out.
slideCount3 to 10 slides. Default 6.
structure, outputProfile, styleId, hook, ctaCardId, groupIdThe kind of post, the size, the look, the opening line, the last slide's card, and an account group whose notes shape the words.
photosOnlytrue: real photos only, no AI images, so only the words cost.
maxCreditsThe 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.

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