[← Back to blog](/blog/) By [PixelVault](/about/) October 30, 2026 # Generate an image and get a hosted URL in one API call The usual flow is generate, download, upload, then paste the link. PixelVault now does the first three in a single request, from code or from Claude.  Generated with the endpoint this post describes and hosted on PixelVault, then cropped to 16:9 with `?w=1400&h=788&fit=cover`. 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 Node Python \# One call: prompt in, hosted image out. 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: JSON {   "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.  **Illustration.** “Isometric flat illustration of a tidy desk with a laptop, a small potted plant and a coffee cup, soft pastel colors, clean geometric shapes, plain light background, no text”  **Product backdrop.** “Minimal studio backdrop for product photos: a smooth terracotta pedestal on a warm beige surface, soft morning window light with long gentle shadows, empty space above for text, no objects, no text”  **Social background.** “Abstract gradient mesh background in deep indigo and orange, subtle film grain, soft glowing light, wide airy composition, suitable as a social media card background, no text” 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](/docs/#transforms) 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=auto` That 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](/blog/mcp-image-hosting/), 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](/docs/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-schnell` images. 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 use `flux-1-schnell`. - `429`: 60 generations per hour per account, or the service is at its daily capacity. Honor `Retry-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](/docs/#generate). ## 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](https://developers.cloudflare.com/workers-ai/models/) 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](/blog/host-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](/pricing/); 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](/signup/), grab your key, and run the curl example above. [Read the API reference →](/docs/#generate) ## More in AI-generated images - [How to host GPT Image 2 images on a permanent URL](/blog/host-gpt-image-2-images/) GPT Image 2 returns image bytes with temporary URLs that expire — OpenAI itself says to store them in your own CDN. Here's the one-call way to turn a gpt-image-2 result into a permanent, embeddable URL. - [Generate images with Nano Banana, host them on PixelVault](/blog/nano-banana-image-hosting/) Turn a prompt into a permanent CDN URL your coding agent can embed: generate a hero or OG card with Nano Banana (Google's Gemini image model), host it on PixelVault, done. Includes the open-source skill that does it. - [How to host AI-generated images](/blog/host-ai-generated-images/) DALL·E, GPT Image, Midjourney, and Flux give you URLs that expire in an hour. Here's how to make them permanent in one call. [All posts in AI-generated images →](/blog/topics/ai-images/)