---
title: "Generate images for a post"
method: POST
path: "/media/generate-image"
tags: ["Media library"]
---

# Generate images for a post

`POST /media/generate-image`

## Request

- Base URL: `https://www.sociahive.com/api/v1`
- URL: `https://www.sociahive.com/api/v1/media/generate-image`
- Auth: one of:
  - API key in header `X-API-Key`
  - OAuth 2 (authorization code, authorization URL `/api/oauth/authorize`, token URL `/api/oauth/token`, scopes: `uploads:write`)

Makes up to 4 AI images from a description or a caption. Each image is stored and added to your media library. Counts against your plan's monthly AI images (429 `allowance_exhausted` with `resetAt` when none are left). Behind the SCHEDULER_COMPOSER_IMAGE_GEN feature flag (403 `feature_disabled` while off).

## Request body

- GenerateImageRequest
  - `prompt` string: What the image shows. Required unless `fromCaption` is set.
  - `caption` string: The post caption, used with `fromCaption`.
  - `fromCaption` boolean: Draw an image for the caption (no text in the image).
  - `aspect` 'square' | 'portrait' | 'landscape', required: square 1024×1024, portrait 1024×1536, landscape 1536×1024.
  - `count` integer: Options to make (default 1). Each uses one image of the allowance.
  - `requestId` string: Retry with the same id to get the first result instead of new images.

## Response `200`

The generated images

- GenerateImageResponse
  - `images` GeneratedImage[], required
    - `asset_id` string, required: The media library entry (empty when it could not be recorded).
    - `url` string, uri, required: Public URL. Use it as post media (type `image`).
    - `width` integer, required
    - `height` integer, required
    - `mime_type` string, required
  - `failed` integer, required: Images that could not be made; they were not counted.
  - `allowance` AiImageAllowance, required
    - `used` integer, required
    - `limit` integer, nullable, required: Images per month on your plan; null is unlimited.
    - `remaining` integer, nullable, required: Null is unlimited.
    - `resetAt` string, date-time, required: When the count starts again.

## Other responses

- `400`: Invalid body, or nothing to draw (`prompt_required`)
- `401`: Authentication required — provide X-API-Key or Bearer token
- `403`: Insufficient scope for this operation
- `409`: A request with this `requestId` is still running (`in_progress`)
- `422`: The description was blocked by content rules (`prompt_rejected`)
- `429`: No AI images left this month (`allowance_exhausted`), or generation is busy (`busy`)
- `500`: Internal server error
- `502`: No image could be made (`generation_failed`); nothing was counted

---

[API](https://skmtc.dev/sociahive/apis/sociahive-api.md) · [All operations](https://skmtc.dev/sociahive/apis/sociahive-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sociahive/apis/sociahive-api/revisions/791b8548d288?raw)