---
title: "Generate an image (logged-in): a prepaid credit, else a Lightning offer"
method: POST
path: "/v1/images/generate"
tags: ["Generation"]
---

# Generate an image (logged-in): a prepaid credit, else a Lightning offer

`POST /v1/images/generate`

## Request

- Base URL: `https://api.memestack.ai`
- URL: `https://api.memestack.ai/v1/images/generate`
- Auth: HTTP bearer

A `standard` generation consumes ONE prepaid generation credit when the account holds one (answered 201 with the job dispatched); otherwise — and always for `quality` and `edit` — answers a 402 Lightning offer for the mode's price ($0.08 standard / $0.20 quality / $0.15 edit, invoiced in sats at the current BTC/USD rate), to be paid and then redeemed at POST /v1/images/generate/redeem. `edit` takes up to 3 references: existing image ids (`ref_image_ids`) and/or ephemeral uploads (`ref_upload_ids` from /v1/images/generate/ref-upload). Idempotency-Key is REQUIRED — the credit arm is a mutation, and a same-key retry of a 402 hands back the SAME offer rather than minting a second invoice. Requires a fresh account. Rate limited 20/min/user. Returns 403 while IMAGE_GEN_ENABLED is off.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `mode` 'standard' | 'quality' | 'edit', required
  - `prompt` string, required
  - `aspect_ratio` '1:1' | '3:4' | '16:9', required
  - `ref_image_ids` string[]: edit only — existing images the caller may access.
  - `ref_upload_ids` string[]: edit only — ids returned by /v1/images/generate/ref-upload.

## Response `201`

A prepaid credit covered the generation; the job is dispatched. Poll GET /v1/images/{id}/generation-status.

- object
  - `imageId` string, uuid
  - `status` 'generating'
  - `cost_sats` 0
  - `paid_with` 'credit'
  - `generation_credits` integer: Credits remaining after this one.

## Other responses

- `400`: MISSING_IDEMPOTENCY_KEY, INVALID_MODE, INVALID_PROMPT, INVALID_ASPECT, or an invalid reference set.
- `401`: Authentication required.
- `402`: The Lightning offer for this mode's price — same shape as /v1/premium/purchase's 402 without `product`. Pay `invoice`, then redeem.
- `403`: Generation disabled (FEATURE_DISABLED), or a reference the caller may not use.
- `404`: A referenced image does not exist.
- `429`: Rate limit exceeded (20/min/user).
- `502`: The credit was consumed but the job could not be enqueued (ENQUEUE_FAILED); the credit is refunded (`refunded`). Retry with a NEW Idempotency-Key.
- `503`: GENERATION_UNAVAILABLE — the credit check itself failed, nothing was charged; or PAYMENT_UNAVAILABLE — payments paused / the offer could not be minted.

---

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