# Generate an image from a text prompt with Vimmerse's API Vimmerse's text-to-image API returns a finished image URL from one POST to `https://agents.vimmerse.net/zcj/xuf4jsbz9dyf/v2/image/text-2-image`. Each call is charged its credits at $0.03 per credit, and the free estimate route tells you the credit count before you pay. The storefront answers the first request with a 402, the price quote, which you settle with a wallet over x402 or MPP and then retry unchanged. ## At a glance - **Endpoint:** `POST https://agents.vimmerse.net/zcj/xuf4jsbz9dyf/v2/image/text-2-image` - **Body:** `prompt` (the description), plus optional `option`, `quantity`, `aspect_ratio`, `async_mode`, `enhance_image`, `webhook_url` - **Price:** credits times $0.03 per credit. `POST https://agents.vimmerse.net/zcj/xuf4jsbz9dyf/v2/image/estimate-credits` returns the credit count for free. - **Payment:** a 402 price quote, settled over x402 (Base USDC) or MPP (Tempo USDC) and retried. A card works per call only from $0.50. - **Identity:** a free agent credential, sent on the paid call as `ZC-Agent-Authorization: Bearer ` - **Response:** an asset object with the image URLs in `results` - **Limits:** 1 to 4 images per call. The call stays open until the image is ready unless you set `async_mode`. - **Full purchase flow:** [the buyer skill](https://agents.vimmerse.net/zcj/xuf4jsbz9dyf/SKILL.md) ## Generate your first image 1. Get the free agent credential and a short-lived access token as [the identity reference](https://agents.vimmerse.net/zcj/xuf4jsbz9dyf/auth.md) describes, reusing a credential you already hold from any ZeroClick storefront. 2. Estimate the credits. This call is free and creates nothing: ```bash curl -s -X POST https://agents.vimmerse.net/zcj/xuf4jsbz9dyf/v2/image/estimate-credits \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -d '{"app_name": "text-to-image", "option": "AutoI", "quantity": 1}' ``` The response is `{"total_credits": , "breakdown": {...}}`. For one `AutoI` image, the estimate is 4 credits. At the pay-per-call rate, that is $0.12. 3. Send the generation request. The first answer is the 402: ```bash curl -s -i -X POST https://agents.vimmerse.net/zcj/xuf4jsbz9dyf/v2/image/text-2-image \ -H 'Content-Type: application/json' \ -H "ZC-Agent-Authorization: Bearer $ACCESS_TOKEN" \ -d '{"prompt": "a lighthouse on a rocky coast at dusk, watercolor"}' ``` The 402 body carries `payment.amountUsd`, the `plan` and a `protocols` block. The signable challenges also arrive as headers: `payment-required` for x402 and `www-authenticate` for MPP. Nothing is charged at this point, so it is safe to stop here. 4. Pay and retry the same request with the proof attached. Keep the token header, and set a client timeout of several minutes: ```bash curl -s --max-time 300 -X POST https://agents.vimmerse.net/zcj/xuf4jsbz9dyf/v2/image/text-2-image \ -H 'Content-Type: application/json' \ -H "ZC-Agent-Authorization: Bearer $ACCESS_TOKEN" \ -H "x-payment: $X402_PAYMENT" \ -d '{"prompt": "a lighthouse on a rocky coast at dusk, watercolor"}' ``` On MPP, send the credential as `Authorization: Payment ` in place of `x-payment`. The example request was quoted 4 credits and paid $0.12 over x402. That call stayed open 50.5 seconds before it answered 200 with the finished image. A short default timeout drops the response after you have paid. 5. Read `results`. The response is an asset object: ```json { "id": "", "status": "success", "app_name": "text-to-image", "mime_type": "image/png", "quantity": 1, "credits": "", "args": {"prompt": "…", "option": "AutoI", "aspect_ratio": "16:9", "quantity": 1, "async_mode": false, "enhance_image": false}, "results": ["https://.png"] } ``` Download each URL in `results`. `credits` and `args` record what the call charged and what it ran with. ## Why the token goes on the paid call A job belongs to the identity that paid for it. If you pay with a wallet and send no token, the job belongs to the wallet, and a later poll with your token answers 404. Send `ZC-Agent-Authorization: Bearer` on the paid request, and use the same token for every poll and estimate. The dedicated header keeps the token apart from an MPP `Authorization: Payment` credential, so one request works on either rail. ## Set the request fields | Field | Values | Effect | | --- | --- | --- | | `option` | `AutoI` (default), `Seedream`, `NanoBananaT2`, `NanoBananaPro`, `QwenImage`, `GPTImage`, `FluxPro`, `FluxTurbo`, `NanoBanana`, `FluxKontextPro`, `StableDiffusion3.5` | `AutoI` picks a model for you. A named model can cost more credits. | | `quantity` | `1` to `4` | Number of images in one call. Estimate with the same quantity. | | `aspect_ratio` | `21:9`, `16:9` (default), `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `9:16`, `9:21` | Output shape | | `async_mode` | `false` (default), `true` | `true` returns at once with `status: processing` | | `enhance_image` | `false` (default), `true` | Applies 1× super-resolution after generation | With `option` set to `NanoBananaPro`, the estimate for one image is 16 credits. At the pay-per-call rate, that is $0.48. Run the estimate with the exact `option` and `quantity` before each new combination. With `async_mode: true`, keep the `id` from the response. Poll `GET https://agents.vimmerse.net/zcj/xuf4jsbz9dyf/v2/asset/{asset_id}`, which is free, with the same bearer until `status` is `success`, and then read `results`. ## Boundaries - This route generates images from text only. Editing an existing image is a separate route, `/v2/image/image-2-image`, which takes an `image_url`. - A pay-per-call image is paid for over a wallet. A card can pay a single call only when it costs $0.50 or more. For smaller calls by card, buy prepaid Credits (from $14) through `/plans/{planId}/purchase`. The plan ids are in the catalog. - The estimate route and asset polling are free. Only the paid 402 charges anything. ## Errors on this job | Status or code | Meaning | Action | | --- | --- | --- | | `402` with a `payment` block | The price quote. Nothing is charged yet. | Pay it and retry the same request, or stop | | `401 invalid_token`, reason `token_expired` | The access token has expired | Exchange the stored assertion for a fresh token | | `invalid_token`, reason `malformed_agent_authorization` | `ZC-Agent-Authorization` held more than one `Bearer ` | Send exactly one token | | `422` | A field value is outside the spec, such as an unknown `option` | Use a value from the table above | | `settlement_failed` | The payment did not settle (`settlementReason` says why) | Fix the wallet, then start again for a fresh 402 | | `404` on a poll | The job was paid under no identity or a different one | Poll with the token you sent on the paid call | ## Other services on the same payment Each service uses the same 402, wallet and token. Service slugs label prices and are never request values. Each service's operations and its estimate route are in `https://agents.vimmerse.net/zcj/xuf4jsbz9dyf/services/{slug}/openapi.json`. | Service | What it makes | How the result arrives | Pay per call | | --- | --- | --- | --- | | AI Audio (`audio`) | Speech, sound effects and music from text | The file URL in the response | $0.03 | | AI Video from text or images (`media`) | A clip from a prompt, optionally from reference images, with narration or music | Poll `GET /v2/media/{media_id}` until `processing_status` is `success` | $0.03 | | AI Video tools (`video`) | Video from public image and video URLs: reference to video, video to video, motion effects, enhancement, reframing | Send `async_mode: true`, then poll `GET /v2/asset/{asset_id}` until `status` is `success` | $0.03 | | AI Story (`story`) | A multi-scene video from an idea, a page URL or image URLs | Poll `GET /v2/story/{story_id}` until `status` is `success`, then read `video_url` | $0.03 | | Workflow templates (`workflow`) | A published template run on your images | Poll `GET /v2/workflow/{workflow_id}` until `processing_status` is `success` | $0.03 | | Prompt tools (`text`) | A written or refined generation prompt | A single string | $0.03 | ## Frequently asked questions ### Does the Vimmerse image generation API need an API key? No. Each call is paid at the request over x402 or MPP, with no signup and no API key. The free agent credential is not a key. It ties the job to an identity, so the same token can poll it. ### How much does one generated image cost? It costs the call's credits times $0.03 per credit. One `AutoI` image is estimated at 4 credits, which is $0.12, and a named model such as `NanoBananaPro` can cost more. Run the free image estimate route with your `option` and `quantity` first. The 402 states the exact amount before you pay. ### Can one call generate several images? Yes. Set `quantity` from 1 to 4, and every URL comes back in `results`. Run the estimate with the same quantity to see the credits before you pay. ### Which model does AutoI use? `AutoI` selects one of the available models for each request. To fix the model, set `option` to a named value from the list above, and check its credits on the estimate route first. ### Can I prepay instead of paying per image? Yes. The Credits, Pro credits and Business credits plans are prepaid balances that calls draw down: Credits at $28 per thousand credits from $14, Pro credits at $24 per thousand credits from $120, and Business credits at $20 per thousand credits from $1000. Buying one needs the agent credential. The buyer skill covers the purchase. ## Keep reading - [The buyer skill](https://agents.vimmerse.net/zcj/xuf4jsbz9dyf/SKILL.md): the full purchase and recovery flow - [Identity](https://agents.vimmerse.net/zcj/xuf4jsbz9dyf/auth.md): registering, exchanging and refreshing the agent credential - [How to pay](https://agents.vimmerse.net/zcj/xuf4jsbz9dyf/payment.md): x402, MPP, card and prepaid credit - [Error reference](https://agents.vimmerse.net/zcj/xuf4jsbz9dyf/errors.md): every storefront error code - [Services and prices](https://agents.vimmerse.net/zcj/xuf4jsbz9dyf/services): every service with its price matrix --- Updated 2026-11-06. All Vimmerse guides: https://agents.vimmerse.net/guides.md. Storefront: https://agents.vimmerse.net/zcj/xuf4jsbz9dyf/llms.txt.