Initiate Import

POST https://embed-api.postnitro.ai/post/initiate/import

Creates a carousel post by importing your own slide content.

Headers

Content-Type: application/json
embed-api-key: your-api-key-here (required)

Request Body

Field	Type	Required	Description	Allowed Values
`postType`	string	Yes	Type of post to generate	`"CAROUSEL"` , `"IMAGE"`
`requestorId`	string	No	Custom identifier for tracking	Any string
`templateId`	string	Yes	ID of the template to use	Valid template ID
`brandId`	string	Yes	ID of the brand configuration	Valid brand ID
`responseType`	string	No	Output format (default: “DESIGN”)	`"DESIGN"`, `"PDF"`, `"PNG"`
`slides`	`array` , `object`	Yes	Array of slide objects for `postType CAROUSEL` and an object for `postType IMAGE`	See slide structure below
`generateImages`	object	No	Opt-in AI image generation — generates images and bakes them into the design before rendering	See AI Image Generation

Slide Structure

Each slide must have the following structure:

Field	Type	Required	Description	Allowed Values
`type`	string	Yes for postType `CAROUSEL` and not required for postType `IMAGE`	Type of slide	`"starting_slide"`, `"body_slide"`, `"ending_slide"`
`heading`	string	Yes	Main heading text	Any string
`sub_heading`	string	No	Subtitle text	Any string
`description`	string	No	Description text	Any string
`image`	string	No	Image URL	Valid URL
`background_image`	string	No	Background image URL	Valid URL
`cta_button`	string	No	Call-to-action button text	Any string
`layoutType`	string	No	Slide layout type. Available on both `CAROUSEL` and `IMAGE` slides	`"default"` (default), `"infographic"`
`layoutConfig`	object	No	Infographics configuration, used when `layoutType` is `"infographic"`. If omitted, the slide falls back to the default layout	Layout Configuration

Layout Configuration (Infographics)

All fields are optional; any field you omit uses its default.

Field	Type	Required	Default	Description	Allowed Values
`hasHeader`	boolean	No	`true`	Display a header for each column	`true`, `false`
`columnCount`	number	No	`1`	Number of columns to display	`1`, `2`, `3`
`displayCounterAs`	string	No	`"counter"`	How the counter is displayed	`"none"`, `"counter"`
`columnDisplay`	string	No	`"grid"`	Cyclical or grid layout	`"cycle"`, `"grid"`
`columnData`	array	No	`[]`	Array of column data	Column Data

Infographics Column Data

Each entry in columnData is a column:

Field	Type	Required	Description	Allowed Values
`id`	string	Yes	Unique id for the column. Caller-provided — stored as-is, not auto-generated	Any string
`header`	string	No	Column header text (shown when `hasHeader` is `true`)	Any string
`content`	array	Yes	Items in the column	Content Item

Infographics Content Item

Each element of a column’s content array:

Field	Type	Required	Description	Allowed Values
`id`	string	Yes	Unique id for the item. Caller-provided — stored as-is, not auto-generated	Any string
`icon`	string \| null	No	Optional icon	Any string or `null`
`title`	string	Yes	Item title	Any string
`description`	string	Yes	Description as an HTML string	e.g. `"<p dir=\"ltr\">Description</p>"`
`titleEnabled`	boolean	No	Whether to show the title	`true`, `false`
`descriptionEnabled`	boolean	No	Whether to show the description	`true`, `false`

Important Information for CAROUSEL!

Exactly 1 starting_slide (required) — must be the first slide
At least 1 body_slide (required) — placed between the starting and ending slides
Exactly 1 ending_slide (required) — must be the last slide
Column Count should not exceed 3
Layout Type set as infographic will replace the image field (any provided image is ignored on that slide)
Column Display can either be set as cycle or grid
Cyclical Infographic (columnDisplay: "cycle") accepts data in the first columnData entry only, so no need to add information in columns two or three
Slides must be an array and include type

Important Information for IMAGE!

