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. Optionally enable prompt enhancement to let AI optimize your prompt for better results.

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	Image aspect ratio (default: `square`, see sizes below)
`quantity`	number	No	Number of images to generate (1-4, default: 1)
`model`	string	No	Image model to use (default: `nano-banana-2`, see models below)
`enhance_prompt`	boolean	No	Let AI optimize your prompt for better results (default: `false`)
`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's optional — if omitted, the prompt is derived from the generation's captions.

Models

Choose a model based on your use case. Each model has different strengths and supported sizes.

Model ID	Name	Supported Sizes	Best For
`flux2-flex`	FLUX.2 Flex	square, feed, portrait, landscape	Multi-reference, fine control
`ideogram-3`	Ideogram 3.0	square, feed, portrait, landscape	Best text rendering and logos
`gpt-image-2`	GPT Image 2	square, portrait, landscape	Reasoning, photorealistic, sharp
`nano-banana-2`	Nano Banana 2	square, feed, portrait, landscape	Fast generation, great text

Not all sizes are available for every model. For example, gpt-image-2 does not support feed. Requesting an unsupported size returns a 400 error.

Image Sizes

Size names (square, feed, portrait, landscape) are the same across models, but pixel dimensions are per model (matched to each provider’s supported presets).

flux2-flex (default pixel map for the labels below):

Size	Aspect Ratio	Dimensions	Best For
`square`	1:1	1536×1536	Instagram feed, profile images
`feed`	4:5	1280×1600	Instagram/Facebook feed posts
`portrait`	9:16	1088×1936	Stories, Reels, TikTok
`landscape`	16:9	1536×864	YouTube thumbnails, X posts

Other models (same size names, different pixels):

Size	`ideogram-3`	`nano-banana-2`	`gpt-image-2`
`square`	1024×1024	1024×1024	1024×1024
`feed`	896×1152	928×1152	— (not supported)
`portrait`	768×1344	768×1376	1024×1536 (2:3)
`landscape`	1344×768	1376×768	1536×1024 (3:2)

Requesting a size a model does not support (for example feed with gpt-image-2) returns a 400 error. Pixel values above match what PowerPost sends to the image provider.

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	Image aspect ratio (default: `square`, see sizes below)
`quantity`	number	No	Number of images to generate (1-4, default: 1)
`model`	string	No	Image model to use (default: `nano-banana-2`, see models below)
`enhance_prompt`	boolean	No	Let AI optimize your prompt for better results (default: `false`)
`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's optional — if omitted, the prompt is derived from the generation's captions.

Models

Choose a model based on your use case. Each model has different strengths and supported sizes.

Model ID	Name	Supported Sizes	Best For
`flux2-flex`	FLUX.2 Flex	square, feed, portrait, landscape	Multi-reference, fine control
`ideogram-3`	Ideogram 3.0	square, feed, portrait, landscape	Best text rendering and logos
`gpt-image-2`	GPT Image 2	square, portrait, landscape	Reasoning, photorealistic, sharp
`nano-banana-2`	Nano Banana 2	square, feed, portrait, landscape	Fast generation, great text

Not all sizes are available for every model. For example, gpt-image-2 does not support feed. Requesting an unsupported size returns a 400 error.

Image Sizes

Size names (square, feed, portrait, landscape) are the same across models, but pixel dimensions are per model (matched to each provider’s supported presets).

flux2-flex (default pixel map for the labels below):

Size	Aspect Ratio	Dimensions	Best For
`square`	1:1	1536×1536	Instagram feed, profile images
`feed`	4:5	1280×1600	Instagram/Facebook feed posts
`portrait`	9:16	1088×1936	Stories, Reels, TikTok
`landscape`	16:9	1536×864	YouTube thumbnails, X posts

Other models (same size names, different pixels):

Size	`ideogram-3`	`nano-banana-2`	`gpt-image-2`
`square`	1024×1024	1024×1024	1024×1024
`feed`	896×1152	928×1152	— (not supported)
`portrait`	768×1344	768×1376	1024×1536 (2:3)
`landscape`	1344×768	1376×768	1536×1024 (3:2)

Requesting a size a model does not support (for example feed with gpt-image-2) returns a 400 error. Pixel values above match what PowerPost sends to the image provider.

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