---
title: "generate_image"
method: POST
path: "/generate_image"
tags: ["image"]
---

# generate_image

`POST /generate_image`

## Request

- Base URL: `https://app.podmule.com/api/v1`
- URL: `https://app.podmule.com/api/v1/generate_image`
- Auth: HTTP bearer

Generate an AI image for a show (use this for any thumbnail / cover art / artwork / image request — NOT the writing/article path). Runs in the background and saves the image to the workspace media library, attached to the entity in context so it appears on that entity's media: pass attach_to_type + attach_to_id (show | episode | social | contact | group | interview) — e.g. an episode thumbnail attaches to that episode; defaults to the show. **Aspect ratio is controlled ONLY by the aspect_ratio parameter (1:1 | 16:9 | 9:16 | 4:5) — never by words in the prompt; the output is guaranteed to be exactly that ratio. Pick it from intent (YouTube thumbnail → 16:9, Short/Reel → 9:16) without asking.** Optionally pass reference_media_ids (med_<uuid> from list_entity_media / list_media_assets) to edit/composite against real workspace images (host/guest photos, a logo); with no references it is pure text-to-image and cannot retain a supplied image. Returns a job_id — the image appears when the job completes; then apply_media_asset can set it as a cover/social image. Required: show_id, prompt. Billed in credits.

## Headers

- `Idempotency-Key` string
- `X-PodMule-Dry-Run` 'true' | 'false'

## Request body

- unknown

## Response `200`

Capability output wrapped in `{ data }`.

- object
  - `data` unknown, required

## Other responses

- `400`: Invalid input — Zod validation failed.
- `401`: Missing, malformed, or audience-mismatched bearer token.
- `403`: Token is valid but lacks the required scope.
- `404`: Capability not registered, or referenced resource not found.
- `409`: IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.
- `429`: Rate limit exceeded. Retry after the period in `Retry-After`.
- `500`: Internal error.

---

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