Slides must be an object
IMAGE slides support the same infographic layout as CAROUSEL — set layoutType: "infographic" and provide layoutConfig. Beyond the six content fields, layoutType and layoutConfig are the only additional fields allowed on an IMAGE slide.

Important Information for Infographics! (IMAGE & CAROUSEL)

Available on both IMAGE (the single slide object) and CAROUSEL (per slide in the array). For CAROUSEL it can be set on any slide — starting_slide, body_slide, or ending_slide.
The id fields on each column and each content item must be provided by the caller — they are stored as-is and are not auto-generated by the import endpoint.
If layoutType is "infographic" but layoutConfig is missing, the slide falls back to the default layout.
Any layoutConfig field you omit uses its default.

Validation note: IMAGE enforces a strict field allowlist, so layoutType and layoutConfig are explicitly permitted (any other unknown field returns a 422). CAROUSEL does not restrict extra fields, so these keys pass through freely. Infographic behavior is identical on both — only the validation strictness differs.

AI Image Generation

Add an optional generateImages object to have the API generate AI images and bake them into the design before it’s rendered. Its presence is the opt-in — omit the field and no images are generated (existing behavior). Works for both CAROUSEL and IMAGE posts and with every responseType (PDF, PNG, DESIGN).

Field	Type	Required	Default	Allowed Values
`context`	string	No	Empty string if not provided	Any string — topic/brief that guides the image prompts
`imagePlacement`	string	No	`"auto"`	`"auto"`, `"background"`, `"in-line"`
`imageStrategy`	string	No	`"strategic"`	`"strategic"`, `"all"`

These are the only accepted fields — any other key inside generateImages returns a 422. Everything else the image service needs is resolved server-side: editorType from postType, the platform image model, and the copy config (socialPlatform/tone/audience/language) which defaults to LinkedIn / creative / general public / english on the import endpoint.

On direct REST calls, context is optional (it falls back as shown above). Over the MCP server and CLI, context is required — the AI agent composes it for the user. That is the only difference in how generateImages behaves across the two.

imagePlacement

Value	Behavior
`auto`	AI decides per slide whether an image is a background or placed in-line with the content.
`background`	Images are generated for slide backgrounds.
`in-line`	Images are generated to sit inside the slide content, alongside the text.

imageStrategy

Value	Behavior
`strategic`	The AI picks which slides get images, capped at ~50% of slides for a balanced look.
`all`	Every eligible slide gets an image, capped only by available credits.

Behavior & limits:

Image generation runs after the design is created and before rendering, so a rendered PDF/PNG already contains the images and a DESIGN response has them baked into the saved design (visible via editorUrl). The output shape is unchanged — no new fields.
Best-effort: if generation fails or isn’t permitted, the post still completes without images. A GENERATE_IMAGES step appears in the status logs — COMPLETED on success, FAILED (with a skip reason) otherwise.
Free plan: AI image generation is not available — the step is skipped (logged as failed) and the post completes without images.
Credits: the post’s reported credits (slide-based) are unchanged. AI images bill against the organization’s separate AI-image quota.
Image generation adds latency — keep polling status until COMPLETED.

Example Requests

Default - CAROUSEL


curl --location 'https://embed-api.postnitro.ai/post/initiate/import' \
--header 'Content-Type: application/json' \
--header 'embed-api-key: pn-your-api-key' \
--data '{
    "postType": "CAROUSEL",
    "templateId": "xtrnxgfgk9a08tmsz2601k1c",
    "brandId": "cmdhb8oe10006v0pmh6a4no6t",
    "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",
            "background_image": "https://example.com/background1.jpg"
        },
        {
            "type": "body_slide",
            "heading": "Section 1: The Core Idea",
            "description": "Explain your first key point here. This point might have multiple lines too.",
            "image": "https://example.com/image1.jpg"
        },
        {
            "type": "body_slide",
            "heading": "Section 2: Deeper Dive",
            "description": "More details for the second point.",
            "image": "https://example.com/image2.png"
        },
        {
            "type": "ending_slide",
            "sub_heading": "Ready to Act?",
            "heading": "Get Started Today!",
            "description": "A final encouraging message.",
            "cta_button": "Visit Our Website",
            "image": "https://example.com/logo.png",
            "background_image": "https://example.com/background2.jpg"
        }
    ]
}'

