Most image-generation APIs hand you something awkward to keep: a URL that expires, or a blob of base64. To use the picture anywhere, in a README, an email, a CMS or a pull request, you still have to download it and upload it somewhere stable. An agent doing that has three tools to call and two places to fail.
We added POST /v1/images/generate to collapse that. You send a prompt, a Cloudflare Workers AI model draws the image, and PixelVault stores it and returns the URL, in the same response. It launched this week as a test, so the model list is deliberately short, and we say below what it does and doesn't do well.
One call: prompt in, hosted image out
You need a PixelVault API key (a secret key, and a verified email) and nothing else. There is no separate AI account or bucket to set up.
curl -s -X POST https://api.pixelvault.dev/v1/images/generate \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"Isometric flat illustration of a tidy desk with a laptop, a small potted plant and a coffee cup, soft pastel colors, no text"}' \
| jq -r '.data.url'
# → https://img.pixelvault.dev/proj_…/img_….jpg
The response is the same payload an upload returns, plus a generation block that tells you what it cost. This is a real one, from the first curl example above:
"data": {
"id": "img_rnvpd6170k5c",
"url": "https://img.pixelvault.dev/proj_mkoboesmx25d/img_rnvpd6170k5c.jpg",
"optimized_url": "…/img_rnvpd6170k5c.jpg?fmt=auto&q=85",
"mime_type": "image/jpeg",
"size": 160196,
"width": 1024,
"height": 1024,
"generation": {
"model": "flux-1-schnell",
"credits_charged": 1,
"credits_remaining": 7
}
}
}
Calls took three to four seconds end to end in our production runs. The image comes back as a 1024×1024 file. That one is 160 KB as a JPEG; the optimized_url serves the same picture as WebP at 21.8 KB, which is the one to put in a page or an email.
What it produces
These three were generated through the same call, with no editing, using the default flux-1-schnell model. The prompt is under each one.
Notice that the model did not follow every instruction literally: the desk got two coffee cups, and the gradient is warmer than “deep indigo and orange” suggests. Treat the first result as a draft, the way you would with any image model, and rerun or reword the prompt when it matters.
Crop it for the platform without another tool
Because the result is a normal PixelVault image, every URL transform works on it. The same social background, cropped to the 1200×630 Open Graph size, is just a query string on the URL you already have:
…/img_xs7dx8d9uvy1.jpg?w=1200&h=630&fit=cover&fmt=autoThat is the whole workflow for a social card or a blog header: generate once, then resize per channel with a URL. Nothing is re-uploaded.
Use it from Claude or any MCP client
The same capability is a tool, generate_image, on the PixelVault MCP server, and on the OAuth connector you add to Claude, so an agent can create an image and get a link it can use straight away. Connect PixelVault to Claude, then ask for what you need:
Use PixelVault to generate a minimalist hero image of a mountain at sunrise, flat illustration, and give me the CDN URL and Markdown.
The tool returns the same fields as the API, including how many credits are left, so the agent can tell you what the call cost. We suggest it calls get_usage first if it is about to generate several images.
Models and credits
Generation draws from a monthly credit grant instead of counting images, because the models differ a lot in cost. A cheap model costs one credit and a Leonardo image costs twenty.
| Model | Credits per image | Plans |
|---|---|---|
flux-1-schnell (default) | 1 | All, including Free |
sdxl-lightning, sdxl-base (beta) | 1 | Starter, Pro |
lucid-origin, phoenix-1.0 (Leonardo) | 20 | Starter, Pro |
- Free: 10 credits a month, which is ten
flux-1-schnellimages. Enough to see whether it fits your workflow. - Starter: 300 credits a month. Pro: 1,500.
- Credits reset on the first of each month (UTC). Deleting an image does not give its credit back.
- If a generation fails or the image can't be stored, the credit is refunded, so a failed call costs nothing.
A generated image also counts toward your normal upload and storage limits, because it is stored like any other image.
Limits and what the errors mean
402 generation_credits_exhausted: you are out of credits until the first, or you can upgrade. Don't retry; it won't succeed.402 model_requires_paid_plan: the free plan can only useflux-1-schnell.429: 60 generations per hour per account, or the service is at its daily capacity. HonorRetry-After.422 prompt_rejected: prompts that clearly ask for adult content are refused.502,503,504: the model failed or timed out. Your credit is refunded and it is safe to retry.
The full list, with every field, is in the API reference.
Where it fits, and where it doesn't
These are open models served by Cloudflare Workers AI, and they are good at illustrations, backgrounds and abstract art like the examples above. They are not the largest models available, so for work that depends on exact text in the image or photoreal faces, test your own prompt before you rely on it. Each model carries its own license, so check the terms in Cloudflare's model catalog before using the output commercially.
If you already generate images with another tool, you don't need this endpoint: our guide to hosting AI-generated images covers turning those expiring URLs and base64 blobs into stable ones. This endpoint is for when you want one call to do both jobs.
Because this is a test, the model list is short on purpose. If there is a model you want, there is a vote button under the plans on the pricing page; that is how we decide what to add.
Try it
The free plan includes 10 generation credits a month with no card. Create an account, grab your key, and run the curl example above.