image.generate
[paid: $0.06/image max] Generate 1-3 images from a text prompt on the first lane that delivers, tried in order: google/nano-banana-2.1 via the Cloudflare AI catalog ($0.06/image), then @cf/black-forest-labs/flux-2-dev via Cloudflare Workers AI, only when the first lane is down ($0.00/image). Each lane settles its own price per delivered image, so an image never costs more than the first lane's price, the credit a call must have available before it runs; price.charged_micro_usd in the result is the actual charge. Nano Banana keeps printed words (signs, labels, posters) legible; for a product photo the owner already has, image.variation with the photo as reference keeps the real product. Each image is stored in this workspace's image library and returned as JSON {images:[{url, asset_key, download_url?, width, height}], price, next} plus a preview; never a provider link. A result with no download_url says why in download_url_unavailable. Refuses: VALIDATION_ERROR on an empty prompt (describe the image), INSUFFICIENT_CREDITS (add credits), SIMPLER_IMAGE_PROMPT_REFUSED names the label (sexual, minor, real_person or other_unsafe): rewrite the prompt without it, for example no real person's name or likeness; SIMPLER_IMAGE_PROMPT_CHECK_UNAVAILABLE (the safety check is down, nothing charged: retry later); SIMPLER_IMAGE_OUTPUT_FLAGGED (the output failed the content check and was refunded: change the prompt); SIMPLER_IMAGE_OUTPUT_SCAN_UNAVAILABLE (outputs cannot be checked right now, nothing charged: retry later). A partial result lists refunded outputs in output.withheld; SIMPLER_IMAGE_RESULT_UNDELIVERED means nothing was charged: retry. For canvas-sized generation inside an edit session use image.generate_for_edit. NEXT: pass images[0].asset_key as image_asset_key to image.variation or image.upscale.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"prompt": "<prompt>"
},
"name": "image.generate"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of images (1-3, default 1). | |
| width | No | Desired width px (256-2048; sets the aspect ratio: the image comes out at about 2K on the long side at the nearest of 21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16). | |
| height | No | Desired height px (256-2048; sets the aspect ratio with width). | |
| prompt | Yes | Image description (max 1500 chars). | |
| request_ref | No | Optional idempotency key (1-64 chars: letters, digits, . _ : -). Retrying with the same request_ref and the same arguments within 24 hours returns the first result at $0 with replayed: true; the same request_ref with different arguments is refused (SIMPLER_IMAGE_REQUEST_REF_CONFLICT), and so is a retry whose first result was deleted since (SIMPLER_IMAGE_REQUEST_REF_RESULT_DELETED): send a new request_ref to run it again. | |
| preview_format | No | Preview block after the JSON, at most 384px on the long edge and never charged: png, jpeg or none. Left out, a PNG result gets a png preview and a JPEG or WebP result a jpeg one. A result with no preview says why in preview_unavailable. |