mirror of
https://github.com/MarshalX/telegram-crawler.git
synced 2024-12-29 15:59:13 +01:00
571 lines
56 KiB
HTML
571 lines
56 KiB
HTML
<!DOCTYPE html>
|
||
<html class="">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<title>Uploading and Downloading Files</title>
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta property="description" content="How to transfer large data batches correctly.">
|
||
<meta property="og:title" content="Uploading and Downloading Files">
|
||
<meta property="og:image" content="1937a1be855ea8fce8">
|
||
<meta property="og:description" content="How to transfer large data batches correctly.">
|
||
<link rel="icon" type="image/svg+xml" href="/img/website_icon.svg?4">
|
||
<link rel="apple-touch-icon" sizes="180x180" href="/img/apple-touch-icon.png">
|
||
<link rel="icon" type="image/png" sizes="32x32" href="/img/favicon-32x32.png">
|
||
<link rel="icon" type="image/png" sizes="16x16" href="/img/favicon-16x16.png">
|
||
<link rel="alternate icon" href="/img/favicon.ico" type="image/x-icon" />
|
||
<link href="/css/bootstrap.min.css?3" rel="stylesheet">
|
||
|
||
<link href="/css/telegram.css?230" rel="stylesheet" media="screen">
|
||
<style>
|
||
</style>
|
||
</head>
|
||
<body class="preload">
|
||
<div class="dev_page_wrap">
|
||
<div class="dev_page_head navbar navbar-static-top navbar-tg">
|
||
<div class="navbar-inner">
|
||
<div class="container clearfix">
|
||
<ul class="nav navbar-nav navbar-right hidden-xs"><li class="navbar-twitter"><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)"><i class="icon icon-twitter"></i><span> Twitter</span></a></li></ul>
|
||
<ul class="nav navbar-nav">
|
||
<li><a href="//telegram.org/">Home</a></li>
|
||
<li class="hidden-xs"><a href="//telegram.org/faq">FAQ</a></li>
|
||
<li class="hidden-xs"><a href="//telegram.org/apps">Apps</a></li>
|
||
<li class="active"><a href="/api">API</a></li>
|
||
<li class=""><a href="/mtproto">Protocol</a></li>
|
||
<li class=""><a href="/schema">Schema</a></li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="container clearfix">
|
||
<div class="dev_page">
|
||
<div id="dev_page_content_wrap" class=" ">
|
||
<div class="dev_page_bread_crumbs"><ul class="breadcrumb clearfix"><li><a href="/api" >API</a></li><i class="icon icon-breadcrumb-divider"></i><li><a href="/api/files" >Uploading and Downloading Files</a></li></ul></div>
|
||
<h1 id="dev_page_title">Uploading and Downloading Files</h1>
|
||
|
||
<div id="dev_page_content"><!-- scroll_nav -->
|
||
|
||
<p>When working with the API, it is sometimes necessary to send a relatively large file to the server. For example, when sending a message with a photo/video attachment or when setting the current user's profile picture.</p>
|
||
<h3><a class="anchor" href="#uploading-files" id="uploading-files" name="uploading-files"><i class="anchor-icon"></i></a>Uploading files</h3>
|
||
<p>There are a number of API methods to save files. The schema of the types and methods used is presented below:</p>
|
||
<pre><code><a href='/constructor/inputFile'>inputFile</a>#f52ff27f id:<a href='/type/long'>long</a> parts:<a href='/type/int'>int</a> name:<a href='/type/string'>string</a> md5_checksum:<a href='/type/string'>string</a> = <a href='/type/InputFile'>InputFile</a>;
|
||
<a href='/constructor/inputFileBig'>inputFileBig</a>#fa4f0bb5 id:<a href='/type/long'>long</a> parts:<a href='/type/int'>int</a> name:<a href='/type/string'>string</a> = <a href='/type/InputFile'>InputFile</a>;
|
||
|
||
|
||
<a href='/constructor/inputEncryptedFileUploaded'>inputEncryptedFileUploaded</a>#64bd0306 id:<a href='/type/long'>long</a> parts:<a href='/type/int'>int</a> md5_checksum:<a href='/type/string'>string</a> key_fingerprint:<a href='/type/int'>int</a> = <a href='/type/InputEncryptedFile'>InputEncryptedFile</a>;
|
||
<a href='/constructor/inputEncryptedFileBigUploaded'>inputEncryptedFileBigUploaded</a>#2dc173c8 id:<a href='/type/long'>long</a> parts:<a href='/type/int'>int</a> key_fingerprint:<a href='/type/int'>int</a> = <a href='/type/InputEncryptedFile'>InputEncryptedFile</a>;
|
||
|
||
<a href='/constructor/inputSecureFileUploaded'>inputSecureFileUploaded</a>#3334b0f0 id:<a href='/type/long'>long</a> parts:<a href='/type/int'>int</a> md5_checksum:<a href='/type/string'>string</a> file_hash:<a href='/type/bytes'>bytes</a> secret:<a href='/type/bytes'>bytes</a> = <a href='/type/InputSecureFile'>InputSecureFile</a>;
|
||
<a href='/constructor/inputSecureFile'>inputSecureFile</a>#5367e5be id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> = <a href='/type/InputSecureFile'>InputSecureFile</a>;
|
||
|
||
<a href='/constructor/inputMediaUploadedPhoto'>inputMediaUploadedPhoto</a>#1e287d04 flags:<a href='/type/%23'>#</a> file:<a href='/type/InputFile'>InputFile</a> stickers:flags.0?<a href='/type/Vector%20t'>Vector</a><<a href='/type/InputDocument'>InputDocument</a>> ttl_seconds:flags.1?<a href='/type/int'>int</a> = <a href='/type/InputMedia'>InputMedia</a>;
|
||
<a href='/constructor/inputMediaUploadedDocument'>inputMediaUploadedDocument</a>#5b38c6c1 flags:<a href='/type/%23'>#</a> nosound_video:flags.3?<a href='/constructor/true'>true</a> force_file:flags.4?<a href='/constructor/true'>true</a> file:<a href='/type/InputFile'>InputFile</a> thumb:flags.2?<a href='/type/InputFile'>InputFile</a> mime_type:<a href='/type/string'>string</a> attributes:<a href='/type/Vector%20t'>Vector</a><<a href='/type/DocumentAttribute'>DocumentAttribute</a>> stickers:flags.0?<a href='/type/Vector%20t'>Vector</a><<a href='/type/InputDocument'>InputDocument</a>> ttl_seconds:flags.1?<a href='/type/int'>int</a> = <a href='/type/InputMedia'>InputMedia</a>;
|
||
|
||
<a href='/constructor/inputChatUploadedPhoto'>inputChatUploadedPhoto</a>#c642724e flags:<a href='/type/%23'>#</a> file:flags.0?<a href='/type/InputFile'>InputFile</a> video:flags.1?<a href='/type/InputFile'>InputFile</a> video_start_ts:flags.2?<a href='/type/double'>double</a> = <a href='/type/InputChatPhoto'>InputChatPhoto</a>;
|
||
|
||
|
||
---functions---
|
||
|
||
<a href='/method/messages.sendMedia'>messages.sendMedia</a>#e25ff8e0 flags:<a href='/type/%23'>#</a> silent:flags.5?<a href='/constructor/true'>true</a> background:flags.6?<a href='/constructor/true'>true</a> clear_draft:flags.7?<a href='/constructor/true'>true</a> noforwards:flags.14?<a href='/constructor/true'>true</a> peer:<a href='/type/InputPeer'>InputPeer</a> reply_to_msg_id:flags.0?<a href='/type/int'>int</a> media:<a href='/type/InputMedia'>InputMedia</a> message:<a href='/type/string'>string</a> random_id:<a href='/type/long'>long</a> reply_markup:flags.2?<a href='/type/ReplyMarkup'>ReplyMarkup</a> entities:flags.3?<a href='/type/Vector%20t'>Vector</a><<a href='/type/MessageEntity'>MessageEntity</a>> schedule_date:flags.10?<a href='/type/int'>int</a> send_as:flags.13?<a href='/type/InputPeer'>InputPeer</a> = <a href='/type/Updates'>Updates</a>;
|
||
<a href='/method/messages.uploadMedia'>messages.uploadMedia</a>#519bc2b1 peer:<a href='/type/InputPeer'>InputPeer</a> media:<a href='/type/InputMedia'>InputMedia</a> = <a href='/type/MessageMedia'>MessageMedia</a>;
|
||
<a href='/method/messages.sendEncryptedFile'>messages.sendEncryptedFile</a>#5559481d flags:<a href='/type/%23'>#</a> silent:flags.0?<a href='/constructor/true'>true</a> peer:<a href='/type/InputEncryptedChat'>InputEncryptedChat</a> random_id:<a href='/type/long'>long</a> data:<a href='/type/bytes'>bytes</a> file:<a href='/type/InputEncryptedFile'>InputEncryptedFile</a> = <a href='/type/messages.SentEncryptedMessage'>messages.SentEncryptedMessage</a>;
|
||
|
||
<a href='/method/photos.uploadProfilePhoto'>photos.uploadProfilePhoto</a>#89f30f69 flags:<a href='/type/%23'>#</a> file:flags.0?<a href='/type/InputFile'>InputFile</a> video:flags.1?<a href='/type/InputFile'>InputFile</a> video_start_ts:flags.2?<a href='/type/double'>double</a> = <a href='/type/photos.Photo'>photos.Photo</a>;
|
||
|
||
<a href='/method/upload.saveFilePart'>upload.saveFilePart</a>#b304a621 file_id:<a href='/type/long'>long</a> file_part:<a href='/type/int'>int</a> bytes:<a href='/type/bytes'>bytes</a> = <a href='/type/Bool'>Bool</a>;
|
||
<a href='/method/upload.saveBigFilePart'>upload.saveBigFilePart</a>#de7b673d file_id:<a href='/type/long'>long</a> file_part:<a href='/type/int'>int</a> file_total_parts:<a href='/type/int'>int</a> bytes:<a href='/type/bytes'>bytes</a> = <a href='/type/Bool'>Bool</a>;</code></pre>
|
||
<p>Before transmitting the contents of the file itself, the file has to be assigned a unique 64-bit client identifier: <strong>file_id</strong>.</p>
|
||
<p>The file's binary content is then split into parts. All parts must have the same size ( <strong>part_size</strong> ) and the following conditions must be met:</p>
|
||
<ul>
|
||
<li><code>part_size % 1024 = 0</code> (divisible by 1KB)</li>
|
||
<li><code>524288 % part_size = 0</code> (512KB must be evenly divisible by <strong>part_size</strong>)</li>
|
||
</ul>
|
||
<p>The last part does not have to satisfy these conditions, provided its size is less than <strong>part_size</strong>.</p>
|
||
<p>Each part should have a sequence number, <strong>file_part</strong>, with a value ranging from 0 to 2,999.</p>
|
||
<p>After the file has been partitioned you need to choose a method for saving it on the server. Use <a href="/method/upload.saveBigFilePart">upload.saveBigFilePart</a> in case the full size of the file is more than <strong>10 MB</strong> and <a href="/method/upload.saveFilePart">upload.saveFilePart</a> for smaller files.</p>
|
||
<p>Each call saves a portion of the data in a temporary location on the server to be used later. The storage life of each portion of data is between several minutes and several hours (depending on how busy the storage area is). After this time, the file part will become unavailable. To increase the time efficiency of a file save operation, we recommend using a call queue, so X pieces of the file are being saved at any given moment in time. Each successful operation to save a part invokes the method call to save the next part. The value of X can be tuned to achieve maximum performance.</p>
|
||
<p>When using one of the methods mentioned above to save file parts, one of the following <a href="/api/errors#400-bad-request">data input errors</a> may be returned:</p>
|
||
<ul>
|
||
<li>FILE_PARTS_INVALID - Invalid number of parts. The value is not between <code>1..3000</code></li>
|
||
<li>FILE_PART_INVALID: The file part number is invalid. The value is not between <code>0 and 2,999</code>.</li>
|
||
<li>FILE_PART_TOO_BIG: The size limit (512 KB) for the content of the file part has been exceeded</li>
|
||
<li>FILE_PART_EMPTY: The file part sent is empty</li>
|
||
<li>FILE_PART_SIZE_INVALID - 512KB cannot be evenly divided by <strong>part_size</strong></li>
|
||
<li>FILE_PART_SIZE_CHANGED - The part size is different from the size of one of the previous parts in the same file</li>
|
||
</ul>
|
||
<p>While the parts are being uploaded, an <a href="https://en.wikipedia.org/wiki/MD5">MD5 hash</a> of the file contents can also be computed to be used later as the <strong>md5_checksum</strong> parameter in the <a href="/constructor/inputFile">inputFile</a> constructor (since it is checked only by the server, for encrypted secret chat files it must be generated from the encrypted file).
|
||
After the entire file is successfully saved, the final method may be called and passed the generated <a href="/type/InputFile">inputFile</a> object. In case the <a href="/method/upload.saveBigFilePart">upload.saveBigFilePart</a> method is used, the <a href="/constructor/inputFileBig">inputFileBig</a> constructor must be passed, in other cases use <a href="/constructor/inputFile">inputFile</a>.</p>
|
||
<ul>
|
||
<li><a href="/method/messages.sendMedia">messages.sendMedia</a> - Sends a media file to a chat</li>
|
||
<li><a href="/method/messages.uploadMedia">messages.uploadMedia</a> - Uploads a media file to a chat, without sending it, returning only a <a href="/type/MessageMedia">MessageMedia</a> constructor that can be used to later send the file to multiple chats, without reuploading it every time. </li>
|
||
<li><a href="/method/photos.uploadProfilePhoto">photos.uploadProfilePhoto</a> - Used to set a <a href="#uploading-profile-or-chat-pictures">profile or chat picture or video</a></li>
|
||
</ul>
|
||
<p>The file save operation may return one of the following <a href="/api/errors#400-bad-request">data input errors</a>:</p>
|
||
<ul>
|
||
<li>FILE_PARTS_INVALID: The number of file parts is invalid The value is not between 1 and 3,000.</li>
|
||
<li>FILE_PART_Х_MISSING: Part X (where X is a number) of the file is missing from storage. Try repeating the method call to resave the part.</li>
|
||
<li>MD5_CHECKSUM_INVALID: The file's checksum did not match the <strong>md5_checksum</strong> parameter</li>
|
||
</ul>
|
||
<h4><a class="anchor" href="#albums-grouped-media" id="albums-grouped-media" name="albums-grouped-media"><i class="anchor-icon"></i></a>Albums, grouped media</h4>
|
||
<pre><code><a href='/constructor/inputMediaUploadedPhoto'>inputMediaUploadedPhoto</a>#1e287d04 flags:<a href='/type/%23'>#</a> file:<a href='/type/InputFile'>InputFile</a> stickers:flags.0?<a href='/type/Vector%20t'>Vector</a><<a href='/type/InputDocument'>InputDocument</a>> ttl_seconds:flags.1?<a href='/type/int'>int</a> = <a href='/type/InputMedia'>InputMedia</a>;
|
||
<a href='/constructor/inputMediaUploadedDocument'>inputMediaUploadedDocument</a>#5b38c6c1 flags:<a href='/type/%23'>#</a> nosound_video:flags.3?<a href='/constructor/true'>true</a> force_file:flags.4?<a href='/constructor/true'>true</a> file:<a href='/type/InputFile'>InputFile</a> thumb:flags.2?<a href='/type/InputFile'>InputFile</a> mime_type:<a href='/type/string'>string</a> attributes:<a href='/type/Vector%20t'>Vector</a><<a href='/type/DocumentAttribute'>DocumentAttribute</a>> stickers:flags.0?<a href='/type/Vector%20t'>Vector</a><<a href='/type/InputDocument'>InputDocument</a>> ttl_seconds:flags.1?<a href='/type/int'>int</a> = <a href='/type/InputMedia'>InputMedia</a>;
|
||
|
||
<a href='/constructor/inputSingleMedia'>inputSingleMedia</a>#1cc6e91f flags:<a href='/type/%23'>#</a> media:<a href='/type/InputMedia'>InputMedia</a> random_id:<a href='/type/long'>long</a> message:<a href='/type/string'>string</a> entities:flags.0?<a href='/type/Vector%20t'>Vector</a><<a href='/type/MessageEntity'>MessageEntity</a>> = <a href='/type/InputSingleMedia'>InputSingleMedia</a>;
|
||
|
||
---functions---
|
||
|
||
<a href='/method/messages.sendMultiMedia'>messages.sendMultiMedia</a>#f803138f flags:<a href='/type/%23'>#</a> silent:flags.5?<a href='/constructor/true'>true</a> background:flags.6?<a href='/constructor/true'>true</a> clear_draft:flags.7?<a href='/constructor/true'>true</a> noforwards:flags.14?<a href='/constructor/true'>true</a> peer:<a href='/type/InputPeer'>InputPeer</a> reply_to_msg_id:flags.0?<a href='/type/int'>int</a> multi_media:<a href='/type/Vector%20t'>Vector</a><<a href='/type/InputSingleMedia'>InputSingleMedia</a>> schedule_date:flags.10?<a href='/type/int'>int</a> send_as:flags.13?<a href='/type/InputPeer'>InputPeer</a> = <a href='/type/Updates'>Updates</a>;</code></pre>
|
||
<p>Telegram allows grouping photos into <a href="https://telegram.org/blog/albums-saved-messages">albums</a> and generic files (audio, docuemnts) into media groups. </p>
|
||
<p>To do this, <a href="/method/messages.sendMultiMedia">messages.sendMultiMedia</a> is used, wrapping each <a href="/type/InputMedia">InputMedia</a> constructor (uploaded or pre-existing, maximum 10 per media group) into an <a href="/constructor/inputSingleMedia">inputSingleMedia</a> constructor, optionally providing a custom per-file caption in <code>message</code>. </p>
|
||
<p>For photo albums, clients should display an album caption only if exactly one photo in the group has a caption, otherwise no album caption should be displayed, and only when viewing in detail a specific photo of the group the caption should be shown.<br>
|
||
Other grouped media can display a caption under each file. </p>
|
||
<h4><a class="anchor" href="#re-using-pre-uploaded-files" id="re-using-pre-uploaded-files" name="re-using-pre-uploaded-files"><i class="anchor-icon"></i></a>Re-using pre-uploaded files</h4>
|
||
<pre><code><a href='/constructor/document'>document</a>#1e87342b flags:<a href='/type/%23'>#</a> id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> file_reference:<a href='/type/bytes'>bytes</a> date:<a href='/type/int'>int</a> mime_type:<a href='/type/string'>string</a> size:<a href='/type/int'>int</a> thumbs:flags.0?<a href='/type/Vector%20t'>Vector</a><<a href='/type/PhotoSize'>PhotoSize</a>> video_thumbs:flags.1?<a href='/type/Vector%20t'>Vector</a><<a href='/type/VideoSize'>VideoSize</a>> dc_id:<a href='/type/int'>int</a> attributes:<a href='/type/Vector%20t'>Vector</a><<a href='/type/DocumentAttribute'>DocumentAttribute</a>> = <a href='/type/Document'>Document</a>;
|
||
|
||
---functions---
|
||
|
||
<a href='/method/messages.getDocumentByHash'>messages.getDocumentByHash</a>#338e2464 sha256:<a href='/type/bytes'>bytes</a> size:<a href='/type/int'>int</a> mime_type:<a href='/type/string'>string</a> = <a href='/type/Document'>Document</a>;</code></pre>
|
||
<p>For some types of documents like GIFs, <a href="/method/messages.getDocumentByHash">messages.getDocumentByHash</a> can be used to search for the document on Telegram servers.
|
||
The SHA256 hash of the file is computed, and it is passed along with the file's mime type and size to the method: if the file type is correct and the file is found, a <a href="/constructor/document">document</a> is returned.</p>
|
||
<h3><a class="anchor" href="#uploading-profile-or-chat-pictures" id="uploading-profile-or-chat-pictures" name="uploading-profile-or-chat-pictures"><i class="anchor-icon"></i></a>Uploading profile or chat pictures</h3>
|
||
<pre><code><a href='/constructor/photo'>photo</a>#fb197a65 flags:<a href='/type/%23'>#</a> has_stickers:flags.0?<a href='/constructor/true'>true</a> id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> file_reference:<a href='/type/bytes'>bytes</a> date:<a href='/type/int'>int</a> sizes:<a href='/type/Vector%20t'>Vector</a><<a href='/type/PhotoSize'>PhotoSize</a>> video_sizes:flags.1?<a href='/type/Vector%20t'>Vector</a><<a href='/type/VideoSize'>VideoSize</a>> dc_id:<a href='/type/int'>int</a> = <a href='/type/Photo'>Photo</a>;
|
||
|
||
<a href='/constructor/photos.photo'>photos.photo</a>#20212ca8 photo:<a href='/type/Photo'>Photo</a> users:<a href='/type/Vector%20t'>Vector</a><<a href='/type/User'>User</a>> = <a href='/type/photos.Photo'>photos.Photo</a>;
|
||
|
||
<a href='/constructor/inputPhoto'>inputPhoto</a>#3bb3b94a id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> file_reference:<a href='/type/bytes'>bytes</a> = <a href='/type/InputPhoto'>InputPhoto</a>;
|
||
|
||
<a href='/constructor/inputFile'>inputFile</a>#f52ff27f id:<a href='/type/long'>long</a> parts:<a href='/type/int'>int</a> name:<a href='/type/string'>string</a> md5_checksum:<a href='/type/string'>string</a> = <a href='/type/InputFile'>InputFile</a>;
|
||
|
||
<a href='/constructor/inputChatUploadedPhoto'>inputChatUploadedPhoto</a>#c642724e flags:<a href='/type/%23'>#</a> file:flags.0?<a href='/type/InputFile'>InputFile</a> video:flags.1?<a href='/type/InputFile'>InputFile</a> video_start_ts:flags.2?<a href='/type/double'>double</a> = <a href='/type/InputChatPhoto'>InputChatPhoto</a>;
|
||
<a href='/constructor/inputChatPhoto'>inputChatPhoto</a>#8953ad37 id:<a href='/type/InputPhoto'>InputPhoto</a> = <a href='/type/InputChatPhoto'>InputChatPhoto</a>;
|
||
|
||
---functions---
|
||
|
||
<a href='/method/photos.updateProfilePhoto'>photos.updateProfilePhoto</a>#72d4742c id:<a href='/type/InputPhoto'>InputPhoto</a> = <a href='/type/photos.Photo'>photos.Photo</a>;
|
||
<a href='/method/photos.uploadProfilePhoto'>photos.uploadProfilePhoto</a>#89f30f69 flags:<a href='/type/%23'>#</a> file:flags.0?<a href='/type/InputFile'>InputFile</a> video:flags.1?<a href='/type/InputFile'>InputFile</a> video_start_ts:flags.2?<a href='/type/double'>double</a> = <a href='/type/photos.Photo'>photos.Photo</a>;
|
||
|
||
<a href='/method/messages.editChatPhoto'>messages.editChatPhoto</a>#35ddd674 chat_id:<a href='/type/long'>long</a> photo:<a href='/type/InputChatPhoto'>InputChatPhoto</a> = <a href='/type/Updates'>Updates</a>;
|
||
|
||
<a href='/method/channels.editPhoto'>channels.editPhoto</a>#f12e57c9 channel:<a href='/type/InputChannel'>InputChannel</a> photo:<a href='/type/InputChatPhoto'>InputChatPhoto</a> = <a href='/type/Updates'>Updates</a>;</code></pre>
|
||
<p>User profile pictures can be uploaded using the <a href="/method/photos.updateProfilePhoto">photos.uploadProfilePhoto</a> method: the actual profile picture has to be <a href="#uploading-files">uploaded as for normal files</a>.<br>
|
||
<a href="/method/photos.updateProfilePhoto">photos.uploadProfilePhoto</a> can also be used to reupload previously uploaded profile pictures. </p>
|
||
<h4><a class="anchor" href="#animated-profile-pictures" id="animated-profile-pictures" name="animated-profile-pictures"><i class="anchor-icon"></i></a>Animated profile pictures</h4>
|
||
<p>Animated profile pictures are also supported, by populating the <code>video</code> constructor: square MPEG4 videos up to <code>1080x1080</code> are supported, <code>800x800</code> is the recommended resolution.<br>
|
||
The <code>video_start_ts</code> is a floating point UNIX timestamp in seconds, indicating the frame of the video that should be used as static preview. </p>
|
||
<p><a href="/api/channel">Chat, channel and supergroup</a> profile photos and videos can be uploaded using <a href="/method/messages.editChatPhoto">messages.editChatPhoto</a> (<a href="/api/channel#basic-groups">basic groups</a>) or <a href="/method/channels.editPhoto">channels.editPhoto</a> (<a href="/api/channel">channels, supergroups</a>).<br>
|
||
Use the <a href="/constructor/inputChatPhoto">inputChatPhoto</a> to reuse previously uploaded profile pictures. </p>
|
||
<h3><a class="anchor" href="#downloading-files" id="downloading-files" name="downloading-files"><i class="anchor-icon"></i></a>Downloading files</h3>
|
||
<p>There are methods available to download files which have been successfully uploaded. The schema of the types and methods used is presented below:</p>
|
||
<pre><code><a href='/constructor/upload.file'>upload.file</a>#96a18d5 type:<a href='/type/storage.FileType'>storage.FileType</a> mtime:<a href='/type/int'>int</a> bytes:<a href='/type/bytes'>bytes</a> = <a href='/type/upload.File'>upload.File</a>;
|
||
<a href='/constructor/upload.fileCdnRedirect'>upload.fileCdnRedirect</a>#f18cda44 dc_id:<a href='/type/int'>int</a> file_token:<a href='/type/bytes'>bytes</a> encryption_key:<a href='/type/bytes'>bytes</a> encryption_iv:<a href='/type/bytes'>bytes</a> file_hashes:<a href='/type/Vector%20t'>Vector</a><<a href='/type/FileHash'>FileHash</a>> = <a href='/type/upload.File'>upload.File</a>;
|
||
|
||
<a href='/constructor/storage.fileUnknown'>storage.fileUnknown</a>#aa963b05 = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
<a href='/constructor/storage.fileJpeg'>storage.fileJpeg</a>#7efe0e = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
<a href='/constructor/storage.fileGif'>storage.fileGif</a>#cae1aadf = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
<a href='/constructor/storage.filePng'>storage.filePng</a>#a4f63c0 = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
<a href='/constructor/storage.fileMp3'>storage.fileMp3</a>#528a0677 = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
<a href='/constructor/storage.fileMov'>storage.fileMov</a>#4b09ebbc = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
<a href='/constructor/storage.filePartial'>storage.filePartial</a>#40bc6f52 = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
<a href='/constructor/storage.fileMp4'>storage.fileMp4</a>#b3cea0e4 = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
<a href='/constructor/storage.fileWebp'>storage.fileWebp</a>#1081464c = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
|
||
---functions---
|
||
|
||
<a href='/method/upload.getFile'>upload.getFile</a>#b15a9afc flags:<a href='/type/%23'>#</a> precise:flags.0?<a href='/constructor/true'>true</a> cdn_supported:flags.1?<a href='/constructor/true'>true</a> location:<a href='/type/InputFileLocation'>InputFileLocation</a> offset:<a href='/type/int'>int</a> limit:<a href='/type/int'>int</a> = <a href='/type/upload.File'>upload.File</a>;</code></pre>
|
||
<p>Any file can be downloaded by calling <a href="/method/upload.getFile">upload.getFile</a>.
|
||
The data for the input parameter of the <a href="/type/InputFileLocation">InputFileLocation</a> type is generated as follows:</p>
|
||
<pre><code><a href='/constructor/inputFileLocation'>inputFileLocation</a>#dfdaabe1 volume_id:<a href='/type/long'>long</a> local_id:<a href='/type/int'>int</a> secret:<a href='/type/long'>long</a> file_reference:<a href='/type/bytes'>bytes</a> = <a href='/type/InputFileLocation'>InputFileLocation</a>;
|
||
<a href='/constructor/inputEncryptedFileLocation'>inputEncryptedFileLocation</a>#f5235d55 id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> = <a href='/type/InputFileLocation'>InputFileLocation</a>;
|
||
<a href='/constructor/inputDocumentFileLocation'>inputDocumentFileLocation</a>#bad07584 id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> file_reference:<a href='/type/bytes'>bytes</a> thumb_size:<a href='/type/string'>string</a> = <a href='/type/InputFileLocation'>InputFileLocation</a>;
|
||
<a href='/constructor/inputSecureFileLocation'>inputSecureFileLocation</a>#cbc7ee28 id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> = <a href='/type/InputFileLocation'>InputFileLocation</a>;
|
||
<a href='/constructor/inputTakeoutFileLocation'>inputTakeoutFileLocation</a>#29be5899 = <a href='/type/InputFileLocation'>InputFileLocation</a>;
|
||
<a href='/constructor/inputPhotoFileLocation'>inputPhotoFileLocation</a>#40181ffe id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> file_reference:<a href='/type/bytes'>bytes</a> thumb_size:<a href='/type/string'>string</a> = <a href='/type/InputFileLocation'>InputFileLocation</a>;
|
||
<a href='/constructor/inputPhotoLegacyFileLocation'>inputPhotoLegacyFileLocation</a>#d83466f3 id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> file_reference:<a href='/type/bytes'>bytes</a> volume_id:<a href='/type/long'>long</a> local_id:<a href='/type/int'>int</a> secret:<a href='/type/long'>long</a> = <a href='/type/InputFileLocation'>InputFileLocation</a>;
|
||
<a href='/constructor/inputPeerPhotoFileLocation'>inputPeerPhotoFileLocation</a>#37257e99 flags:<a href='/type/%23'>#</a> big:flags.0?<a href='/constructor/true'>true</a> peer:<a href='/type/InputPeer'>InputPeer</a> photo_id:<a href='/type/long'>long</a> = <a href='/type/InputFileLocation'>InputFileLocation</a>;
|
||
<a href='/constructor/inputStickerSetThumb'>inputStickerSetThumb</a>#9d84f3db stickerset:<a href='/type/InputStickerSet'>InputStickerSet</a> thumb_version:<a href='/type/int'>int</a> = <a href='/type/InputFileLocation'>InputFileLocation</a>;
|
||
<a href='/constructor/inputGroupCallStream'>inputGroupCallStream</a>#598a92a flags:<a href='/type/%23'>#</a> call:<a href='/type/InputGroupCall'>InputGroupCall</a> time_ms:<a href='/type/long'>long</a> scale:<a href='/type/int'>int</a> video_channel:flags.0?<a href='/type/int'>int</a> video_quality:flags.0?<a href='/type/int'>int</a> = <a href='/type/InputFileLocation'>InputFileLocation</a>;
|
||
|
||
<a href='/constructor/inputStickerSetEmpty'>inputStickerSetEmpty</a>#ffb62b95 = <a href='/type/InputStickerSet'>InputStickerSet</a>;
|
||
<a href='/constructor/inputStickerSetID'>inputStickerSetID</a>#9de7a269 id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> = <a href='/type/InputStickerSet'>InputStickerSet</a>;
|
||
<a href='/constructor/inputStickerSetShortName'>inputStickerSetShortName</a>#861cc8a0 short_name:<a href='/type/string'>string</a> = <a href='/type/InputStickerSet'>InputStickerSet</a>;
|
||
<a href='/constructor/inputStickerSetAnimatedEmoji'>inputStickerSetAnimatedEmoji</a>#28703c8 = <a href='/type/InputStickerSet'>InputStickerSet</a>;
|
||
<a href='/constructor/inputStickerSetDice'>inputStickerSetDice</a>#e67f520e emoticon:<a href='/type/string'>string</a> = <a href='/type/InputStickerSet'>InputStickerSet</a>;
|
||
<a href='/constructor/inputStickerSetAnimatedEmojiAnimations'>inputStickerSetAnimatedEmojiAnimations</a>#cde3739 = <a href='/type/InputStickerSet'>InputStickerSet</a>;
|
||
|
||
<a href='/constructor/inputPeerSelf'>inputPeerSelf</a>#7da07ec9 = <a href='/type/InputPeer'>InputPeer</a>;
|
||
<a href='/constructor/inputPeerChat'>inputPeerChat</a>#35a95cb9 chat_id:<a href='/type/long'>long</a> = <a href='/type/InputPeer'>InputPeer</a>;
|
||
<a href='/constructor/inputPeerUser'>inputPeerUser</a>#dde8a54c user_id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> = <a href='/type/InputPeer'>InputPeer</a>;
|
||
<a href='/constructor/inputPeerChannel'>inputPeerChannel</a>#27bcbbfc channel_id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> = <a href='/type/InputPeer'>InputPeer</a>;
|
||
|
||
<a href='/constructor/photo'>photo</a>#fb197a65 flags:<a href='/type/%23'>#</a> has_stickers:flags.0?<a href='/constructor/true'>true</a> id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> file_reference:<a href='/type/bytes'>bytes</a> date:<a href='/type/int'>int</a> sizes:<a href='/type/Vector%20t'>Vector</a><<a href='/type/PhotoSize'>PhotoSize</a>> video_sizes:flags.1?<a href='/type/Vector%20t'>Vector</a><<a href='/type/VideoSize'>VideoSize</a>> dc_id:<a href='/type/int'>int</a> = <a href='/type/Photo'>Photo</a>;
|
||
<a href='/constructor/document'>document</a>#1e87342b flags:<a href='/type/%23'>#</a> id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> file_reference:<a href='/type/bytes'>bytes</a> date:<a href='/type/int'>int</a> mime_type:<a href='/type/string'>string</a> size:<a href='/type/int'>int</a> thumbs:flags.0?<a href='/type/Vector%20t'>Vector</a><<a href='/type/PhotoSize'>PhotoSize</a>> video_thumbs:flags.1?<a href='/type/Vector%20t'>Vector</a><<a href='/type/VideoSize'>VideoSize</a>> dc_id:<a href='/type/int'>int</a> attributes:<a href='/type/Vector%20t'>Vector</a><<a href='/type/DocumentAttribute'>DocumentAttribute</a>> = <a href='/type/Document'>Document</a>;
|
||
|
||
<a href='/constructor/photoSize'>photoSize</a>#75c78e60 type:<a href='/type/string'>string</a> w:<a href='/type/int'>int</a> h:<a href='/type/int'>int</a> size:<a href='/type/int'>int</a> = <a href='/type/PhotoSize'>PhotoSize</a>;
|
||
<a href='/constructor/photoCachedSize'>photoCachedSize</a>#21e1ad6 type:<a href='/type/string'>string</a> w:<a href='/type/int'>int</a> h:<a href='/type/int'>int</a> bytes:<a href='/type/bytes'>bytes</a> = <a href='/type/PhotoSize'>PhotoSize</a>;
|
||
|
||
<a href='/constructor/chatPhoto'>chatPhoto</a>#1c6e1c11 flags:<a href='/type/%23'>#</a> has_video:flags.0?<a href='/constructor/true'>true</a> photo_id:<a href='/type/long'>long</a> stripped_thumb:flags.1?<a href='/type/bytes'>bytes</a> dc_id:<a href='/type/int'>int</a> = <a href='/type/ChatPhoto'>ChatPhoto</a>;
|
||
<a href='/constructor/userProfilePhoto'>userProfilePhoto</a>#82d1f706 flags:<a href='/type/%23'>#</a> has_video:flags.0?<a href='/constructor/true'>true</a> photo_id:<a href='/type/long'>long</a> stripped_thumb:flags.1?<a href='/type/bytes'>bytes</a> dc_id:<a href='/type/int'>int</a> = <a href='/type/UserProfilePhoto'>UserProfilePhoto</a>;</code></pre>
|
||
<ul>
|
||
<li>
|
||
<p>For photos, <a href="/constructor/inputPhotoFileLocation">inputPhotoFileLocation</a> is used:</p>
|
||
<ul>
|
||
<li><code>id</code>, <code>file_reference</code> and <code>access_hash</code> taken from the <a href="/constructor/photo">photo</a> constructor</li>
|
||
<li><code>thumb_size</code> taken from the <code>type</code> field of the desired <a href="/type/PhotoSize">PhotoSize</a> of the <a href="/constructor/photo">photo</a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p>For profile pictures of users, channels, supergroups and groups, <a href="/constructor/inputPeerPhotoFileLocation">inputPeerPhotoFileLocation</a> has to be used:</p>
|
||
<ul>
|
||
<li><code>peer</code> is the identifier of the peer whose photo we want to download</li>
|
||
<li><code>big</code> is used to choose whether to download the full-resolution picture, or just the thumbnail</li>
|
||
<li><code>photo_id</code> is extracted from the <a href="/constructor/chatPhoto">chatPhoto</a> or <a href="/constructor/userProfilePhoto">userProfilePhoto</a> of the desired profile photo</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p>For documents, <a href="/constructor/inputDocumentFileLocation">inputDocumentFileLocation</a> is used:</p>
|
||
<ul>
|
||
<li><code>id</code>, <code>file_reference</code> and <code>access_hash</code> taken from the <a href="/constructor/document">document</a> constructor</li>
|
||
<li>If downloading the thumbnail of a document, <code>thumb_size</code> should be taken from the <code>type</code> field of the desired <a href="/type/PhotoSize">PhotoSize</a> of the <a href="/constructor/photo">photo</a>; otherwise, provide an empty string.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p>For previews of sticker sets, <a href="/constructor/inputStickerSetThumb">inputStickerSetThumb</a> is used (note: to download stickers and previews of stickers use the document method described above for documents):</p>
|
||
<ul>
|
||
<li><code>stickerset</code> is set to the <a href="/type/InputStickerSet">InputStickerSet</a> constructor generated from <a href="/constructor/stickerSet">stickerSet</a></li>
|
||
<li><code>thumb_version</code> is copied from the same field in <a href="/constructor/stickerSet">stickerSet</a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p>For encrypted secret chat and telegram passport documents, respectively <a href="/constructor/inputEncryptedFileLocation">inputEncryptedFileLocation</a> and <a href="/constructor/inputSecureFileLocation">inputSecureFileLocation</a> have to be used, with parameters extracted from <a href="/constructor/encryptedFile">encryptedFile</a> and <a href="/constructor/secureFile">secureFile</a> (<a href="/passport">passport docs</a>).</p>
|
||
</li>
|
||
<li>
|
||
<p>For livestream chunks, <a href="/constructor/inputGroupCallStream">inputGroupCallStream</a> is used:</p>
|
||
<ul>
|
||
<li><code>call</code> contains the related group call ID+access hash, taken from the <a href="/constructor/groupCall">groupCall</a> constructor.</li>
|
||
<li><code>time_ms</code> specifies the timestamp to fetch</li>
|
||
<li><code>scale</code> specifies the duration of the video segment to fetch in milliseconds, by bitshifting <code>1000</code> to the right <code>scale</code> times: <code>duration_ms := 1000 >> scale</code></li>
|
||
<li><code>video_channel</code> specifies the video channel to fetch</li>
|
||
<li><code>video_quality</code> specifies the selected video quality (0 = lowest, 1 = medium, 2 = best)</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p>For old <strong>deprecated</strong> photos, if the client has cached some old fileLocations with the <strong>deprecated</strong> <code>secret</code> identifier, <a href="/constructor/inputFileLocation">inputFileLocation</a> or <a href="/constructor/inputPhotoLegacyFileLocation">inputPhotoLegacyFileLocation</a> is used (this is mainly used for backwards compatibility with bot API file IDs, all user clients must use the modern <a href="/constructor/inputPhotoFileLocation">inputPhotoFileLocation</a> file IDs): </p>
|
||
<ul>
|
||
<li>All fields are taken from the previously cached fileLocation except for <code>file_reference</code>, <code>access_hash</code> and <code>id</code>, which are taken from the <a href="/constructor/photo">photo</a> constructor (the last two fields are used only if available, in which case <a href="/constructor/inputPhotoLegacyFileLocation">inputPhotoLegacyFileLocation</a> is used instead of <a href="/constructor/inputFileLocation">inputFileLocation</a>).</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>The size of each file in bytes is available, which makes it possible to download the file in parts using the parameters <strong>offset</strong> and <strong>limit</strong>, similar to the way files are uploaded.</p>
|
||
<p>If <strong>precise</strong> flag is not specified, then </p>
|
||
<ul>
|
||
<li>The parameter <strong>offset</strong> must be divisible by 4 KB.</li>
|
||
<li>The parameter <strong>limit</strong> must be divisible by 4 KB.</li>
|
||
<li>1048576 (1 MB) must be divisible by <strong>limit</strong>.</li>
|
||
</ul>
|
||
<p>If <strong>precise</strong> is specified, then</p>
|
||
<ul>
|
||
<li>The parameter <strong>offset</strong> must be divisible by 1 KB.</li>
|
||
<li>The parameter <strong>limit</strong> must be divisible by 1 KB.</li>
|
||
<li><strong>limit</strong> must not exceed 1048576 (1 MB).</li>
|
||
</ul>
|
||
<p>In any case the requested part should be within one 1 MB chunk from the beginning of the file, i. e.</p>
|
||
<ul>
|
||
<li><strong>offset</strong> / (1024 * 1024) == (<strong>offset</strong> + <strong>limit</strong> - 1) / (1024 * 1024).</li>
|
||
</ul>
|
||
<p>The file download operation may return a <code>FILE_REFERENCE_EXPIRED</code> error (or another error starting with <code>FILE_REFERENCE_</code>): in this case, the <code>file_reference</code> field of the input location must be <a href="/api/file_reference">refreshed</a>.
|
||
The file download operation may return an <a href="/constructor/upload.fileCdnRedirect">upload.fileCdnRedirect</a> constructor: in this case, <a href="/cdn">these</a> instructions must be followed for downloading CDN files.
|
||
The file download operation may also return one of the following <a href="/api/errors#400-bad-request">data input errors</a>:</p>
|
||
<ul>
|
||
<li>FILE_ID_INVALID: The file address is invalid</li>
|
||
<li>OFFSET_INVALID: The <strong>offset</strong> value is invalid</li>
|
||
<li>LIMIT_INVALID: The <strong>limit</strong> value is invalid</li>
|
||
<li>FILE_MIGRATE_X: The file is in the datacenter No. X</li>
|
||
</ul>
|
||
<h4><a class="anchor" href="#verifying-downloaded-chunks" id="verifying-downloaded-chunks" name="verifying-downloaded-chunks"><i class="anchor-icon"></i></a>Verifying downloaded chunks</h4>
|
||
<pre><code><a href='/constructor/fileHash'>fileHash</a>#6242c773 offset:<a href='/type/int'>int</a> limit:<a href='/type/int'>int</a> hash:<a href='/type/bytes'>bytes</a> = <a href='/type/FileHash'>FileHash</a>;
|
||
|
||
---functions---
|
||
|
||
<a href='/method/upload.getFileHashes'>upload.getFileHashes</a>#c7025931 location:<a href='/type/InputFileLocation'>InputFileLocation</a> offset:<a href='/type/int'>int</a> = <a href='/type/Vector%20t'>Vector</a><<a href='/type/FileHash'>FileHash</a>>;</code></pre>
|
||
<p>In order to confirm the integrity of the downloaded file, clients are recommended to verify hashes for each downloaded part, as for <a href="/cdn">CDN DCs</a>.
|
||
<a href="/method/upload.getFileHashes">upload.getFileHashes</a> contain <a href="/type/FileHash">FileHash</a> constructors. Each of these constructors contains the SHA-256 hash of a part of the file that starts with <code>offset</code> and takes <code>limit</code> bytes.</p>
|
||
<p>Before saving each portion of the data received from the DC into the file, the client can confirm that its hash matches the hash that was received from the master DC. If missing a hash for any file part, client developers must use the <a href="/method/upload.getFileHashes">upload.getFileHashes</a> method to obtain the missing hash.</p>
|
||
<h4><a class="anchor" href="#handling-audio-video-and-vector-previews" id="handling-audio-video-and-vector-previews" name="handling-audio-video-and-vector-previews"><i class="anchor-icon"></i></a>Handling audio, video and vector previews</h4>
|
||
<p>Schema:</p>
|
||
<pre><code><a href='/constructor/photoSizeEmpty'>photoSizeEmpty</a>#e17e23c type:<a href='/type/string'>string</a> = <a href='/type/PhotoSize'>PhotoSize</a>;
|
||
<a href='/constructor/photoSize'>photoSize</a>#75c78e60 type:<a href='/type/string'>string</a> w:<a href='/type/int'>int</a> h:<a href='/type/int'>int</a> size:<a href='/type/int'>int</a> = <a href='/type/PhotoSize'>PhotoSize</a>;
|
||
<a href='/constructor/photoCachedSize'>photoCachedSize</a>#21e1ad6 type:<a href='/type/string'>string</a> w:<a href='/type/int'>int</a> h:<a href='/type/int'>int</a> bytes:<a href='/type/bytes'>bytes</a> = <a href='/type/PhotoSize'>PhotoSize</a>;
|
||
<a href='/constructor/photoStrippedSize'>photoStrippedSize</a>#e0b0bc2e type:<a href='/type/string'>string</a> bytes:<a href='/type/bytes'>bytes</a> = <a href='/type/PhotoSize'>PhotoSize</a>;
|
||
<a href='/constructor/photoSizeProgressive'>photoSizeProgressive</a>#fa3efb95 type:<a href='/type/string'>string</a> w:<a href='/type/int'>int</a> h:<a href='/type/int'>int</a> sizes:<a href='/type/Vector%20t'>Vector</a><<a href='/type/int'>int</a>> = <a href='/type/PhotoSize'>PhotoSize</a>;
|
||
<a href='/constructor/photoPathSize'>photoPathSize</a>#d8214d41 type:<a href='/type/string'>string</a> bytes:<a href='/type/bytes'>bytes</a> = <a href='/type/PhotoSize'>PhotoSize</a>;
|
||
|
||
<a href='/constructor/videoSize'>videoSize</a>#de33b094 flags:<a href='/type/%23'>#</a> type:<a href='/type/string'>string</a> w:<a href='/type/int'>int</a> h:<a href='/type/int'>int</a> size:<a href='/type/int'>int</a> video_start_ts:flags.0?<a href='/type/double'>double</a> = <a href='/type/VideoSize'>VideoSize</a>;
|
||
|
||
<a href='/constructor/document'>document</a>#1e87342b flags:<a href='/type/%23'>#</a> id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> file_reference:<a href='/type/bytes'>bytes</a> date:<a href='/type/int'>int</a> mime_type:<a href='/type/string'>string</a> size:<a href='/type/int'>int</a> thumbs:flags.0?<a href='/type/Vector%20t'>Vector</a><<a href='/type/PhotoSize'>PhotoSize</a>> video_thumbs:flags.1?<a href='/type/Vector%20t'>Vector</a><<a href='/type/VideoSize'>VideoSize</a>> dc_id:<a href='/type/int'>int</a> attributes:<a href='/type/Vector%20t'>Vector</a><<a href='/type/DocumentAttribute'>DocumentAttribute</a>> = <a href='/type/Document'>Document</a>;
|
||
<a href='/constructor/photo'>photo</a>#fb197a65 flags:<a href='/type/%23'>#</a> has_stickers:flags.0?<a href='/constructor/true'>true</a> id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> file_reference:<a href='/type/bytes'>bytes</a> date:<a href='/type/int'>int</a> sizes:<a href='/type/Vector%20t'>Vector</a><<a href='/type/PhotoSize'>PhotoSize</a>> video_sizes:flags.1?<a href='/type/Vector%20t'>Vector</a><<a href='/type/VideoSize'>VideoSize</a>> dc_id:<a href='/type/int'>int</a> = <a href='/type/Photo'>Photo</a>;
|
||
|
||
<a href='/constructor/photo'>photo</a>#fb197a65 flags:<a href='/type/%23'>#</a> has_stickers:flags.0?<a href='/constructor/true'>true</a> id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> file_reference:<a href='/type/bytes'>bytes</a> date:<a href='/type/int'>int</a> sizes:<a href='/type/Vector%20t'>Vector</a><<a href='/type/PhotoSize'>PhotoSize</a>> video_sizes:flags.1?<a href='/type/Vector%20t'>Vector</a><<a href='/type/VideoSize'>VideoSize</a>> dc_id:<a href='/type/int'>int</a> = <a href='/type/Photo'>Photo</a>;</code></pre>
|
||
<p>Telegram attaches a vector of thumbnails with reduced resolution to all uploaded media.<br>
|
||
The server also generates a trimmed and scaled down video preview for videos, GIFs and animated profile pictures. </p>
|
||
<h4><a class="anchor" href="#image-thumbnail-types" id="image-thumbnail-types" name="image-thumbnail-types"><i class="anchor-icon"></i></a>Image thumbnail types</h4>
|
||
<p>Each photo preview has a specific <code>type</code>, indicating the resolution and image transform that was applied server-side. </p>
|
||
<table class="table">
|
||
<thead>
|
||
<tr>
|
||
<th>Type</th>
|
||
<th>Image filter</th>
|
||
<th>Size</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>s</code></td>
|
||
<td>box</td>
|
||
<td>100x100</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>m</code></td>
|
||
<td>box</td>
|
||
<td>320x320</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>x</code></td>
|
||
<td>box</td>
|
||
<td>800x800</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>y</code></td>
|
||
<td>box</td>
|
||
<td>1280x1280</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>w</code></td>
|
||
<td>box</td>
|
||
<td>2560x2560</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>a</code></td>
|
||
<td>crop</td>
|
||
<td>160x160</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>b</code></td>
|
||
<td>crop</td>
|
||
<td>320x320</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>c</code></td>
|
||
<td>crop</td>
|
||
<td>640x640</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>d</code></td>
|
||
<td>crop</td>
|
||
<td>1280x1280</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Special types:</p>
|
||
<table class="table">
|
||
<thead>
|
||
<tr>
|
||
<th>Type</th>
|
||
<th>Image filter</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>i</code></td>
|
||
<td>strip</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>j</code></td>
|
||
<td>outline</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h4><a class="anchor" href="#stripped-thumbnails" id="stripped-thumbnails" name="stripped-thumbnails"><i class="anchor-icon"></i></a>Stripped thumbnails</h4>
|
||
<pre><code><a href='/constructor/photoStrippedSize'>photoStrippedSize</a>#e0b0bc2e type:<a href='/type/string'>string</a> bytes:<a href='/type/bytes'>bytes</a> = <a href='/type/PhotoSize'>PhotoSize</a>;</code></pre>
|
||
<p>A <a href="/constructor/photoStrippedSize">photoStrippedSize</a> (with type <code>i</code>) is an extremely low-res thumbnail, embedded directly inside media location objects.<br>
|
||
It should be shown to the user in chat message previews, or while still downloading the most appropriately sized <a href="/constructor/photoSize">photoSize</a> through the media DCs as <a href="#downloading-files">described above</a>. </p>
|
||
<p>The stripped <code>bytes</code> payload should be inflated to a JPG payload as seen <a href="https://github.com/telegramdesktop/tdesktop/blob/1757dd856b84d23f83d4e562c94dde825f6eb40c/Telegram/SourceFiles/ui/image/image.cpp#L43">here »</a>.</p>
|
||
<h4><a class="anchor" href="#vector-thumbnails" id="vector-thumbnails" name="vector-thumbnails"><i class="anchor-icon"></i></a>Vector thumbnails</h4>
|
||
<pre><code><a href='/constructor/photoPathSize'>photoPathSize</a>#d8214d41 type:<a href='/type/string'>string</a> bytes:<a href='/type/bytes'>bytes</a> = <a href='/type/PhotoSize'>PhotoSize</a>;</code></pre>
|
||
<p>Messages with <a href="/animated_stickers">animated</a>, <a href="/stickers#video-stickers">video</a>, <a href="/stickers">normal</a> stickers can have a compressed svg (< 300 bytes) to show the outline of the sticker before fetching the actual sticker.
|
||
Sticker outlines will have a <code>j</code> type <a href="/constructor/photoPathSize">photoPathSize</a> thumbnail. </p>
|
||
<p>This specific vector thumbnail consists of an <a href="https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths">SVG path</a>, specially encoded to save space.<br>
|
||
This path will be the outline of the animated sticker, and should be shown to the user while downloading the actual sticker. </p>
|
||
<p>As for stripped sizes, the payload should be inflated using the following algorithm:</p>
|
||
<pre><code>encoded := photoPathSize.bytes
|
||
|
||
lookup := "AACAAAAHAAALMAAAQASTAVAAAZaacaaaahaaalmaaaqastava.az0123456789-,"
|
||
|
||
path := "M"
|
||
|
||
len := strlen(encoded)
|
||
for (i = 0; i < len; i++) {
|
||
num := ord(encoded[i])
|
||
if (num >= 128 + 64) {
|
||
path += lookup[num - 128 - 64]
|
||
} else {
|
||
if (num >= 128) {
|
||
path += ','
|
||
} else if (num >= 64) {
|
||
path += '-'
|
||
}
|
||
path += itoa(num & 63)
|
||
}
|
||
}
|
||
path += "z"</code></pre>
|
||
<p><code>path</code> will contain the actual SVG path that can be directly inserted in the <code>d</code> attribute of an <a href="https://developer.mozilla.org/en-US/docs/Web/SVG/Element/path">svg <path> element</a>: </p>
|
||
<pre><code><?xml version="1.0" encoding="utf-8"?>
|
||
<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
|
||
viewBox="0 0 512 512" xml:space="preserve">
|
||
<path d="{$path}"/>
|
||
</svg></code></pre>
|
||
<h4><a class="anchor" href="#video-types" id="video-types" name="video-types"><i class="anchor-icon"></i></a>Video types</h4>
|
||
<pre><code><a href='/constructor/videoSize'>videoSize</a>#de33b094 flags:<a href='/type/%23'>#</a> type:<a href='/type/string'>string</a> w:<a href='/type/int'>int</a> h:<a href='/type/int'>int</a> size:<a href='/type/int'>int</a> video_start_ts:flags.0?<a href='/type/double'>double</a> = <a href='/type/VideoSize'>VideoSize</a>;</code></pre>
|
||
<p>A <a href="/constructor/videoSize">videoSize</a> constructor is typically used for <a href="#animated-profile-pictures">animated profile pictures</a> and video previews.</p>
|
||
<table class="table">
|
||
<thead>
|
||
<tr>
|
||
<th>Type</th>
|
||
<th>Description</th>
|
||
<th>Format</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>u</code></td>
|
||
<td>Animated profile picture</td>
|
||
<td>MPEG4</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>v</code></td>
|
||
<td>Video preview</td>
|
||
<td>MPEG4</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h3><a class="anchor" href="#downloading-webfiles" id="downloading-webfiles" name="downloading-webfiles"><i class="anchor-icon"></i></a>Downloading webfiles</h3>
|
||
<p>Remote HTTP files sent by inline bots <a href="/type/BotInlineResult">in response to inline queries</a> and in other places are represented by <a href="/type/WebDocument">WebDocument</a> constructors.
|
||
When forwarding such remote HTTP files, they should be sent using <a href="/type/InputMedia">external InputMedia constructors</a>.
|
||
Remote HTTP files can only be downloaded directly by the client if contained in a <a href="/constructor/webDocumentNoProxy">webDocumentNoProxy</a> constructor: in this case, the file is deemed safe to download (this is the case for HTTPS files from certain trusted domains).</p>
|
||
<p>However, if the remote file is contained in a <a href="/constructor/webDocument">webDocument</a>, to avoid leaking sensitive information the file must be downloaded through telegram's servers.
|
||
This can be done in a manner similar to <a href="#downloading-files">normal files</a>, with the difference that <a href="/method/upload.getWebFile">upload.getWebFile</a> must be used, instead.</p>
|
||
<pre><code><a href='/constructor/upload.webFile'>upload.webFile</a>#21e753bc size:<a href='/type/int'>int</a> mime_type:<a href='/type/string'>string</a> file_type:<a href='/type/storage.FileType'>storage.FileType</a> mtime:<a href='/type/int'>int</a> bytes:<a href='/type/bytes'>bytes</a> = <a href='/type/upload.WebFile'>upload.WebFile</a>;
|
||
|
||
<a href='/constructor/storage.fileUnknown'>storage.fileUnknown</a>#aa963b05 = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
<a href='/constructor/storage.fileJpeg'>storage.fileJpeg</a>#7efe0e = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
<a href='/constructor/storage.fileGif'>storage.fileGif</a>#cae1aadf = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
<a href='/constructor/storage.filePng'>storage.filePng</a>#a4f63c0 = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
<a href='/constructor/storage.fileMp3'>storage.fileMp3</a>#528a0677 = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
<a href='/constructor/storage.fileMov'>storage.fileMov</a>#4b09ebbc = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
<a href='/constructor/storage.filePartial'>storage.filePartial</a>#40bc6f52 = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
<a href='/constructor/storage.fileMp4'>storage.fileMp4</a>#b3cea0e4 = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
<a href='/constructor/storage.fileWebp'>storage.fileWebp</a>#1081464c = <a href='/type/storage.FileType'>storage.FileType</a>;
|
||
|
||
---functions---
|
||
|
||
<a href='/method/upload.getWebFile'>upload.getWebFile</a>#24e6818d location:<a href='/type/InputWebFileLocation'>InputWebFileLocation</a> offset:<a href='/type/int'>int</a> limit:<a href='/type/int'>int</a> = <a href='/type/upload.WebFile'>upload.WebFile</a>;</code></pre>
|
||
<p>The <a href="/type/InputWebFileLocation">InputWebFileLocation</a> constructor is generated as follows.</p>
|
||
<pre><code><a href='/constructor/inputWebFileLocation'>inputWebFileLocation</a>#c239d686 url:<a href='/type/string'>string</a> access_hash:<a href='/type/long'>long</a> = <a href='/type/InputWebFileLocation'>InputWebFileLocation</a>;
|
||
<a href='/constructor/inputWebFileGeoPointLocation'>inputWebFileGeoPointLocation</a>#9f2221c9 geo_point:<a href='/type/InputGeoPoint'>InputGeoPoint</a> access_hash:<a href='/type/long'>long</a> w:<a href='/type/int'>int</a> h:<a href='/type/int'>int</a> zoom:<a href='/type/int'>int</a> scale:<a href='/type/int'>int</a> = <a href='/type/InputWebFileLocation'>InputWebFileLocation</a>;
|
||
|
||
<a href='/constructor/webDocument'>webDocument</a>#1c570ed1 url:<a href='/type/string'>string</a> access_hash:<a href='/type/long'>long</a> size:<a href='/type/int'>int</a> mime_type:<a href='/type/string'>string</a> attributes:<a href='/type/Vector%20t'>Vector</a><<a href='/type/DocumentAttribute'>DocumentAttribute</a>> = <a href='/type/WebDocument'>WebDocument</a>;
|
||
|
||
<a href='/constructor/inputGeoPoint'>inputGeoPoint</a>#48222faf flags:<a href='/type/%23'>#</a> lat:<a href='/type/double'>double</a> long:<a href='/type/double'>double</a> accuracy_radius:flags.0?<a href='/type/int'>int</a> = <a href='/type/InputGeoPoint'>InputGeoPoint</a>;
|
||
|
||
<a href='/constructor/geoPoint'>geoPoint</a>#b2a2f663 flags:<a href='/type/%23'>#</a> long:<a href='/type/double'>double</a> lat:<a href='/type/double'>double</a> access_hash:<a href='/type/long'>long</a> accuracy_radius:flags.0?<a href='/type/int'>int</a> = <a href='/type/GeoPoint'>GeoPoint</a>;</code></pre>
|
||
<ul>
|
||
<li><a href="/constructor/inputWebFileLocation">inputWebFileLocation</a> is simply generated by taking the <code>url</code> and <code>access_hash</code> fields of the <a href="/constructor/webDocument">webDocument</a> constructor.</li>
|
||
<li><a href="/constructor/inputWebFileGeoPointLocation">inputWebFileGeoPointLocation</a> is used to download a server-generated image with the map preview from a <a href="/constructor/geoPoint">geoPoint</a>.<ul>
|
||
<li><code>geo_point</code> is generated from the <code>lat</code>, <code>long</code> <code>accuracy_radius</code> parameters of the <a href="/constructor/geoPoint">geoPoint</a></li>
|
||
<li><code>access_hash</code> is the access hash of the <a href="/constructor/geoPoint">geoPoint</a></li>
|
||
<li><code>w</code> - Map width in pixels before applying scale; 16-1024</li>
|
||
<li><code>h</code> - Map height in pixels before applying scale; 16-1024</li>
|
||
<li><code>zoom</code> - Map zoom level; 13-20</li>
|
||
<li><code>scale</code> - Map scale; 1-3</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3><a class="anchor" href="#general-considerations" id="general-considerations" name="general-considerations"><i class="anchor-icon"></i></a>General Considerations</h3>
|
||
<p>It is recommended that large queries (<a href="/method/upload.getFile">upload.getFile</a>, <a href="/method/upload.saveFilePart">upload.saveFilePart</a>, <a href="/method/upload.getWebFile">upload.getWebFile</a>) be handled through a separate session and a separate connection, in which no methods other than these should be executed. If this is done, then data transfer will cause less interference with <a href="/api/updates">getting updates</a> and other method calls.</p>
|
||
<h3><a class="anchor" href="#related-articles" id="related-articles" name="related-articles"><i class="anchor-icon"></i></a>Related articles</h3>
|
||
<h4><a class="anchor" href="#handling-file-references" id="handling-file-references" name="handling-file-references"><i class="anchor-icon"></i></a><a href="/api/file_reference">Handling file references</a></h4>
|
||
<p>How to handle file references.</p></div>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="footer_wrap">
|
||
<div class="footer_columns_wrap footer_desktop">
|
||
<div class="footer_column footer_column_telegram">
|
||
<h5>Telegram</h5>
|
||
<div class="footer_telegram_description"></div>
|
||
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
|
||
</div>
|
||
|
||
<div class="footer_column">
|
||
<h5><a href="//telegram.org/faq">About</a></h5>
|
||
<ul>
|
||
<li><a href="//telegram.org/faq">FAQ</a></li>
|
||
<li><a href="//telegram.org/blog">Blog</a></li>
|
||
<li><a href="//telegram.org/jobs">Jobs</a></li>
|
||
</ul>
|
||
</div>
|
||
<div class="footer_column">
|
||
<h5><a href="//telegram.org/apps#mobile-apps">Mobile Apps</a></h5>
|
||
<ul>
|
||
<li><a href="//telegram.org/dl/ios">iPhone/iPad</a></li>
|
||
<li><a href="//telegram.org/dl/android">Android</a></li>
|
||
<li><a href="//telegram.org/dl/wp">Windows Phone</a></li>
|
||
</ul>
|
||
</div>
|
||
<div class="footer_column">
|
||
<h5><a href="//telegram.org/apps#desktop-apps">Desktop Apps</a></h5>
|
||
<ul>
|
||
<li><a href="//desktop.telegram.org/">PC/Mac/Linux</a></li>
|
||
<li><a href="//macos.telegram.org/">macOS</a></li>
|
||
<li><a href="//telegram.org/dl/web">Web-browser</a></li>
|
||
</ul>
|
||
</div>
|
||
<div class="footer_column footer_column_platform">
|
||
<h5><a href="//core.telegram.org/">Platform</a></h5>
|
||
<ul>
|
||
<li><a href="//core.telegram.org/api">API</a></li>
|
||
<li><a href="//translations.telegram.org/">Translations</a></li>
|
||
<li><a href="//instantview.telegram.org/">Instant View</a></li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div class="footer_columns_wrap footer_mobile">
|
||
<div class="footer_column">
|
||
<h5><a href="//telegram.org/faq">About</a></h5>
|
||
</div>
|
||
<div class="footer_column">
|
||
<h5><a href="//telegram.org/blog">Blog</a></h5>
|
||
</div>
|
||
<div class="footer_column">
|
||
<h5><a href="//telegram.org/apps">Apps</a></h5>
|
||
</div>
|
||
<div class="footer_column">
|
||
<h5><a href="//core.telegram.org/">Platform</a></h5>
|
||
</div>
|
||
<div class="footer_column">
|
||
<h5><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)">Twitter</a></h5>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<script src="/js/main.js?46"></script>
|
||
<script src="/js/jquery.min.js?1"></script>
|
||
<script src="/js/bootstrap.min.js?1"></script>
|
||
|
||
<script>window.initDevPageNav&&initDevPageNav();
|
||
backToTopInit("Go up");
|
||
removePreloadInit();
|
||
</script>
|
||
</body>
|
||
</html>
|
||
|