Postnitro Carousel

PostNitro Carousel Generator

Create social media carousel posts via the PostNitro.ai Embed API. Two workflows:

• AI Generation — provide a topic, article, or text and let AI create the carousel
• Content Import — provide your own slide content with full control, including infographics

Prerequisites

Set the following environment variables:

1. POSTNITRO_API_KEY — Obtained from PostNitro.ai account settings under "Embed".
2. POSTNITRO_TEMPLATE_ID — ID of a carousel template from the user's PostNitro account.
3. POSTNITRO_BRAND_ID — ID of a brand profile from the user's PostNitro account.
4. POSTNITRO_PRESET_ID — (Required for AI generation) An AI preset ID from the user's PostNitro account.

If the user doesn't have these, direct them to https://postnitro.ai to sign up (free plan: 5 credits/month).

API Overview

Base URL: https://embed-api.postnitro.ai

Authentication: All requests require the header embed-api-key: $POSTNITRO_API_KEY.

Content-Type: application/json (for POST requests).

Async Workflow

All carousel creation is asynchronous:

1. Initiate — POST /post/initiate/generate or POST /post/initiate/import → returns embedPostId
2. Poll Status — GET /post/status/{embedPostId} → poll until status is "COMPLETED"
3. Get Output — GET /post/output/{embedPostId} → download the finished carousel

Endpoint 1: AI-Powered Generation

POST /post/initiate/generate

Use when the user provides a topic, article URL, or text and wants AI to generate carousel content.

Request Body

aiGeneration Object

aiGeneration.type values:

• "text" — Generate from user-provided text content
• "article" — Generate from an article URL (pass the URL as context)
• "x" — Generate from an X (Twitter) post or thread URL

Example (from text)

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",
    "requestorId": "user123",
    "templateId": "'"$POSTNITRO_TEMPLATE_ID"'",
    "brandId": "'"$POSTNITRO_BRAND_ID"'",
    "presetId": "'"$POSTNITRO_PRESET_ID"'",
    "responseType": "PNG",
    "aiGeneration": {
      "type": "text",
      "context": "Digital marketing tips for small businesses: 1. Focus on local SEO 2. Use social proof 3. Start email marketing early",
      "instructions": "Focus on actionable tips that can be implemented immediately"
    }
  }'

Example (from article URL)

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",
    "requestorId": "user123",
    "templateId": "'"$POSTNITRO_TEMPLATE_ID"'",
    "brandId": "'"$POSTNITRO_BRAND_ID"'",
    "presetId": "'"$POSTNITRO_PRESET_ID"'",
    "responseType": "PNG",
    "aiGeneration": {
      "type": "article",
      "context": "https://example.com/blog/digital-marketing-tips",
      "instructions": "Focus on actionable tips for small businesses"
    }
  }'

Response

{
  "success": true,
  "message": "CAROUSEL generation initiated",
  "data": {
    "embedPostId": "post123",
    "status": "PENDING"
  }
}

Credit cost: 2 credits per slide.

Endpoint 2: Content Import

POST /post/initiate/import

Use when the user provides their own slide content.

Request Body

Slide Structure

Slide Rules

• Exactly 1 starting_slide (required)
• At least 1 body_slide (required)
• Exactly 1 ending_slide (required)

Infographics Layout

Set layoutType to "infographic" on a body_slide to replace the image area with structured data.

layoutConfig object:

columnData items:

Infographics notes:

• layoutType: "infographic" replaces the slide image with the infographic
• Column count must not exceed 3
• Cyclical display ("cycle") only uses data from the first column
• Grid display ("grid") uses data from all columns

Example (Default Slides)

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",
        "sub_heading": "My Awesome Subtitle",
        "heading": "Welcome to the Carousel!",
        "description": "This is how you start with a bang.",
        "cta_button": "Swipe to learn more"
      },
      {
        "type": "body_slide",
        "heading": "Section 1: The Core Idea",
        "description": "Explain your first key point here."
      },
      {
        "type": "body_slide",
        "heading": "Section 2: Deeper Dive",
        "description": "More details for the second point."
      },
      {
        "type": "ending_slide",
        "heading": "Get Started Today!",
        "sub_heading": "Ready to Act?",
        "description": "A final encouraging message.",
        "cta_button": "Visit Our Website"
      }
    ]
  }'

Example (With Infographics)

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": "PostNitro Infographics",
        "sub_heading": "Import API Feature",
        "description": "Create stunning visual carousels with structured data."
      },
      {
        "type": "body_slide",
        "heading": "Grid Layout",
        "description": "Display data in an organized grid format.",
        "layoutType": "infographic",
        "layoutConfig": {
          "columnCount": 2,
          "columnDisplay": "grid",
          "displayCounterAs": "counter",
          "hasHeader": true,
          "columnData": [
            {
              "header": "Features",
              "content": [
                {"title": "Grid Display", "description": "Organized columns for comparison."},
                {"title": "Counter Support", "description": "Numbered items for sequence."}
              ]
            },
            {
              "header": "Options",
              "content": [
                {"title": "Column Headers", "description": "Enable/disable per column."},
                {"title": "Flexible Columns", "description": "Choose 1, 2, or 3 columns."}
              ]
            }
          ]
        }
      },
      {
        "type": "ending_slide",
        "heading": "Try PostNitro Infographics",
        "sub_heading": "Start Creating Today",
        "cta_button": "Get Your API Key"
      }
    ]
  }'