Default - IMAGE


curl --location 'https://embed-api.postnitro.ai/post/initiate/import' \
--header 'Content-Type: application/json' \
--header 'embed-api-key: pn-your-api-key' \
--data '{
    "postType": "IMAGE",
    "templateId": "xtrnxgfgk9a08tmsz2601k1c",
    "brandId": "cmdhb8oe10006v0pmh6a4no6t",
    "responseType": "PNG",
    "slides": {
        "sub_heading": "Ready to Act?",
        "heading": "Get Started Today!",
        "description": "A final encouraging message.",
        "cta_button": "Visit Our Website",
        "image": "https://example.com/logo.png",
        "background_image": "https://example.com/background2.jpg"
    }
}'

IMAGE with AI-generated background image

Uses generateImages to produce a background image instead of supplying one yourself.


curl --location 'https://embed-api.postnitro.ai/post/initiate/import' \
--header 'Content-Type: application/json' \
--header 'embed-api-key: pn-your-api-key' \
--data '{
    "postType": "IMAGE",
    "templateId": "xtrnxgfgk9a08tmsz2601k1c",
    "brandId": "cmdhb8oe10006v0pmh6a4no6t",
    "responseType": "PNG",
    "slides": {
        "heading": "Our 2026 Results",
        "sub_heading": "By the numbers",
        "cta_button": "Learn more"
    },
    "generateImages": {
        "context": "Annual results, upbeat and professional",
        "imagePlacement": "background",
        "imageStrategy": "strategic"
    }
}'

With Infographics


