Documentation menu
API keys & connected appsImage uploads
Accepted formats and sizes, the presigned upload flow and how uploads become render inputs.
On this page
Every render starts from an image the account owns: one uploaded from a device, one imported from a public address, or one produced by an earlier render.
Accepted files
| Image formats | PNG, JPEG, WebP, GIF, AVIF |
| Workspace upload limit | 20 MB for compressible formats; 10 MB for GIF and SVG |
| Renders reading an image | Up to 32 MB |
| Importing from a URL | Up to 32 MB, public HTTPS only |
| Upload rate limit | 15 uploads a minute per account, website and MCP combined |
Images larger than roughly 500 KB are compressed in the browser before they are sent, down to a 2048-pixel long edge, and AVIF is converted to JPEG on the way. A phone photograph therefore arrives far smaller than its original size without asking, which is why the workspace limit is rarely the one that bites.
How an upload becomes a render input
In the workspace this happens on its own: the file previews at once, uploads in the background, and is read for orientation, scene type and structure on the way. You do not confirm anything.
Over MCP the sequence is explicit, and it has two purposes: the file goes straight to storage rather than through the server, and the account only inherits a file that it actually confirmed.
upload_imagewithaction: "prepare"returns a presigned address, a set of headers, a finalkeyand astagingKey.PUTthe bytes to that address with every returned header unchanged. The address is valid for five minutes by default, an hour at most.upload_imagewithaction: "confirm"moves the file from staging to its final location and returns theimageobject thatcreate_renderaccepts.
prepare checks the general upload limits, not the render limits. It accepts some non-image media types and files much larger than 32 MB, and such a file confirms normally, then create_render refuses it with FORBIDDEN_SOURCE. Check the format and size on the client before preparing the upload.
Anything fetched from a URL follows the same path internally: only a public HTTPS address is accepted, GetRender's own addresses are refused, and redirects are followed at most three times. The file is decoded once before it is stored, so a truncated image is refused at import rather than at render time.
Over MCP, an upload reference stops working when the upload's seven days run out; create_render then returns FORBIDDEN_SOURCE. A finished result keeps working as { "kind": "result", "assetId" } for as long as it stays in the project.
Where files live and how long
| Kind | Retention |
|---|---|
| Staged upload waiting for confirmation | One day |
| Uploaded source image | Seven days |
| Render result | Kept in the project history |
The seven-day window applies to the working copy of an upload. A render keeps using its frozen input, so an older result still compares against the image it was made from, but the upload itself should not be treated as permanent storage: keep your own copy of anything you may need later.
Storage in the library is counted separately, against uploaded images only: 100 MiB on a free account, 10 GiB on a paid plan.
Inputs a render can take
| Input | Notes |
|---|---|
| Source image | Required by most tools. Scaled to a 2048-pixel long edge when it is frozen into a render. |
| Reference image | One per render, optional. It guides atmosphere, palette and materials rather than the layout. |
| Previous result | Any finished result of the same account, used by id. |
| Marked areas | Required by the tools that change one object or one surface. |
Tools that operate on a marked area or on the image's own pixels — material change, area edit, enhance, sketch-to-plan, plan editor — do not take a reference image. A reference image is not a style library either: it is an image you supply for this render, and its role can be set to overall design, style, materials, or light and atmosphere.
Related
Library, presets and prompt recipes · MCP tools · Errors and limits