Avatar photo 413 image_too_large: 16,384 px and 100 MP limits

A Sume avatar photo returns 413 image_too_large when it is wider or taller than 16,384 px, or when width times height is more than 100,000,000 pixels (100 megapixels). A separate branch of the same code covers a response that is larger in bytes than the configured upload limit, and then details carries max_bytes and size_bytes. Resize the picture and send it again.

The check runs in the avatar photo preflight, before a job or a reservation exists. Source for the request shape: Create new avatar, read 2026-10-05.

Where the line is

The pixel limit is applied to the decoded header size, so a heavily compressed file can still fail while a large-looking file with small dimensions passes. The two dimension rules are independent, which is why a very long, thin image can fail the side rule while its pixel count is small.

• Downscale before hosting; the avatar renders at 720p, so extra pixels buy nothing.
• Keep both sides at or below 16,384 px.
• Keep width times height at or below 100,000,000.
• Watch details.size_bytes and details.max_bytes when the byte cap is the cause.

Check before you submit

Check any dimensions you have before the call.

def too_large(width, height):
    return width > 16384 or height > 16384 or width * height > 100_000_000

for w, h in [(4000, 6000), (12000, 8000), (10000, 10000), (10001, 10000), (16385, 1000)]:
    print(w, h, w * h, "413" if too_large(w, h) else "ok")

Do not confuse it with payload_too_large

This is not the same 413 as payload_too_large. That code in the error table is about the JSON body of your request being over the API limit. A photo avatar request carries only a URL, so its body is tiny; image_too_large is about the file at the other end of the URL, and the error names the host in details.url_host.

In practice, a photo for a talking avatar does not need 100 megapixels. Phone cameras and design exports are the usual source of oversize files, and a downscale to a few thousand pixels on the long side keeps the face sharp. Sume does not state a recommended resolution in these docs, so treat any specific target as your own choice and use the preview stills to judge.

Tests pin both sides of the line

A photo that is exactly 100,000,000 pixels passes, and one pixel row more does not. The API test suite checks both sides of the line: 10,000 x 10,000 is accepted and 10,001 x 10,000 is rejected with 413 image_too_large and details.reason: image_dimensions_too_large. Expect the same behaviour at the side limit, where 16,384 passes and 16,385 does not.

These limits are about what Sume will accept, not what suits an avatar. A talking avatar video renders at 720p, so a photo in the tens of megapixels adds transfer time without adding anything the output can show.

Why a big file can fail as a fetch error instead

Preflight runs under a 15 second abort that covers both the response and reading the body. A huge file on a slow host can therefore end as image_not_fetchable with a null status rather than as image_too_large. If a large photo fails with a fetch error, shrink it before you suspect the host. The timing rule is described in the 15 second preflight post.

One checklist for all three

Fix order for a failed photo: check the content type first (unsupported_image_type), then the pixel rules (invalid_image), then this one. All three come back as 400 or 413 with details.suggested_input, and none of them creates a job.