Create a carousel

Posteady writes the copy for each slide, designs it, and saves every slide as a JPEG image in your media library. Generation is not a single request: you submit it, check its status until it finishes, then publish with the images you get back.

Flow

1. (Optional) List options to find the IDs of templates and brands.
2. Submit the request — you get a carouselId right away.
3. Check the status every 20–30 seconds until it is completed or failed.
4. Publish or schedule with the mediaId of each finished slide.

Generation usually finishes within one to three minutes. A 5–6 slide carousel from a topic took about a minute; more slides, link sources, and AI images take longer.

Submit the request

requestId is a UUID you generate. Provide exactly one content source: topic, text, or url.

curl --request POST "https://www.posteady.com/api/v1/carousels" \
  --header "Authorization: Bearer $POSTEADY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "requestId": "77777777-7777-4777-8777-777777777777",
  "topic": "Five mistakes first-time cafe owners make in their opening month",
  "slideCount": 5,
  "language": "en"
}'

{
  "carouselId": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
  "status": "queued"
}

An accepted request returns HTTP 202. Problems you can fix — invalid input, plan, insufficient credits, an unknown template or brand — are returned as errors at submission.

Credits

Each generated carousel is charged to the organization's credits. Read the amount from generationCredits in the options response. With imageMode set to ai, each generated image is charged in addition.

If credits are insufficient at submission, the request returns 402 INSUFFICIENT_CREDITS and nothing is created. If generation fails after submission, its generation credits are refunded.

Check the status

curl --request GET "https://www.posteady.com/api/v1/carousels/cccccccc-cccc-4ccc-8ccc-cccccccccccc" \
  --header "Authorization: Bearer $POSTEADY_API_KEY"

{
  "carouselId": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
  "status": "completed",
  "editorUrl": "https://www.posteady.com/carousel/cccccccc-cccc-4ccc-8ccc-cccccccccccc",
  "title": "Five mistakes first-time cafe owners make",
  "caption": "Opening a cafe? Avoid these five mistakes in your first month.",
  "aspectRatio": "4:5",
  "slideCount": 5,
  "images": [
    {
      "mediaId": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
      "url": "https://media.posteady.com/media/example/slide-01.jpg",
      "width": 1080,
      "height": 1350
    }
  ]
}

images lists the slides in order. Open editorUrl to change copy or design in the Posteady editor. After an edit, images can be empty because the earlier images no longer match the content. Download the carousel or create a post from it in the editor to render it again, then check the status once more.

You can also read carousels made in the Posteady app. The carouselId is the last part of the editor URL.

Templates and brands

curl --request GET "https://www.posteady.com/api/v1/carousels/options" \
  --header "Authorization: Bearer $POSTEADY_API_KEY"

Use a templateId from templates and a brandId from brands in the request. Templates provided by Posteady are listed by default; add templateSource=workspace for templates saved in this workspace. When nextTemplateCursor is present, pass it as cursor to read the next page.

Publish the slides

Finished slides are images in the workspace media library. Put their mediaId values, in order, into items of an Instagram media request, and use caption as the post text if you like. An Instagram carousel takes 2–10 items, so choose which slides to publish when a carousel has more than 10.

curl --request POST "https://www.posteady.com/api/v1/posts" \
  --header "Authorization: Bearer $POSTEADY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "accountIds": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "instagram": {
    "requestId": "33333333-3333-4333-8333-333333333333",
    "contentType": "FEED",
    "caption": "Opening a cafe? Avoid these five mistakes in your first month.",
    "items": [
      {
        "mediaId": "dddddddd-dddd-4ddd-8ddd-dddddddddddd"
      },
      {
        "mediaId": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee"
      }
    ]
  }
}'

The publishing requestId is separate from the one used for generation. Track the result with publishing status. Account requirements and per-format input are in the Instagram media guide.

Sending a request again

If you did not receive a response, send it again with the same requestId and the same body. You get the same carousel and are not charged again. A different body with the same requestId returns 409 REQUEST_CONFLICT.

Sending a failed request again with the same requestId returns the same failed result. Use a new requestId to try again.

When generation fails

Generation credits are refunded for every failure except RENDER_FAILED, where the carousel was saved.

Good to know

• Videos in the source are used as still images. Slides that contain video are created in the Posteady app.
• A template that uses uploaded fonts missing from the workspace cannot be generated through the API. In the app you can choose replacement fonts.
• With MCP, the same flow uses the create_carousel, get_carousel, and list_carousel_options tools. See MCP tools.

Create carousel reference · Retries · Error codes