Response

{
  "success": true,
  "message": "CAROUSEL generation initiated",
  "data": {
    "embedPostId": "post123",
    "status": "PENDING"
  }
}

Credit cost: 1 credit per slide.

Endpoint 3: Check Post Status

GET /post/status/{embedPostId}

No request body. Pass embedPostId as a path parameter.

Headers: embed-api-key: $POSTNITRO_API_KEY (required)

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

Response

{
  "success": true,
  "data": {
    "embedPostId": "post123",
    "embedPost": {
      "id": "post123",
      "postType": "CAROUSEL",
      "status": "COMPLETED",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:35:00Z"
    },
    "logs": [
      {
        "id": "log1",
        "embedPostId": "post123",
        "step": "INITIATED",
        "status": "SUCCESS",
        "message": "Post generation initiated",
        "timestamp": "2024-01-15T10:30:00Z"
      },
      {
        "id": "log2",
        "embedPostId": "post123",
        "step": "PROCESSING",
        "status": "SUCCESS",
        "message": "Content generated successfully",
        "timestamp": "2024-01-15T10:32:00Z"
      },
      {
        "id": "log3",
        "embedPostId": "post123",
        "step": "COMPLETED",
        "status": "SUCCESS",
        "message": "Post generation completed",
        "timestamp": "2024-01-15T10:35:00Z"
      }
    ]
  }
}

Poll every 3–5 seconds. Check data.embedPost.status for completion. The logs array provides step-by-step progress.

Endpoint 4: Get Output

GET /post/output/{embedPostId}

No request body. Pass embedPostId as a path parameter.

Headers: embed-api-key: $POSTNITRO_API_KEY (required)

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

Response (PNG)

{
  "success": true,
  "data": {
    "embedPost": {
      "id": "post123",
      "postType": "CAROUSEL",
      "responseType": "PNG",
      "status": "COMPLETED",
      "credits": 4,
      "createdAt": "2026-02-19T21:11:50.115Z",
      "updatedAt": "2026-02-19T21:12:08.333Z"
    },
    "result": {
      "id": "result123",
      "name": "Welcome to the Carousel!",
      "size": {
        "id": "4:5",
        "dimensions": { "width": 1080, "height": 1350 }
      },
      "type": "png",
      "mimeType": "image/png",
      "data": [
        "https://...supabase.co/.../slide_0.png",
        "https://...supabase.co/.../slide_1.png"
      ]
    }
  }
}

Response (PDF)

{
  "success": true,
  "data": {
    "embedPost": {
      "id": "post123",
      "postType": "CAROUSEL",
      "responseType": "PDF",
      "status": "COMPLETED",
      "credits": 10,
      "createdAt": "2026-02-19T21:11:50.115Z",
      "updatedAt": "2026-02-19T21:12:08.333Z"
    },
    "result": {
      "id": "result123",
      "name": "Welcome to the Carousel!",
      "size": {
        "id": "4:5",
        "dimensions": { "width": 1080, "height": 1350 }
      },
      "type": "pdf",
      "mimeType": "application/pdf",
      "data": "https://...supabase.co/.../output.pdf"
    }
  }
}

Result Object

Download the URLs directly to save the carousel files.

Step-by-Step Usage

AI-Generated Carousel

1. Confirm POSTNITRO_API_KEY, POSTNITRO_TEMPLATE_ID, POSTNITRO_BRAND_ID, and POSTNITRO_PRESET_ID are set.
2. Ask the user for their generation type (text, article, or x), the corresponding content (text, article URL, or X post URL), and any style instructions.
3. Send the generate request to POST /post/initiate/generate.
4. Extract embedPostId from the response.
5. Poll GET /post/status/{embedPostId} every 3–5 seconds until status is "COMPLETED".
6. Call GET /post/output/{embedPostId} to get the result. Download the URL(s) from data to save files.

Custom Content Carousel

1. Confirm POSTNITRO_API_KEY, POSTNITRO_TEMPLATE_ID, and POSTNITRO_BRAND_ID are set.
2. Gather slide content from the user. Structure as: 1 starting_slide → 1+ body_slide → 1 ending_slide.
3. For data-heavy slides, use layoutType: "infographic" with a layoutConfig object.
4. Send the import request to POST /post/initiate/import.
5. Follow the same poll → output flow.

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.

Error Handling

• If the API returns an authentication error, verify POSTNITRO_API_KEY is correct and the account is active.
• If credits are exhausted, inform the user. Free plan: 5 credits/month. Paid plan: 250+ credits/month ($10/month base).
• If the status poll indicates failure, retry the initiation once before reporting the error.
• All endpoints are rate-limited per API key — space requests appropriately.
• Default responseType is "PDF". Always specify "PNG" explicitly if individual slide images are needed.

Links

• Documentation: https://postnitro.ai/docs/embed/api
• Get API Key: https://postnitro.ai/app/embed
• Postman Collection: https://www.postman.com/postnitro/postnitro-embed-apis/overview
• Support: support@postnitro.ai