Generate Content

POST /api/v1/content/generate

Generate platform-optimized social media content from text, images, or video input.

Input type is determined by the fields you send: prompt only (text), media_ids for images or video (+ optional prompt). You must provide either prompt or media_ids (or both). Conceptual overview: Input types.

Required scopes: content:generate · Header: X-Workspace-Id

Text Input

Generate content from a text prompt.

Request Body

Field	Type	Required	Description
`prompt`	string	Yes*	What you want to post about (max 2,000 tokens)
`post_types`	string[]	Yes	Target post types (at least one)
`research_mode`	string	Yes	`regular` or `deep`
`writing_style_id`	string	No	Custom writing style ID (see dashboard)
`cta_text`	string	No	Custom call-to-action (max 100 characters)
`source_urls`	string[]	No	URLs to scrape for research context (max 10)

* prompt is required unless media_ids is provided. Sending neither returns a 400.

Example

curl -X POST https://powerpost.ai/api/v1/content/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "We just shipped dark mode across all our apps",
    "post_types": ["instagram-reel", "tiktok-video", "x-post"],
    "research_mode": "regular"
  }'

Image Input

Generate content from uploaded images. PowerPost analyzes the images and creates captions. Optionally provide a prompt for additional context.

Supported formats: JPEG, PNG, WebP

Request Body

Field	Type	Required	Description
`media_ids`	string[]	Yes	Array of uploaded image media IDs (up to 10)
`prompt`	string	No	Additional context to guide the generated content
`post_types`	string[]	Yes	Target post types (at least one)
`research_mode`	string	Yes	`regular` or `deep`
`writing_style_id`	string	No	Custom writing style ID (see dashboard)
`cta_text`	string	No	Custom call-to-action (max 100 characters)

Example

curl -X POST https://powerpost.ai/api/v1/content/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "media_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "prompt": "Behind the scenes at our product launch",
    "post_types": ["instagram-feed", "facebook-post"],
    "research_mode": "regular"
  }'

Upload images first using the Upload Media endpoint to get media_ids.

Video Input

Generate content from an uploaded video. PowerPost analyzes the video using AI video understanding, then generates captions based on the content.

Supported formats: MP4, MOV

Request Body

Field	Type	Required	Description
`media_ids`	string[]	Yes	Array with the uploaded video media ID
`prompt`	string	No	Additional context to focus the generated content
`post_types`	string[]	Yes	Target post types (at least one)
`research_mode`	string	Yes	`regular` or `deep`
`writing_style_id`	string	No	Custom writing style ID (see dashboard)
`cta_text`	string	No	Custom call-to-action (max 100 characters)

Example

curl -X POST https://powerpost.ai/api/v1/content/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "media_ids": ["f9g0h1i2-j3k4-5678-lmno-pq9876543210"],
    "prompt": "Focus on the key insights about productivity",
    "post_types": ["tiktok-video", "youtube-short"],
    "research_mode": "deep"
  }'

Upload videos first using the Upload Media endpoint to get media_ids.

Source URLs (research add-on)

source_urls is a research add-on that can be combined with any input mode (text, images, or video). PowerPost scrapes each URL and uses the content to generate more informed captions.

Request Body

Field	Type	Required	Description
`prompt`	string	Yes*	What you want to post about (max 2,000 tokens)
`post_types`	string[]	Yes	Target post types (at least one)
`research_mode`	string	Yes	`regular` or `deep`
`source_urls`	string[]	No	URLs to scrape for context (max 10)
`media_ids`	string[]	No	Image or video IDs to combine with URL research (max 10)
`writing_style_id`	string	No	Custom writing style ID
`cta_text`	string	No	Custom call-to-action (max 100 characters)

* prompt is required unless media_ids is also provided. If both are given, prompt is optional.

Example

curl -X POST https://powerpost.ai/api/v1/content/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Announce our new product launch",
    "post_types": ["instagram-reel", "linkedin-post"],
    "research_mode": "regular",
    "source_urls": ["https://example.com/product-page"]
  }'

URLs must be publicly accessible http(s) addresses; requests targeting non-public infrastructure are rejected with 400.

Common parameters

Headers

Header	Value
`x-api-key`	Your API key
`X-Workspace-Id`	Your workspace ID
`Content-Type`	`application/json`

`post_types`

Required. At least one value from the post types list. Platform is derived from each type. Multiple types on the same platform share one caption.

`research_mode`

Required: regular or deep. See Research modes.

`writing_style_id`

Optional. Create styles in Settings → Writing Styles. If omitted, uses your active style (if any).

{
  "prompt": "We just shipped dark mode",
  "post_types": ["instagram-reel"],
  "research_mode": "regular",
  "writing_style_id": "c3d4e5f6-a7b8-9012-cdef-345678901234"
}

Response

