image.convert
[paid: $0.0005] Convert an image to PNG, JPEG or WebP, and optionally bound its size, with the Cloudflare Images service: a PNG, JPEG, WebP, GIF or HEIC goes in and the result is stored in this workspace. format is png, jpeg, webp (AVIF is not offered). quality (1-100, default 85) applies to jpeg and webp. width and height (16-4096 px) bound the result and fit picks how: scale-down (the default) shrinks to fit and never enlarges, contain fits inside and may enlarge, cover and crop fill the box and cut the overflow, pad fits inside and fills the rest with background. background (#RRGGBB) fills transparent pixels and padding; a JPEG, which has no transparency, is laid on white unless you name a colour. One call is one Images transformation at $0.0005, charged only when the result is stored; the preview is never charged. Returns JSON {images:[{url, asset_key, download_url?, width, height, content_type}], price, output: {format, bytes, quality?, input_format, input_bytes}, next} plus a preview; a result with no download_url says why in download_url_unavailable. Refuses: SIMPLER_MEDIA_INPUT_MISSING (pass the url or the asset_key), SIMPLER_MEDIA_FOREIGN_KEY (use this workspace's asset_key), SIMPLER_MEDIA_URL_REFUSED (use https, data:image or an asset_key), VALIDATION_ERROR naming the field for a format outside the list, a quality with png, a size outside the range, a fit without width or height, or a background that is not #RRGGBB; SIMPLER_IMAGES_BINDING_ABSENT (this deployment has no Images binding yet, owner step O-2: send a standard PNG), SIMPLER_IMAGES_QUOTA_EXCEEDED or SIMPLER_IMAGES_LEGACY_SUBSCRIPTION (an owner account step: send a standard PNG meanwhile), SIMPLER_IMAGES_INPUT_UNREADABLE (send a PNG, JPEG, WebP, GIF or HEIC), SIMPLER_IMAGES_INPUT_TOO_LARGE (under 20,000,000 bytes and 100 megapixels), SIMPLER_IMAGES_TRANSFORM_FAILED (retry, or send a standard PNG); nothing is charged on any of them; SIMPLER_MEDIA_PIN_TOO_LARGE when the result is over 20MB (pass width and height, or pick jpeg or webp); INSUFFICIENT_CREDITS or PAYMENT_REQUIRED when the workspace cannot cover $0.0005 or is past its spend cap (add credits or raise the cap). NEXT: Pass images[0].asset_key as image_asset_key to image.adjust, image.marketplace_check or another image.* tool; a download_url, when the result carries one, works for 24 hours without a session.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fit | No | How the image fits width and height (default scale-down). Needs width or height. | |
| width | No | Bounding width in pixels; leave width and height out to keep the size. | |
| format | Yes | The result's file type: png (lossless, keeps transparency), jpeg (smallest for photos, no transparency) or webp. | |
| height | No | Bounding height in pixels; leave width and height out to keep the size. | |
| quality | No | jpeg and webp only: 1-100, default 85. Refused with png. | |
| image_url | No | The image to convert: a public https URL, a data:image/...;base64 URL, or the url/url_path of an earlier image result (max 20MB; PNG, JPEG, WebP, GIF or HEIC; SVG is refused). Pass this or image_asset_key, not both. | |
| background | No | #RRGGBB under transparent pixels and around a padded image. A jpeg defaults to #FFFFFF. | |
| 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. | |
| image_asset_key | No | The image to convert, as the asset_key of an earlier image result for this workspace (edit-projects/<tenant>/... or images/<tenant>/...). A key from another workspace is refused (SIMPLER_MEDIA_FOREIGN_KEY). |