> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Understanding Requests Keep Timing Out — Is the Image Too Large?

> If a GPT vision request hangs, returns 429 upstream saturated, or 400 patches exceeding the limit, the image is most likely too large. Per-route limits, how to check, and resize code.

## Short Answer

Most likely, yes. GPT models process images in 32×32-pixel patches, so a larger image means more patches. When a single image exceeds roughly **30 megapixels** (for example 6700×4500), some routes reject it outright. Above roughly **60 megapixels**, the request is often **queued for several minutes before being rejected** during peak hours, so your client times out first and the request looks like it "never responds".

These failures are deterministic: **retrying or switching API keys will not help**. Resize the image so its longer side is about 2048 pixels before uploading. Recognition quality stays the same, and input tokens drop to a small fraction of the original.

## Three Typical Symptoms

The same oversized image can fail in any of these ways, depending on the route and time of day:

| What you see | Error keyword | Explanation |
| - | - | - |
| The request never responds; the client eventually times out or the connection is closed | None (the client only sees a timeout) | The provider queues the request during peak hours and rejects it after about 5 minutes, by which time the client has already disconnected |
| `429` upstream load saturated for the current group | `exceeds the maximum usage size allowed during peak load` | A single request exceeds the usage allowed during peak load. This is not concurrency rate limiting |
| `400` image over the limit | `requires 67081 patches after processing, exceeding the limit of 30000` | The processed image exceeds the patch limit and must be resized |

> [!WARNING]
>
> Do not ramp up retries when you see `429`. Read the error message first: if it mentions `maximum usage size` or `patches`, the request itself is too large, and retries only keep occupying concurrency and waiting.

## Test Results: Image Size vs. Outcome

On 2026-10-20 we sent the same image at different sizes to `gpt-6.1-sol` (JPEG, uploaded as Base64 through `image_url` on the OpenAI-compatible chat endpoint):

| Image size | Pixels | Request body | Result | Time | Input tokens |
| - | - | - | - | - | - |
| 2048×1365 | 2.8 MP | 0.75 MB | Success, all text recognized correctly | 6 s | 3,321 |
| 4096×2731 | 11.2 MP | 2.9 MB | Success | 10 s | 13,228 |
| 6000×4000 | 24 MP | 6.2 MB | Success | 20 s | 28,219 |
| 7200×4800 | 34.6 MP | 8.8 MB | Success | 26 s | 40,519 |
| 9000×6000 | 54 MP | 13.7 MB | Success | 40 s | 63,638 |
| 10240×6827 | 70 MP | 17.7 MB | **No response; connection closed after about 300 s** | — | — |

What this shows:

* **Tokens grow linearly with pixels**, roughly "pixels ÷ 1024 × 1.2". The 9000×6000 image costs about 19 times as many tokens as the 2048 version, with identical recognition results.
* **Whether a large image passes depends on the route and the time of day.** The table above was measured off-peak on a single route. Another route enforces a hard limit of 30,000 patches (about 30 megapixels) per image, and the threshold is lower during peak hours.
* So **do not treat "it passed in a test" as a safe limit.** For image understanding, a longer side of 2048 pixels is enough.

## How to Tell If the Image Is Too Large

**1. Check the request body size**

Base64 encoding inflates the size by about 1.33×. A request body of several MB, or more than 10 MB, almost certainly means the image was not resized.

**2. Check the error message**

Search for `patches`, `maximum usage size`, or `image exceeds`. Any of these means the image is too large.

**3. Compare with a resized image**

Resize the same image to a longer side of 2048 and send it again. If it returns within seconds, the problem is the image size, not the model or the network.

## Fix: Resize Before Uploading

```python theme={null}
import base64, io
from PIL import Image

def image_to_data_uri(path, max_side=2048, quality=85):
    img = Image.open(path)
    img = img.convert("RGB")                      # normalize to RGB; handles PNG, MPO, etc.
    img.thumbnail((max_side, max_side))           # keep aspect ratio, longer side <= max_side
    buf = io.BytesIO()
    img.save(buf, "JPEG", quality=quality)
    return "data:image/jpeg;base64," + base64.b64encode(buf.getvalue()).decode()
```

Put the return value in `image_url.url`. After resizing, an image is usually a few hundred KB and returns within seconds.

> [!TIP]
>
> If you need to read very small text (such as footnotes on a full-page scan), **split the page into several tiles** and upload them separately, or crop to the region you need, instead of uploading one huge original. Each tile stays within the safe range, and recognition is often better.

## FAQ

> **Why does the same model work fine for other users?**
>
> Most users upload screenshots or phone photos that end up at a few megapixels. The per-request usage limit is only hit when someone uploads originals of tens of megapixels, so other users are not affected at the same time.

> **Am I charged for these failures?**
>
> Requests rejected by the provider (`429`, `400`) do not create a consumption record. You can confirm this in your usage logs.

> **Will a longer client timeout fix it?**
>
> No. A longer timeout only means you wait until the provider rejects the request; it still fails. The fix is to resize the image.

> **Do Claude, Gemini, and other models have limits too?**
>
> Yes, with different rules: Claude rejects any single image over 10 MB (also with a `429`), Kimi errors when one image exceeds 16,384 tokens, Seed caps total pixels at 36 megapixels, and Gemini downscales automatically. See the "Downscale large images first" section of [Vision Understanding](/en/api-capabilities/vision-understanding).

## Related Docs

> **[Vision Understanding](/en/api-capabilities/vision-understanding)**
>
> How to send images to each model, large-image handling, and test results

> **[How Can I Troubleshoot Model API Errors?](/en/faq/model-error-troubleshooting)**
>
> Locate problems by error type

> **[How Do I Avoid API Timeouts?](/en/faq/timeout-configuration)**
>
> Timeout configuration and long-request troubleshooting

> **[What Are the API Concurrency Limits?](/en/faq/api-concurrency)**
>
> Tell real concurrency limits apart from other 429s


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.