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 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.
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.
| 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 (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.
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), 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.
Edit an existing image
POST /v1/images/:id/edit 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 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. 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: crop a generated image to
size=socialfor an OG card. - Generate from Claude through the connector.
- Generate images with one API call.