Generate Images

POST /api/v1/images/generate

Generate AI images from a text prompt, from reference images you upload, or from an existing caption generation. Post mode always rewrites that caption into an image prompt before generation. enhance_prompt only polishes a prompt you already wrote.

Image generation requires at least one credit purchase on the account. Signup credits are not enough. See Purchase required.

Input Modes

The input mode is determined by the fields you provide. Each mode can be combined with additional parameters for more control.

Input Mode	How to Use	Description
Text	Send `prompt`	Generate from a text description
Reference	Send `prompt` + `style_images`	Generate inspired by reference images
Post	Send `generation_id` (+ optional `prompt`)	Generate visuals for existing captions

Request Body

Field	Type	Required	Description
`prompt`	string	Yes*	Text description of the image to generate (max 2000 chars)
`size`	string	No	`square`, `feed`, `portrait`, or `landscape`. Defaults to `square`.
`quantity`	number	No	Number of images to generate (1-4, default: 1)
`model`	string	No	Image model. Leave it out to use the current default.
`enhance_prompt`	boolean	No	Polish a prompt you wrote (default: `false`). Ignored for post mode, which always rewrites the caption.
`style_images`	string[]	No	Media IDs of reference images for style guidance (max 4)
`generation_id`	string	No	Caption generation ID for contextual image creation
`source_post_type`	string	No	Which platform's caption to use as source (post mode only)

* prompt is required for text and reference modes. For post mode it is optional extra direction. The caption is always rewritten into an image prompt, including the frame you picked.

Models and sizes

model is optional. Leave it out to use the current default.

size is square, feed, portrait, or landscape. Not every model supports every size. You send the name, not pixel dimensions. An unsupported combination returns 400.

Image generation uses credits. The amount depends on the model and how many images you ask for. The response includes credits_used.

Examples

Text-to-Image

Describe what you want and get an image:

curl -X POST https://powerpost.ai/api/v1/images/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Minimalist workspace with laptop and coffee, warm morning light",
    "size": "square",
    "quantity": 2
  }'

Reference-Based (Image + Text)

Upload reference images first via Upload Media, then use them as style guidance. The prompt describes what new image to create, while the references guide the visual style:

curl -X POST https://powerpost.ai/api/v1/images/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Product photo of headphones on marble surface",
    "size": "feed",
    "style_images": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'

Reference images guide the style, composition, and visual feel — the model generates a new image inspired by the references, not a direct edit. You can pass up to 4 reference images.

From Caption Generation

Generate images that match an existing caption generation. The AI reads your captions and creates a matching visual:

curl -X POST https://powerpost.ai/api/v1/images/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "generation_id": "550e8400-e29b-41d4-a716-446655440000",
    "size": "portrait",
    "quantity": 3
  }'

You can optionally add prompt for extra steering and source_post_type to tell the AI which platform's caption to prioritize:

curl -X POST https://powerpost.ai/api/v1/images/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "generation_id": "550e8400-e29b-41d4-a716-446655440000",
    "prompt": "Use dark background with neon accents",
    "source_post_type": "instagram-feed",
    "size": "feed"
  }'

prompt — Additional instructions layered on top of the caption context (e.g., art direction, color preferences). If omitted, the prompt is derived from the captions automatically.
source_post_type — Which platform's caption to use as source (e.g., instagram-feed). If omitted, all captions are considered.

When the source generation included media (uploaded images or video), those are automatically used as style references — no need to pass style_images separately.

Response

{
  "image_generation_id": "7a8b9c0d-e1f2-3456-abcd-ef7890123456",
  "status": "processing",
  "credits_used": 9,
  "remaining_credits": 36,
  "status_url": "/api/v1/images/generations/7a8b9c0d-e1f2-3456-abcd-ef7890123456"
}

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

Errors