curl --location 'https://embed-api.postnitro.ai/post/initiate/import' \
--header 'Content-Type: application/json' \
--header 'embed-api-key: pn-your-api-key' \
--data '{
    "postType": "CAROUSEL",
    "templateId": "xtrnxgfgk9a08tmsz2601k1c",
    "brandId": "cmdhb8oe10006v0pmh6a4no6t",
    "responseType": "PNG",
    "slides": [
        {
            "type":"starting_slide",
            "sub_heading":"Import API Feature",
            "heading":"PostNitro Infographics",
            "description":"Create stunning visual carousels with structured data using PostNitro's powerful infographics feature.",
            "cta_button":"Learn More",
            "background_image":"https://example.com/postnitro-bg.jpg"
        },
        {
            "type":"body_slide",
            "heading":"Grid Layout Infographics",
            "description":"Display multiple data points in an organized grid format with PostNitro's flexible column system.",
            "layoutType":"infographic",
            "layoutConfig":{
                "columnCount":2,
                "columnDisplay":"grid",
                "displayCounterAs":"counter",
                "hasHeader":true,
                "columnData":[
                {
                    "id":"col-1",
                    "header":"Layout Options",
                    "content":[
                        {
                            "id":"item-1",
                            "icon":null,
                            "title":"Grid Display",
                            "description":"<p dir=\"ltr\">Organize content in structured columns for easy comparison and readability.</p>",
                            "titleEnabled":true,
                            "descriptionEnabled":true
                        },
                        {
                            "id":"item-2",
                            "icon":null,
                            "title":"Counter Support",
                            "description":"<p dir=\"ltr\">Add numbered counters to help users follow the sequence of information.</p>",
                            "titleEnabled":true,
                            "descriptionEnabled":true
                        }
                    ]
                },
                {
                    "id":"col-2",
                    "header":"Customization",
                    "content":[
                        {
                            "id":"item-3",
                            "icon":null,
                            "title":"Column Headers",
                            "description":"<p dir=\"ltr\">Enable or disable headers for each column to match your content structure.</p>",
                            "titleEnabled":true,
                            "descriptionEnabled":true
                        },
                        {
                            "id":"item-4",
                            "icon":null,
                            "title":"Flexible Columns",
                            "description":"<p dir=\"ltr\">Choose between 1, 2, or 3 columns to fit your data presentation needs.</p>",
                            "titleEnabled":true,
                            "descriptionEnabled":true
                        }
                    ]
                }
                ]
            }
        },
        {
            "type":"body_slide",
            "heading":"Standard Content Slides",
            "description":"Mix infographics with traditional image-based slides for comprehensive storytelling with PostNitro.",
            "image":"https://skfhtbmyanoeqbvrtxqa.supabase.co/storage/v1/object/public/media/static/postnitro-on-the-moon.png"
        },
        {
            "type":"body_slide",
            "heading":"Cyclical Infographics",
            "description":"Perfect for step-by-step processes or sequential information using PostNitro's cycle display.",
            "layoutType":"infographic",
            "layoutConfig":{
                "columnCount":1,
                "columnDisplay":"cycle",
                "displayCounterAs":"counter",
                "hasHeader":true,
                "columnData":[
                {
                    "id":"col-1",
                    "header":"Implementation Steps",
                    "content":[
                        {
                            "id":"item-1",
                            "icon":null,
                            "title":"Set Layout Type",
                            "description":"<p dir=\"ltr\">Configure layoutType as 'infographic' to enable structured data display.</p>",
                            "titleEnabled":true,
                            "descriptionEnabled":true
                        },
                        {
                            "id":"item-2",
                            "icon":null,
                            "title":"Choose Display Mode",
                            "description":"<p dir=\"ltr\">Select 'cycle' for sequential presentation or 'grid' for comparative layout.</p>",
                            "titleEnabled":true,
                            "descriptionEnabled":true
                        },
                        {
                            "id":"item-3",
                            "icon":null,
                            "title":"Add Column Data",
                            "description":"<p dir=\"ltr\">Structure your content with titles and descriptions for each data point.</p>",
                            "titleEnabled":true,
                            "descriptionEnabled":true
                        },
                        {
                            "id":"item-4",
                            "icon":null,
                            "title":"Configure Options",
                            "description":"<p dir=\"ltr\">Set column count, headers, and counters to match your presentation needs.</p>",
                            "titleEnabled":true,
                            "descriptionEnabled":true
                        }
                    ]
                }
                ]
            }
        },
        {
            "type":"ending_slide",
            "sub_heading":"Start Creating Today",
            "heading":"Try PostNitro Infographics",
            "description":"Transform your data into engaging visual carousels with PostNitro's Import API.",
            "cta_button":"Get Your API Key"
        }
    ]
}'

IMAGE with Infographics

An IMAGE slide uses the same layoutType/layoutConfig fields — just as a single object rather than an array.


curl --location 'https://embed-api.postnitro.ai/post/initiate/import' \
--header 'Content-Type: application/json' \
--header 'embed-api-key: pn-your-api-key' \
--data '{
    "postType": "IMAGE",
    "templateId": "xtrnxgfgk9a08tmsz2601k1c",
    "brandId": "cmdhb8oe10006v0pmh6a4no6t",
    "responseType": "PNG",
    "slides": {
        "heading": "Our 2026 Results",
        "sub_heading": "By the numbers",
        "layoutType": "infographic",
        "layoutConfig": {
            "hasHeader": true,
            "columnCount": 3,
            "columnDisplay": "grid",
            "displayCounterAs": "counter",
            "columnData": [
                {
                    "id": "col-1",
                    "header": "Heading",
                    "content": [
                        {
                            "id": "item-1",
                            "icon": null,
                            "title": "Title",
                            "description": "<p dir=\"ltr\">Description</p>",
                            "titleEnabled": true,
                            "descriptionEnabled": true
                        }
                    ]
                }
            ]
        }
    }
}'

Carousel Output (Infographics)

Example Carousel Output

Response


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

Image Output

Response


{
    "success": true,
    "message": "IMAGE generation initiated",
    "data": {
        "embedPostId": "post456",
        "status": "PENDING"
    }
}

Generation is asynchronous. This endpoint returns immediately with an embedPostId while the carousel is rendered in the background. Poll Check Post Status with the embedPostId until the status is COMPLETED, then call Get Post Output to retrieve the final files.