Error 413: request too large — how to work around it

Update, October 2026. Image generation through Zukko is temporarily unavailable, so the /v1/images/generations examples below can't be run right now. The current model list is on the Models page↗ or at GET https://api.zukko.pro/v1/models. Closest replacement: for requests with image input, the Claude and GPT vision models (e.g. claude-sonnet-5, gpt-5.6-sol); everything below about 413 and base64 weight applies to them.

A 413 differs from the gateway's other errors in that it never reaches the API's own logic: the server rejects the request body at the intake level, before checking the key, the balance, or the model. If a request carrying an image fails with 413, it almost always means one thing — the request body itself is too heavy, not that something is wrong with the key or the image's content.

Where the extra weight comes from

413 shows up most often when an image is sent as a data URL — data:image/png;base64,... embedded directly in the JSON body. Base64 encoding isn't free: it inflates the data by roughly a third over the source file's weight. A 6 MB photo turns into a string of around 8 MB, and if a single request carries several images at once — for instance, reference mode with an images array — the weight stacks, and the combined body quickly grows past what the server is willing to accept.

The gateway doesn't publish or guarantee an exact numeric limit — it belongs to the request-intake infrastructure rather than the API's business logic, and it can differ by route. It's more reliable to treat 413 as a "the body is too big right now" signal than to try to calculate an exact byte threshold in advance and hardcode it.

First fix: a URL instead of a data URL

The images field on /v1/images/generations accepts a plain file URL, not only a data URL:

curl https://api.zukko.pro/v1/images/generations \
  -H "Authorization: Bearer fetch_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-edit-developer",
    "prompt": "remove the background, keep only the object",
    "images": ["https://example.com/source.png"]
  }'

If a file already lives in a publicly reachable place — S3, a CDN, any static host — pass the direct link instead of encoding the file into base64 and bloating the JSON body. The request body stays tiny regardless of the image's real weight, because the model fetches the file from the link itself instead of receiving it inline.

When there's no link and a data URL is unavoidable

When a file is private and hosting it just for one request isn't worth it, the option left is compressing or downsizing the image before encoding. A practical order of steps:

• lower the resolution to what the task actually needs — reference and edit modes don't need a print-resolution source;
• re-save as JPEG at a reasonable compression quality instead of PNG, if the image is photographic rather than graphics with text or sharp edges — PNG weighs noticeably more for comparable visual quality on photos;
• drop unnecessary images from the request if reference mode is being used with an images array and some samples aren't critical to the result.

Each of these steps cuts the base64 string's weight directly, without losing what the model actually needs to generate from.

It's not a token limit and not a balance issue

413 is worth distinguishing from errors that arrive after the server has already accepted the body: 401 for a bad key, 402 for an empty balance, 400 model_not_found for a typo in the model name. All of those come back with a JSON response body and a message field explaining the cause. A 413 typically arrives without that kind of informative JSON body — it's a transport-level failure, not an API one, and the first thing worth checking isn't the error text but the actual size of what's being sent.

Checking body size before sending

The fastest way is to measure the finished JSON's weight locally before firing the request:

echo -n '{"model":"...", "images":["data:image/png;base64,..."]}' | wc -c

If the result is measured in megabytes rather than kilobytes, that's already a signal to try a URL instead of a data URL or shrink the source image, rather than waiting for an actual 413 from the server.

For reference and edit with multiple samples

In reference mode, the images array can hold more than one file. If a single high-resolution sample goes through but adding a second and third triggers a 413, the issue isn't a specific file — it's the sum of their weights. In that case it's more sensible to keep only the single most informative sample, or replace some of the data URLs with plain links where the files are publicly reachable.

Vision requests to text models hit this too

The same logic applies when sending an image into a vision-capable text model through /v1/messages or /v1/chat/completions. If a conversation accumulates several messages with base64-encoded images, the combined weight of the message history grows with every new picture. If a 413 shows up not on the first message but after several in a row, the likely cause isn't the latest file — it's the accumulated weight of the whole history. It helps to avoid keeping old images in the conversation context verbatim, and instead keep only a text description of an already-processed image once the model no longer needs to see the original file again.

The short version

413 is a transport-level error, not a business-logic one: the key, the balance, and the model's correctness have nothing to do with it. The cause is almost always the same — the request body is physically too heavy because of base64-encoding one or more images. The most reliable fix is passing images by link wherever possible, and for private files, downsizing the resolution and switching to JPEG for photographic content instead of PNG.