Code	Description
400	Invalid request body, unsupported size, or referenced `generation_id`/`style_images` not found
401	Invalid API key
402	Insufficient credits (`INSUFFICIENT_CREDITS`)
402	Purchase required (`MEDIA_REQUIRES_PURCHASE`)
403	API key is missing the `images:generate` scope
429	Rate limit exceeded

Get Image Generation

GET /api/v1/images/generations/{id}

Retrieve the status and outputs of an image generation.

Path Parameters

Parameter	Type	Description
`id`	string	The image generation ID

Example Request

curl https://powerpost.ai/api/v1/images/generations/7a8b9c0d-e1f2-3456-abcd-ef7890123456 \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID"

Response (Processing)

{
  "image_generation_id": "7a8b9c0d-e1f2-3456-abcd-ef7890123456",
  "status": "processing",
  "prompt": "Minimalist workspace with laptop and coffee, warm morning light",
  "size": "square",
  "quantity": 2,
  "model": "nano-banana-2",
  "created_at": "2026-01-10T18:30:00Z"
}

Response (Completed)

{
  "image_generation_id": "7a8b9c0d-e1f2-3456-abcd-ef7890123456",
  "status": "completed",
  "prompt": "Minimalist workspace with laptop and coffee, warm morning light",
  "size": "square",
  "quantity": 2,
  "model": "nano-banana-2",
  "created_at": "2026-01-10T18:30:00Z",
  "images": [
    {
      "media_id": "img-001-abcd-efgh",
      "url": "https://powerpost.ai/storage/images/img-001-abcd-efgh.webp",
      "thumbnail_url": "https://powerpost.ai/storage/images/img-001-abcd-efgh-thumb.jpg",
      "width": 1024,
      "height": 1024
    },
    {
      "media_id": "img-002-ijkl-mnop",
      "url": "https://powerpost.ai/storage/images/img-002-ijkl-mnop.webp",
      "thumbnail_url": "https://powerpost.ai/storage/images/img-002-ijkl-mnop-thumb.jpg",
      "width": 1024,
      "height": 1024
    }
  ]
}

Response (Failed)

{
  "image_generation_id": "7a8b9c0d-e1f2-3456-abcd-ef7890123456",
  "status": "failed",
  "prompt": "Minimalist workspace with laptop and coffee, warm morning light",
  "size": "square",
  "quantity": 2,
  "model": "nano-banana-2",
  "created_at": "2026-01-10T18:30:00Z",
  "images": [
    {
      "media_id": "img-001-abcd-efgh",
      "url": "https://powerpost.ai/storage/images/img-001-abcd-efgh.webp",
      "thumbnail_url": "https://powerpost.ai/storage/images/img-001-abcd-efgh-thumb.jpg",
      "width": 1024,
      "height": 1024
    }
  ],
  "error": {
    "code": "PARTIAL_FAILURE",
    "message": "1 of 2 images failed to generate. Credits refunded for failed images."
  }
}

If some images fail while others succeed, you get a partial result with a partial refund. Only fully failed generations return no images at all.

Response Fields

Field	Type	Description
`image_generation_id`	string	Unique image generation ID
`status`	string	`processing`, `completed`, or `failed`
`prompt`	string	The input prompt (or derived from generation)
`size`	string	Requested image size
`quantity`	number	Requested number of images
`model`	string	Image model used for this generation
`created_at`	string	ISO 8601 timestamp
`images`	array	Generated images (only when completed/partial)
`error`	object	Error details (only when failed)

Image Object

Field	Type	Description
`media_id`	string	Media ID for use in posts
`url`	string	Full-resolution image URL
`thumbnail_url`	string	Thumbnail URL (384px)
`width`	number	Image width in pixels
`height`	number	Image height in pixels

Status Values

Status	Description
`processing`	Images are being generated
`completed`	All images ready
`failed`	Generation failed (may have partial)

Generated image URLs are signed and valid for 7 days. Use the media_id to attach images to posts — URLs are for preview only.

Errors

