<!-- Markdown twin of https://pixelvault.dev/docs/guides/generate-images/ -->

# Generate & edit images

**Goal:** get a hosted image from a prompt (a hero, a placeholder, an OG card) or change an existing one with an instruction, in a single API call with no separate storage step.

## Generate from a prompt

[`POST /v1/images/generate`](/docs/api/images/#generate_image) creates an image from a text prompt and hosts it. A Cloudflare Workers AI model draws it, and you get back the same payload as an upload (CDN URL with no fixed expiry, dimensions, `optimized_url`) plus a `generation` block. Free-plan retention still applies. Requires a **secret** key (publishable keys are refused) and a **verified email**.

Generate

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/images/generate \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A minimalist hero image of a mountain at sunrise, flat illustration"}'
```

Response (`201`):

```
{
  "data": {
    "id": "img_abc123",
    "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg",
    "optimized_url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg?fmt=auto&q=85",
    "mime_type": "image/jpeg",
    "width": 1024,
    "height": 1024,
    "generation": {
      "model": "flux-1-schnell",
      "credits_charged": 1,
      "credits_remaining": 9
    }
  }
}
```

Body fields: `prompt` (1–2,000 characters, required), `model` (default `flux-1-schnell`), `folder`, `visibility` (`public` default, or `private`), `expires_in`. Full schema in the [reference](/docs/api/images/#generate_image).

Model

Credits per image

Plans

`flux-1-schnell` (FLUX.1 schnell)

1

All

`sdxl-lightning`, `sdxl-base` (Stable Diffusion XL, beta)

1

Starter, Pro

`lucid-origin`, `phoenix-1.0` (Leonardo)

20

Starter, Pro

**Credits:** each plan includes a monthly grant — 10 on Free, 300 on Starter, 1,500 on Pro — that resets on the 1st (UTC). Check what's left with [`GET /v1/usage`](/docs/limits/#usage) (`generation.credits_remaining`). Credits are reserved before the model runs and **refunded if generation or storage fails**, so a failed call costs nothing. A generated image also counts toward your upload and storage quotas, and a request that would be refused for plan, quota or credit reasons never runs the model. More models are planned; tell us which on the [pricing page](/pricing/).

**Errors:** `402 generation_credits_exhausted` (out of credits until the 1st, or upgrade), `402 model_requires_paid_plan`, `403 generation_forbidden` (publishable key), `403 email_verification_required`, `422 prompt_rejected` (prompts that clearly ask for adult content are refused; see the [Terms](/terms/)), `429` (60 generations per hour per account, or the day's overall capacity; honour `Retry-After`), `502 generation_failed`, `503 generation_unavailable` and `504 generation_timeout` (all three refund your credits and are safe to retry). Do not retry a 402. See [Errors](/docs/errors/).

## Edit an existing image

[`POST /v1/images/:id/edit`](/docs/api/images/#edit_image) edits an existing image with a natural-language instruction and hosts the result as a **new image**; the source is never overwritten. For a local file, [upload it first](/docs/guides/upload-images/) and use the returned image id. Cloudflare FLUX.2 processes the source and prompt with zero data retention, and PixelVault does not store the prompt. Use a secret key here, or choose **Edit** beside an image in the signed-in dashboard; both paths use the same models and edit-credit allowance. A verified email is required.

```
curl -X POST https://api.pixelvault.dev/v1/images/img_abc123/edit \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Remove the people in the background","model":"fast"}'

→ { "data": {
     "id": "img_edited123",
     "url": "https://img.pixelvault.dev/proj_xyz789/img_edited123.jpg",
     "edit": { "source_image_id": "img_abc123", "model": "fast",
               "credits_charged": 1, "credits_remaining": 4 }
   } }
```

Model

Edit credits

Plans

`fast` (FLUX.2 Klein 4B, default)

1

All

`quality` (FLUX.2 Klein 9B)

5

Starter, Pro

**Credits:** monthly grants are 5 on Free, 100 on Starter and 500 on Pro. They reset on the 1st (UTC), are independent from generation credits, and are refunded if preparation, inference or storage fails. Check `editing.credits_remaining` in [`GET /v1/usage`](/docs/limits/#usage). JPEG, PNG, WebP, AVIF and GIF sources up to 20 MB are supported. The edited image counts toward upload and storage quotas. Edits are limited to 30 per hour per account.

Optional `folder`, `visibility`, `expires_in` and `sign_expires_in` apply to the new image. Visibility defaults to the source image's visibility. Errors: `402 edit_credits_exhausted` or `edit_model_requires_paid_plan`, `403 editing_forbidden` or `email_verification_required`, `404 image_not_found`, `422 source_not_editable` or `prompt_rejected`, `429` (honour `Retry-After`), and transient `502`/`503`/`504` failures (credits refunded).

## Next steps

-   [Transforms](/docs/transforms/): crop a generated image to `size=social` for an OG card.
-   [Generate from Claude](/docs/claude/) through the connector.
-   [Generate images with one API call](/blog/generate-images-with-one-api-call/).
