Initiate AI Generation

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

Generates a carousel, image or video post with AI, from a topic, an article or an X post, using one of your AI presets. For a video, see Video Posts. To send your own slides instead, use Import.

Headers

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

Request Body

AI Generation Object

How type and context work together:

• "text" — context is a plain-text topic or prompt describing what to create (e.g. "Create a carousel about digital marketing tips")
• "article" — context is the URL of an article to turn into a carousel
• "x" — context is the URL of an X (Twitter) post to turn into a carousel

Video Posts

Set postType: "VIDEO" to produce a video. The AI writes slides exactly as it does for a carousel, and each slide becomes a scene in the rendered video. See the VIDEO example.

Everything else about video posts:

• Video Motion: how a video moves without asking, the built-in styles, saved styles and sequences, and its length
• Voiceover: narration the AI writes and records, in the voice and tone you pick
• Per-Slide Motion: each slide’s own animations
• Motion Styles and Motion Sequences: list and save the styles and sequences videoSettings takes by id
• Audio: the backgroundMusicId for its music
• Read a Post and Edit a Post: a video’s settings read back, and its slides, template, brand, motion, music or voiceover changed later

Response types. A VIDEO post accepts only "MP4" — renders the video — or "DESIGN", which saves the design without rendering so you can finish it in the video maker via editorUrl. "PDF" and "PNG" are rejected for VIDEO, and "MP4" is rejected for every other post type.

videoSettings

All of it is optional. A video with no videoSettings is animated as its template is, or in the Clean style, and runs as long as its motion takes, up to 2:00. See Video Motion.

Three more fields are accepted: motion, each slide’s own animations, for per-slide motion; videoDuration, which is ignored, since a video runs as long as its motion takes (Length); and audioId, the older name of backgroundMusicId, so requests that send it keep working. Any other field returns a 422, and so does videoSettings on a CAROUSEL or IMAGE post.

Background music

backgroundMusicId is a media id, not a URL. Get one from the Audio API: upload happens in the PostNitro app, and GET /audio lists what the workspace has. It’s verified when you make the request: the media must exist, belong to your API key’s workspace, and be an audio file. Otherwise the request is rejected with a 422. audioId, its older name, is still accepted; send one or the other, not both.

The music is kept on the design with its volume, so the editor and the MP4 play it alike. A new track starts at its beginning, at 100 unless backgroundMusicVolume says otherwise, and fades out over the last second. It’s lowered to 30% while a voiceover plays. backgroundMusicVolume needs backgroundMusicId. The 422s are listed under Background music.

Voiceover

voiceover has the AI write a line for every slide it made and record it, charged in AI tokens, not API credits. See Voiceover.

The scheduling API’s postSettings takes the same backgroundMusicId, so a track carries straight over from generating a video to scheduling it as a reel. A reel plays its design’s motion, and runs as long as it does.

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 CAROUSEL, IMAGE, and VIDEO posts and with every responseType (PDF, PNG, MP4, DESIGN).

These are the only accepted fields — any other key inside generateImages returns a 422. Everything else the image service needs (editorType, image model, and the AI copy config) is resolved server-side: editorType from postType, the platform image model, and socialPlatform/tone/audience/language from your AI preset.

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

imageStrategy

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.

On generate, context plus socialPlatform/tone/audience/language are taken from the request/preset, so generateImages can be as small as { "imagePlacement": "auto" } — or {} to accept all defaults.

Example Requests

CAROUSEL

curl --location 'https://embed-api.postnitro.ai/post/initiate/generate' \
--header 'Content-Type: application/json' \
--header 'embed-api-key: pn-your-api-key' \
--data '{
    "postType": "CAROUSEL",
    "requestorId": "user123",
    "templateId": "xtrnxgfgk9a08tmsz2601k1c",
    "brandId": "cmdhb8oe10006v0pmh6a4no6t",
    "presetId": "preset123",
    "responseType": "PNG",
    "aiGeneration": {
        "type": "text",
        "context": "Create a carousel about digital marketing tips",
        "instructions": "Focus on actionable tips for small businesses"
    }
}'

CAROUSEL with AI images

curl --location 'https://embed-api.postnitro.ai/post/initiate/generate' \
--header 'Content-Type: application/json' \
--header 'embed-api-key: pn-your-api-key' \
--data '{
    "postType": "CAROUSEL",
    "requestorId": "user123",
    "templateId": "xtrnxgfgk9a08tmsz2601k1c",
    "brandId": "cmdhb8oe10006v0pmh6a4no6t",
    "presetId": "preset123",
    "responseType": "DESIGN",
    "aiGeneration": {
        "type": "text",
        "context": "How our scheduling feature saves marketers time"
    },
    "generateImages": {
        "imagePlacement": "auto",
        "imageStrategy": "all"
    }
}'

VIDEO

The smallest video request: animated as its template is, or in the Clean style.

curl --location 'https://embed-api.postnitro.ai/post/initiate/generate' \
--header 'Content-Type: application/json' \
--header 'embed-api-key: pn-your-api-key' \
--data '{
    "postType": "VIDEO",
    "templateId": "xtrnxgfgk9a08tmsz2601k1c",
    "brandId": "cmdhb8oe10006v0pmh6a4no6t",
    "presetId": "preset123",
    "responseType": "MP4",
    "aiGeneration": {
        "type": "text",
        "context": "Three habits that make remote teams faster"
    }
}'

With a style, music at a quarter of its volume, and a voiceover:

"videoSettings": {
    "motionStyle": "bold",
    "backgroundMusicId": "cmqi7jyir0003v0m91hxnyyaq",
    "backgroundMusicVolume": 25,
    "voiceover": { "voice": "nova", "tone": "Hype and punchy" }
}

Response

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

Generation is asynchronous. This endpoint returns immediately with an embedPostId while the post is generated 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.

Once it’s made, Read a Post gives its content back and Edit a Post changes it in place, by the same embedPostId.