Code	Description
401	Invalid API key
403	API key is missing the `images:read` scope
404	Image generation not found
429	Rate limit exceeded

Generate Images

POST /api/v1/images/generate

Image generation requires at least one credit purchase on the account. Signup credits are not enough. See Purchase required.

Input Modes

The input mode is determined by the fields you provide. Each mode can be combined with additional parameters for more control.

Input Mode	How to Use	Description
Text	Send `prompt`	Generate from a text description
Reference	Send `prompt` + `style_images`	Generate inspired by reference images
Post	Send `generation_id` (+ optional `prompt`)	Generate visuals for existing captions

Request Body

Field	Type	Required	Description
`prompt`	string	Yes*	Text description of the image to generate (max 2000 chars)
`size`	string	No	`square`, `feed`, `portrait`, or `landscape`. Defaults to `square`.
`quantity`	number	No	Number of images to generate (1-4, default: 1)
`model`	string	No	Image model. Leave it out to use the current default.
`enhance_prompt`	boolean	No	Polish a prompt you wrote (default: `false`). Ignored for post mode, which always rewrites the caption.
`style_images`	string[]	No	Media IDs of reference images for style guidance (max 4)
`generation_id`	string	No	Caption generation ID for contextual image creation
`source_post_type`	string	No	Which platform's caption to use as source (post mode only)

* prompt is required for text and reference modes. For post mode it is optional extra direction. The caption is always rewritten into an image prompt, including the frame you picked.

Models and sizes

model is optional. Leave it out to use the current default.

size is square, feed, portrait, or landscape. Not every model supports every size. You send the name, not pixel dimensions. An unsupported combination returns 400.

Image generation uses credits. The amount depends on the model and how many images you ask for. The response includes credits_used.

Examples

Text-to-Image

Describe what you want and get an image:

curl -X POST https://powerpost.ai/api/v1/images/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Minimalist workspace with laptop and coffee, warm morning light",
    "size": "square",
    "quantity": 2
  }'

Reference-Based (Image + Text)

Upload reference images first via Upload Media, then use them as style guidance. The prompt describes what new image to create, while the references guide the visual style:

curl -X POST https://powerpost.ai/api/v1/images/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Product photo of headphones on marble surface",
    "size": "feed",
    "style_images": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'

Reference images guide the style, composition, and visual feel — the model generates a new image inspired by the references, not a direct edit. You can pass up to 4 reference images.

From Caption Generation

Generate images that match an existing caption generation. The AI reads your captions and creates a matching visual:

curl -X POST https://powerpost.ai/api/v1/images/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "generation_id": "550e8400-e29b-41d4-a716-446655440000",
    "size": "portrait",
    "quantity": 3
  }'

You can optionally add prompt for extra steering and source_post_type to tell the AI which platform's caption to prioritize:

curl -X POST https://powerpost.ai/api/v1/images/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "generation_id": "550e8400-e29b-41d4-a716-446655440000",
    "prompt": "Use dark background with neon accents",
    "source_post_type": "instagram-feed",
    "size": "feed"
  }'

prompt — Additional instructions layered on top of the caption context (e.g., art direction, color preferences). If omitted, the prompt is derived from the captions automatically.
source_post_type — Which platform's caption to use as source (e.g., instagram-feed). If omitted, all captions are considered.

When the source generation included media (uploaded images or video), those are automatically used as style references — no need to pass style_images separately.

Response

{
  "image_generation_id": "7a8b9c0d-e1f2-3456-abcd-ef7890123456",
  "status": "processing",
  "credits_used": 9,
  "remaining_credits": 36,
  "status_url": "/api/v1/images/generations/7a8b9c0d-e1f2-3456-abcd-ef7890123456"
}

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

Errors

Code	Description
400	Invalid request body, unsupported size, or referenced `generation_id`/`style_images` not found
401	Invalid API key
402	Insufficient credits (`INSUFFICIENT_CREDITS`)
402	Purchase required (`MEDIA_REQUIRES_PURCHASE`)
403	API key is missing the `images:generate` scope
429	Rate limit exceeded

