---
title: "Generate a post image"
method: POST
path: "/api/apps/{app_id}/virality/posts/{post_id}/generate-image"
---

# Generate a post image

`POST /api/apps/{app_id}/virality/posts/{post_id}/generate-image`

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Generates the image for a single post and saves it on the plan.

The post's own `image_prompt` wins over the `image_prompt` you send, so the request body only decides the prompt for a post that has none. To change an image that already exists, send `refinement_instruction`.

<Note>If the post already has an `image_url` and you send no `refinement_instruction`, the existing image is returned as-is. Nothing is generated and no credits are charged.</Note>

Generating an image costs 1 credit and fails with a 402 when the workspace is out of quota. Image generation is budgeted at up to 60 seconds per attempt, so use a client timeout above that.

This endpoint is limited to 12 requests per minute, separately from the other social content endpoints.

<Note>This endpoint accepts a personal API key. Workspace API keys are not authorized for it and are rejected with a 403.</Note>

<Warning>The response includes fields beyond the ones documented here. Don't rely on undocumented response fields, as they can change at any time. Send only the fields documented here. Other request fields are not supported and their behavior can change.</Warning>

## Path parameters

- `post_id` string, required — ID of the post, as returned in the content plan. Must be a UUID.
- `app_id` string, required — ID of the app.

## Request body

- GenerateImagePayload
  - `image_prompt` string, required — Prompt to generate the image from. Used only when the post carries no `image_prompt` of its own, which is the prompt the plan generated for it. Send the post's own `image_prompt` back if you want to be sure of what is used.
  - `refinement_instruction` string, nullable — What to change about the existing image. Sending this regenerates the image even when the post already has one. The first 300 characters are used.

## Response `200`

Successful Response

- PostImageResponse — The generated image for a post, and the plan it belongs to.
  - `image_url` string, nullable — URL of the post image.
  - `plan` ContentPlan
    - `id` string, nullable — ID of the content plan.
    - `app_id` string, nullable — ID of the app the plan belongs to.
    - `strategy` ContentStrategy
      - `app_summary` string, nullable — Short summary of what the app does.
      - `marketing_approach` string, nullable — The approach the content takes, extracted from the accepted strategy. Empty if the strategy text was empty when the plan was generated.
      - `platforms` PlatformContentPlan[] — One entry per platform you approved, in the order you sent them.
        - `platform` 'x' | 'instagram' | 'tiktok' | 'linkedin' | 'reddit' | 'facebook'
        - `mode` 'series' | 'selection'
        - `reasoning` string, nullable — Why the content for this platform takes the shape it does.
        - `posts` SocialPost[] — The generated posts for this platform.
          - `id` string, nullable — ID of the post. Pass it as `post_id` to [Refine a post](/api-reference/refine-a-post), [Update post content](/api-reference/update-post-content), and [Generate a post image](/api-reference/generate-a-post-image).
          - `platform` 'x' | 'instagram' | 'tiktok' | 'linkedin' | 'reddit' | 'facebook'
          - `angle` 'pain_point' | 'feature_demo' | 'social_proof' | 'trending_hook' | 'user_story' | 'before_after'
          - `angle_label` string, nullable — Human-readable label for the angle.
          - `post_number` integer, nullable — Position of this post within its platform's set, starting at 1.
          - `total_posts` integer, nullable — Number of posts generated for this platform.
          - `suggested_day` integer, nullable — Suggested day to publish on, counted from the start of the campaign.
          - `rationale` string, nullable — Why this post works for this platform and angle.
          - `content` string, nullable — The post text, ready to publish. Change it with [Update post content](/api-reference/update-post-content).
          - `image_url` string, nullable — URL of the post image, or `null` if no image was generated yet. Create one with [Generate a post image](/api-reference/generate-a-post-image).
          - `image_prompt` string, nullable — Prompt used to generate the post image, or `null` if the post has none.
          - `hashtags` string[], nullable — Suggested hashtags, without the leading `#`.
          - `post_title` string, nullable — Title for platforms that use one, such as Reddit and LinkedIn, or `null` elsewhere.
          - `suggested_subreddits` string[], nullable — Subreddits to consider for a Reddit post. Empty for other platforms.
          - `launch_comment` string, nullable — First comment to post under the main post, or `null` if none was generated.
          - `option_label` string, nullable — Label for this post when the platform's `mode` is `selection`, so you can tell the alternatives apart, or `null` in `series` mode.
          - `best_for_context` string, nullable — When to prefer this option over the others, or `null` if not applicable.
    - `created_at` string, nullable — Time the plan was created, as an ISO 8601 timestamp.
    - `updated_at` string, nullable — Time the plan last changed, as an ISO 8601 timestamp.

## Other responses

- `400` — The `post_id` is not a UUID.
- `401` — Missing or invalid credentials.
- `402` — The workspace is out of credits.
- `403` — You don't have editor access to this app, or you used a workspace API key.
- `404` — App not found, the app has no content plan, the post isn't in it, or the social content feature is not enabled for your account.
- `409` — A content plan is currently generating for this app.
- `422` — Validation Error
- `429` — Rate limit exceeded (12 requests per minute).
- `500` — Generating or saving the image failed. Retry the request.

## Changes

- **2026-08-25** `8dfd9c46c0b9` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/idealspot/apis/base44-app-management-api/changes/api/apps/:app_id/virality/posts/:post_id/generate-image/post.md)

---

[API](https://skmtc.dev/idealspot/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/idealspot/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/idealspot/base44-app-management-api/revisions/394136a6cdd4/schema)