Initiate AI Generation

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

Generates a carousel post using AI with predefined content generation presets.

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

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).

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 Request

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"
    }
}'

Example Request (with AI image generation)

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"
    }
}'

Response

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

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