{
  "generation_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "credits_used": 10,
  "remaining_credits": 90,
  "status_url": "/api/v1/content/generations/550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Description
`generation_id`	string	Unique ID to track this generation
`status`	string	Initial status (always `processing`)
`credits_used`	number	Credits deducted for this generation
`remaining_credits`	number	Your credit balance after deduction
`status_url`	string	Relative URL to poll for results

Use the Get Generation endpoint to poll for results.

Errors

Code	Description
400	Invalid request body
401	Invalid API key
402	Insufficient credits
403	API key is missing the `content:generate` scope
429	Rate limit exceeded

MCP tools

These tools take the same JSON as the REST endpoints. You still need prompt and/or media_ids.

Tool	What it does
`powerpost_generate_content`	Starts a caption generation and returns `generation_id`
`powerpost_get_content_generation`	Poll until `completed` or `failed`, then read per-platform captions
`powerpost_list_content_generations`	List generations in the workspace
`powerpost_regenerate_content`	Rewrite one platform's caption

Generate captions guide — End-to-end flow
Get generation — Poll and regenerate
Generate images — Visuals for your content
Create posts — Draft from outputs

POST /api/v1/content/generate

Generate platform-optimized social media content from text, images, or video input.

Required scopes: content:generate · Header: X-Workspace-Id

Text Input

Generate content from a text prompt.

Request Body

Field	Type	Required	Description
`prompt`	string	Yes*	What you want to post about (max 2,000 tokens)
`post_types`	string[]	Yes	Target post types (at least one)
`research_mode`	string	Yes	`regular` or `deep`
`writing_style_id`	string	No	Custom writing style ID (see dashboard)
`cta_text`	string	No	Custom call-to-action (max 100 characters)
`source_urls`	string[]	No	URLs to scrape for research context (max 10)

* prompt is required unless media_ids is provided. Sending neither returns a 400.

Example

curl -X POST https://powerpost.ai/api/v1/content/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "We just shipped dark mode across all our apps",
    "post_types": ["instagram-reel", "tiktok-video", "x-post"],
    "research_mode": "regular"
  }'

Image Input

Generate content from uploaded images. PowerPost analyzes the images and creates captions. Optionally provide a prompt for additional context.

Supported formats: JPEG, PNG, WebP

Request Body

Field	Type	Required	Description
`media_ids`	string[]	Yes	Array of uploaded image media IDs (up to 10)
`prompt`	string	No	Additional context to guide the generated content
`post_types`	string[]	Yes	Target post types (at least one)
`research_mode`	string	Yes	`regular` or `deep`
`writing_style_id`	string	No	Custom writing style ID (see dashboard)
`cta_text`	string	No	Custom call-to-action (max 100 characters)

Example

curl -X POST https://powerpost.ai/api/v1/content/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "media_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "prompt": "Behind the scenes at our product launch",
    "post_types": ["instagram-feed", "facebook-post"],
    "research_mode": "regular"
  }'

Upload images first using the Upload Media endpoint to get media_ids.

Video Input

Generate content from an uploaded video. PowerPost analyzes the video using AI video understanding, then generates captions based on the content.

Supported formats: MP4, MOV

Request Body

Field	Type	Required	Description
`media_ids`	string[]	Yes	Array with the uploaded video media ID
`prompt`	string	No	Additional context to focus the generated content
`post_types`	string[]	Yes	Target post types (at least one)
`research_mode`	string	Yes	`regular` or `deep`
`writing_style_id`	string	No	Custom writing style ID (see dashboard)
`cta_text`	string	No	Custom call-to-action (max 100 characters)

Example

curl -X POST https://powerpost.ai/api/v1/content/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "media_ids": ["f9g0h1i2-j3k4-5678-lmno-pq9876543210"],
    "prompt": "Focus on the key insights about productivity",
    "post_types": ["tiktok-video", "youtube-short"],
    "research_mode": "deep"
  }'

Upload videos first using the Upload Media endpoint to get media_ids.

Source URLs (research add-on)

source_urls is a research add-on that can be combined with any input mode (text, images, or video). PowerPost scrapes each URL and uses the content to generate more informed captions.

Request Body

Field	Type	Required	Description
`prompt`	string	Yes*	What you want to post about (max 2,000 tokens)
`post_types`	string[]	Yes	Target post types (at least one)
`research_mode`	string	Yes	`regular` or `deep`
`source_urls`	string[]	No	URLs to scrape for context (max 10)
`media_ids`	string[]	No	Image or video IDs to combine with URL research (max 10)
`writing_style_id`	string	No	Custom writing style ID
`cta_text`	string	No	Custom call-to-action (max 100 characters)

* prompt is required unless media_ids is also provided. If both are given, prompt is optional.

Example

curl -X POST https://powerpost.ai/api/v1/content/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Announce our new product launch",
    "post_types": ["instagram-reel", "linkedin-post"],
    "research_mode": "regular",
    "source_urls": ["https://example.com/product-page"]
  }'

URLs must be publicly accessible http(s) addresses; requests targeting non-public infrastructure are rejected with 400.

Common parameters

Headers

Header	Value
`x-api-key`	Your API key
`X-Workspace-Id`	Your workspace ID
`Content-Type`	`application/json`

{
  "prompt": "We just shipped dark mode",
  "post_types": ["instagram-reel"],
  "research_mode": "regular",
  "writing_style_id": "c3d4e5f6-a7b8-9012-cdef-345678901234"
}

Response

{
  "generation_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "credits_used": 10,
  "remaining_credits": 90,
  "status_url": "/api/v1/content/generations/550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Description
`generation_id`	string	Unique ID to track this generation
`status`	string	Initial status (always `processing`)
`credits_used`	number	Credits deducted for this generation
`remaining_credits`	number	Your credit balance after deduction
`status_url`	string	Relative URL to poll for results

Use the Get Generation endpoint to poll for results.

Errors

Code	Description
400	Invalid request body
401	Invalid API key
402	Insufficient credits
403	API key is missing the `content:generate` scope
429	Rate limit exceeded

MCP tools

These tools take the same JSON as the REST endpoints. You still need prompt and/or media_ids.

Tool	What it does
`powerpost_generate_content`	Starts a caption generation and returns `generation_id`
`powerpost_get_content_generation`	Poll until `completed` or `failed`, then read per-platform captions
`powerpost_list_content_generations`	List generations in the workspace
`powerpost_regenerate_content`	Rewrite one platform's caption

Generate captions guide — End-to-end flow
Get generation — Poll and regenerate
Generate images — Visuals for your content
Create posts — Draft from outputs

Generate Content

On this page

Generate Content

On this page