Get Image Generation

GET /api/v1/images/generations/{id}

Retrieve the status and outputs of an image generation.

Path Parameters

Parameter	Type	Description
`id`	string	The image generation ID

Example Request

curl https://powerpost.ai/api/v1/images/generations/7a8b9c0d-e1f2-3456-abcd-ef7890123456 \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID"

Response (Processing)

{
  "image_generation_id": "7a8b9c0d-e1f2-3456-abcd-ef7890123456",
  "status": "processing",
  "prompt": "Minimalist workspace with laptop and coffee, warm morning light",
  "size": "square",
  "quantity": 2,
  "model": "nano-banana-2",
  "created_at": "2026-01-10T18:30:00Z"
}

Response (Completed)

{
  "image_generation_id": "7a8b9c0d-e1f2-3456-abcd-ef7890123456",
  "status": "completed",
  "prompt": "Minimalist workspace with laptop and coffee, warm morning light",
  "size": "square",
  "quantity": 2,
  "model": "nano-banana-2",
  "created_at": "2026-01-10T18:30:00Z",
  "images": [
    {
      "media_id": "img-001-abcd-efgh",
      "url": "https://powerpost.ai/storage/images/img-001-abcd-efgh.webp",
      "thumbnail_url": "https://powerpost.ai/storage/images/img-001-abcd-efgh-thumb.jpg",
      "width": 1024,
      "height": 1024
    },
    {
      "media_id": "img-002-ijkl-mnop",
      "url": "https://powerpost.ai/storage/images/img-002-ijkl-mnop.webp",
      "thumbnail_url": "https://powerpost.ai/storage/images/img-002-ijkl-mnop-thumb.jpg",
      "width": 1024,
      "height": 1024
    }
  ]
}

Response (Failed)

{
  "image_generation_id": "7a8b9c0d-e1f2-3456-abcd-ef7890123456",
  "status": "failed",
  "prompt": "Minimalist workspace with laptop and coffee, warm morning light",
  "size": "square",
  "quantity": 2,
  "model": "nano-banana-2",
  "created_at": "2026-01-10T18:30:00Z",
  "images": [
    {
      "media_id": "img-001-abcd-efgh",
      "url": "https://powerpost.ai/storage/images/img-001-abcd-efgh.webp",
      "thumbnail_url": "https://powerpost.ai/storage/images/img-001-abcd-efgh-thumb.jpg",
      "width": 1024,
      "height": 1024
    }
  ],
  "error": {
    "code": "PARTIAL_FAILURE",
    "message": "1 of 2 images failed to generate. Credits refunded for failed images."
  }
}

If some images fail while others succeed, you get a partial result with a partial refund. Only fully failed generations return no images at all.

Response Fields

Field	Type	Description
`image_generation_id`	string	Unique image generation ID
`status`	string	`processing`, `completed`, or `failed`
`prompt`	string	The input prompt (or derived from generation)
`size`	string	Requested image size
`quantity`	number	Requested number of images
`model`	string	Image model used for this generation
`created_at`	string	ISO 8601 timestamp
`images`	array	Generated images (only when completed/partial)
`error`	object	Error details (only when failed)

Image Object

Field	Type	Description
`media_id`	string	Media ID for use in posts
`url`	string	Full-resolution image URL
`thumbnail_url`	string	Thumbnail URL (384px)
`width`	number	Image width in pixels
`height`	number	Image height in pixels

Status Values

Status	Description
`processing`	Images are being generated
`completed`	All images ready
`failed`	Generation failed (may have partial)

Generated image URLs are signed and valid for 7 days. Use the media_id to attach images to posts — URLs are for preview only.

Errors

Code	Description
401	Invalid API key
403	API key is missing the `images:read` scope
404	Image generation not found
429	Rate limit exceeded

Generate Images

On this page

Generate Images

On this page