PostNitro Carousel Generator

Generate social media carousel posts via the PostNitro.ai Embed API. Two workflows: AI generation (topic/article/X post → carousel) and content import (your own slides, with optional infographics).

Setup

1. Sign up at https://postnitro.ai (free plan: 5 credits/month)
2. Go to account settings → "Embed" → generate an API key
3. Set up your template, brand, and AI preset in the PostNitro dashboard
4. Set environment variables:

   export POSTNITRO_API_KEY="your-api-key"
   export POSTNITRO_TEMPLATE_ID="your-template-id"
   export POSTNITRO_BRAND_ID="your-brand-id"
   export POSTNITRO_PRESET_ID="your-ai-preset-id"
   

Base URL: https://embed-api.postnitro.ai Auth header: embed-api-key: $POSTNITRO_API_KEY

Core Workflow

All carousel creation is asynchronous: Initiate → Poll Status → Get Output.

1. Generate a carousel with AI

curl -X POST 'https://embed-api.postnitro.ai/post/initiate/generate' \
  -H 'Content-Type: application/json' \
  -H "embed-api-key: $POSTNITRO_API_KEY" \
  -d '{
    "postType": "CAROUSEL",
    "templateId": "'"$POSTNITRO_TEMPLATE_ID"'",
    "brandId": "'"$POSTNITRO_BRAND_ID"'",
    "presetId": "'"$POSTNITRO_PRESET_ID"'",
    "responseType": "PNG",
    "aiGeneration": {
      "type": "text",
      "context": "5 tips for growing your LinkedIn audience in 2026",
      "instructions": "Professional tone, actionable advice"
    }
  }'

Returns { "success": true, "data": { "embedPostId": "post123", "status": "PENDING" } }. Save the embedPostId.

aiGeneration.type values:

• "text" — context is the text content to turn into a carousel
• "article" — context is an article URL to extract and convert
• "x" — context is an X (Twitter) post or thread URL

See examples/generate-from-text.json, examples/generate-from-article.json, and examples/generate-from-x-post.json.

2. Import your own slide content

curl -X POST 'https://embed-api.postnitro.ai/post/initiate/import' \
  -H 'Content-Type: application/json' \
  -H "embed-api-key: $POSTNITRO_API_KEY" \
  -d '{
    "postType": "CAROUSEL",
    "templateId": "'"$POSTNITRO_TEMPLATE_ID"'",
    "brandId": "'"$POSTNITRO_BRAND_ID"'",
    "responseType": "PNG",
    "slides": [
      { "type": "starting_slide", "heading": "Your Title", "description": "Intro text" },
      { "type": "body_slide", "heading": "Key Point", "description": "Details here" },
      { "type": "ending_slide", "heading": "Take Action!", "cta_button": "Learn More" }
    ]
  }'

Returns same response format with embedPostId.

Slide rules:

• Exactly 1 starting_slide (required)
• At least 1 body_slide (required)
• Exactly 1 ending_slide (required)
• heading is required on every slide

Slide fields: heading (required), sub_heading, description, image (URL), background_image (URL), cta_button, layoutType, layoutConfig.

For infographic slides, set layoutType: "infographic" on body slides — replaces the image with structured data columns. See examples/import-infographics.json and references/api-reference.md for full infographics config.

3. Check post status

curl -X GET "https://embed-api.postnitro.ai/post/status/$EMBED_POST_ID" \
  -H "embed-api-key: $POSTNITRO_API_KEY"

Poll every 3–5 seconds until data.embedPost.status is "COMPLETED". The logs array shows step-by-step progress.

4. Get the output

curl -X GET "https://embed-api.postnitro.ai/post/output/$EMBED_POST_ID" \
  -H "embed-api-key: $POSTNITRO_API_KEY"

Returns downloadable URLs in data.result.data:

• PNG: Array of URLs (one per slide)
• PDF: Single URL

See references/api-reference.md for full response schemas.

Common Patterns

Pattern 1: LinkedIn thought leadership carousel

Generate a carousel from a topic with professional tone:

{
  "aiGeneration": {
    "type": "text",
    "context": "5 mistakes startups make with their LinkedIn strategy and how to fix each one",
    "instructions": "Professional but conversational tone. Each slide should have one clear takeaway."
  }
}

Pattern 2: Repurpose a blog post

Turn an existing article into a carousel:

{
  "aiGeneration": {
    "type": "article",
    "context": "https://yourblog.com/posts/social-media-strategy-2026",
    "instructions": "Extract the 5 most actionable points. Keep slide text concise."
  }
}

Pattern 3: Repurpose an X thread

Convert a viral X thread into a visual carousel:

{
  "aiGeneration": {
    "type": "x",
    "context": "https://x.com/username/status/1234567890",
    "instructions": "Maintain the original voice and key points"
  }
}

Pattern 4: Data-driven infographic carousel

Import slides with structured infographic layouts:

See examples/import-infographics.json for a complete example with grid and cycle layouts.

Content Strategy Tips

• LinkedIn: Professional tone, actionable insights, 6–10 slides, clear CTA.
• Instagram: Visual-first, concise text, 5–8 slides, storytelling arc.
• TikTok: Trendy, punchy, 4–7 slides, hook on slide 1.
• X (Twitter): Data-driven, 3–6 slides, provocative opening.

Common Gotchas

1. Default responseType is PDF — always specify "PNG" explicitly if you want individual slide images.
2. heading is required on every slide — omitting it returns an error.
3. Slide structure is strict — exactly 1 starting, at least 1 body, exactly 1 ending.
4. Article type needs a URL — "article" type expects a URL as context, not plain text.
5. X type needs an X post URL — "x" type expects https://x.com/... or https://twitter.com/... as context.
6. Infographics replace images — setting layoutType: "infographic" overrides any image on that slide.
7. Cyclical infographics use first column only — columnDisplay: "cycle" ignores data in columns 2+.
8. Max 3 columns — columnCount cannot exceed 3 for infographic layouts.
9. Image URLs must be public — image and background_image fields require publicly accessible URLs.
10. Credits vary by method — AI generation costs 2 credits/slide, content import costs 1 credit/slide.

Credits & Pricing

• Content import: 1 credit per slide
• AI generation: 2 credits per slide

Supporting Resources

Reference docs:

• references/api-reference.md — Complete endpoint reference with request/response schemas and infographics config

Ready-to-use examples:

• examples/EXAMPLES.md — Index of all examples
• examples/generate-from-text.json — AI generation from text
• examples/generate-from-article.json — AI generation from article URL
• examples/generate-from-x-post.json — AI generation from X post
• examples/import-default.json — Basic slide import
• examples/import-infographics.json — Import with infographic layouts

Quick Reference

# Auth
Header: embed-api-key: $POSTNITRO_API_KEY

# AI generation
POST /post/initiate/generate  { postType, templateId, brandId, presetId, responseType?, requestorId?, aiGeneration: { type, context, instructions? } }

# Content import
POST /post/initiate/import  { postType, templateId, brandId, responseType?, requestorId?, slides: [{ type, heading, ... }] }

# Check status (poll until COMPLETED)
GET /post/status/{embedPostId}

# Get output (download URLs)
GET /post/output/{embedPostId}

Tips for the Agent

• Always confirm the user has set POSTNITRO_API_KEY, POSTNITRO_TEMPLATE_ID, POSTNITRO_BRAND_ID before calling any endpoint.
• POSTNITRO_PRESET_ID is only required for AI generation, not for content import.
• For "article" type, the context must be a URL — not article text. For article text, use "text" type.
• For "x" type, the context must be an X/Twitter post URL.
• Default responseType is "PDF" — always pass "PNG" if the user wants individual slide images.
• When importing slides, always structure as: 1 starting_slide → 1+ body_slide → 1 ending_slide.
• For data-heavy content, suggest using infographic layouts on body slides instead of plain text.
• Poll GET /post/status/{embedPostId} every 3–5 seconds — don't hammer the endpoint.
• After getting output, the data field contains download URLs — present them to the user directly.
• If the user doesn't specify a platform, suggest LinkedIn (most common carousel use case).
• Warn users about credit costs upfront: AI generation is 2x the cost of content import.