Compress to KB topic guide

Compress images for Telegram bots: hit the sendPhoto 10 MB cap

Direct answer

When a bot calls sendPhoto, Telegram treats the upload as an inline photo, not a generic file. The Bot API states the photo must be at most 10 MB in size, that width and height must not exceed 10000 in total, and that the width-to-height ratio must be at most 20. If your JPEG or PNG is headed for sendPhoto, compress to a deliberate KB budget under 10 MB before the multipart upload — even when the same bytes might fit under sendDocument’s higher file cap.

Try the Compress to KB

What this workflow handles

Treat sendPhoto’s 10 MB ceiling as the pre-compression check for inline bot photos on the default cloud Bot API. The Sending Files section of the Bot API repeats a 10 MB maximum for photos in multipart/form-data uploads and 50 MB for other files — use sendDocument (or sendVideo/sendAnimation as appropriate) when the bot should deliver a file attachment instead of a photo message. If the bot sends a photo by URL rather than upload, the Bot API documents a lower 5 MB cap for photos (20 MB for other content) — compress for the path your integration actually uses. Dimension rules matter alongside bytes: width plus height must not exceed 10000 total, and aspect ratio must be at most 20. Prefer JPEG for photographs; use PNG for sharp UI screenshots. Enter a Compress to KB target under 10240 KB (commonly 8000–9500 KB), quality-sweep at the original dimensions first when pixels already fit Telegram’s rules, and downscale only if the quality floor still misses the budget or you exceed the dimension sum. Self-hosted local Bot API servers can accept uploads up to 2000 MB — that caveat does not change the default cloud sendPhoto 10 MB rule. Beita’s Compress to KB uses a temporary analysis upload with no long-term storage; see the Privacy Policy for retention details.

Use Compress to KB with a target under 10240 KB (for example 8000–9500 KB) before your bot calls sendPhoto. For a 50 MB file send via sendDocument instead, you may not need this tight cap — see the Bot API Sending Files section. For GitHub’s separate 10 MB issue attachment rule, see Compress image for GitHub.

How to use it

  1. Open the Bot API sendPhoto docs and decide whether the bot should send an inline photo (sendPhoto, 10 MB) or a file (sendDocument, up to 50 MB per Sending Files / bots FAQ).
  2. Check width plus height ≤ 10000 total and aspect ratio ≤ 20; resize if pixels break those rules before you compress bytes.
  3. Pick JPEG for photos and PNG for sharp screenshots; if the bot sends by URL, remember the 5 MB photo-by-URL cap in Sending Files.
  4. Enter a Compress to KB target under 10240 KB (commonly 8000–9500 KB), quality-sweep at the current dimensions first, and allow stepped downscale only if the quality floor still exceeds the budget.
  5. Upload the compressed file through your bot’s sendPhoto path and re-read Telegram’s error if validation still fails — local Bot API servers may allow much larger uploads, but the default cloud API does not.

Frequently asked questions

What is Telegram Bot API sendPhoto’s size limit?

The Bot API sendPhoto method states the photo must be at most 10 MB in size. The same page documents that the photo’s width and height must not exceed 10000 in total and that the width-to-height ratio must be at most 20. Treat 10240 KB as the byte ceiling and aim slightly lower for encoding headroom.

When should the bot use sendDocument instead of sendPhoto?

Use sendPhoto when you want an inline photo in the chat. Use sendDocument when the payload should arrive as a file. The Bot API Sending Files section caps multipart photo uploads at 10 MB but allows other files up to 50 MB. The bots FAQ also notes bots can send files of any type up to 50 MB. A 15 MB PNG might fit as a document but fail sendPhoto — pick the method first, then compress to that method’s published cap.

Does sending a photo by URL use the same 10 MB limit?

Not always. The Bot API Sending Files section lists separate limits when content is sent by URL: 5 MB maximum for photos and 20 MB for other content. If your bot passes a photo URL to sendPhoto instead of uploading multipart data, plan for the 5 MB photo-by-URL cap unless Telegram’s docs for your exact call path say otherwise.

What KB target should I use in Compress to KB?

Start from 10240 KB (10 MB) for sendPhoto uploads and leave headroom: 8000–9500 KB is a practical target for a single inline photo. Quality-sweep first at the original pixel dimensions when width plus height already respect the 10000 total rule; allow stepped downscale only if the quality floor still exceeds the budget or pixels break Telegram’s dimension rules. web.dev’s compress-images guide recommends experimenting with quality rather than assuming one universal setting.

JPEG or PNG for Telegram bot photos?

Prefer JPEG for photographs sent with sendPhoto. Use PNG when you need sharp UI text or flat graphics. Both count against the same sendPhoto byte and dimension rules — pick the format that stays readable after compression.

How does getFile’s download limit relate to sendPhoto?

Upload and download limits are separate. The bots FAQ states bots can send files up to 50 MB but can download files via getFile only up to 20 MB. This page focuses on compressing before sendPhoto’s 10 MB inline photo upload; larger outbound files may use sendDocument within the 50 MB send cap.

How is this different from the GitHub, Discord, WhatsApp, and email guides?

compress-image-for-github covers GitHub Docs 10 MB image and GIF attachments on issues and pull requests — same 10 MB number, different product and API. compress-image-for-discord covers Discord Support 20 MB free per-file chat uploads. compress-image-for-whatsapp covers Meta Cloud API 5 MB JPEG/PNG image messages. compress-image-for-email covers Gmail and Outlook.com 25 MB message attachment totals. compress-image-to-kb covers forms and marketplaces (GOV.UK, LinkedIn, Shopify). This page isolates Telegram Bot API sendPhoto rules from core.telegram.org. Same Compress to KB tool; different destination budget.

Sources

Explore the compress to kb topic cluster

This guide covers Telegram Bot API sendPhoto size and dimensions. Related guides cover general KB budgets, email, WhatsApp, GitHub, and Discord caps, and the Compress to KB tool.

Related guides

All compress to kb guides