Downloading and Uploading Files

Uploads are sent as numbered parts using a client-generated upload ID. Once a file is accepted by the server, it receives a permanent file ID that can be used to download it later.

File types

Several protocol types are involved in transferring files:

media.File is the server-side record for a stored file. It contains the permanent fileId, region, size, MIME type, filename, and optional metadata.
media.UploadedFileRef describes a file that has been uploaded by the client but has not yet been turned into a permanent File record.
media.FileRef identifies an existing stored file for downloading.
media.MediaRef references media attached to other objects, such as messages or community avatars.

Uploading files

1. Create an upload ID

The client generates a unique 64-bit uploadId. This ID is temporary. It identifies the upload while its parts are being transferred and is not the permanent ID of the stored file.

2. Upload the file parts

Split the file into parts and send one media.uploadFilePart message for each part:

Field	Meaning
`uploadId`	The client-owned ID for this upload
`part`	Zero-based part number
`data`	The raw bytes for this part

Parts can be uploaded in parallel. Part numbers determine their position in the final file.

All parts except the final part must have the same size. Osmium clients commonly use 5 MiB parts.

Each part is acknowledged by the server. If a part fails, it can be uploaded again using the same uploadId and part number.

3. Create an `UploadedFileRef`

After all parts have been uploaded successfully, create an media.UploadedFileRef:

Field	Meaning
`id`	The `uploadId` used for the upload
`name`	The original filename
`partCount`	The total number of uploaded parts

There is no separate finalize request. The UploadedFileRef is passed to the protocol operation that needs the file. That operation causes the server to validate the uploaded parts and create the permanent media.File record.

At this point, the server assigns the file its permanent fileId.

4. Attach the file to media

The UploadedFileRef is used to construct the uploaded variant of media.MediaRef, together with the file’s MIME type, filename, and optional media.FileMetadata. The operation that consumes this media returns or stores the resulting media.File and its permanent fileId.

For example, a file can be attached to a message or used as a community avatar.

The important distinction is that UploadedFileRef.id is the client’s upload ID, while File.fileId is the server’s permanent file ID.

Downloading a file

Once a file has been stored, it can be downloaded using media.DownloadFilePart.

Downloads are range-based: each request specifies the byte offset and number of bytes to retrieve. The server returns those bytes in a media.FilePart.

DownloadFilePart {
  fileRef: FileRef { mediaFile: { fileId: ... } }
  offset: 0
  length: 1048576
}

FilePart {
  data: <bytes for offset through offset + length>
}

The request contains:

Field	Meaning
`fileRef`	Identifies the stored file to download
`offset`	Starting byte, measured from the beginning of the file
`length`	Maximum number of bytes to return

The response contains the requested bytes.

Downloading the complete file

To download the entire file, issue requests covering the file from byte 0 through its total size.

For example, a 10 MiB file could be downloaded as:

offset=0        length=1 MiB
offset=1 MiB    length=1 MiB
offset=2 MiB    length=1 MiB
...
offset=9 MiB    length=1 MiB

The final request may contain fewer bytes than the usual request size.

Partial downloads

The same mechanism can be used to:

Resume an interrupted download
Download only a portion of a file (streaming)
Fetch a preview without downloading the entire file

The server always returns whatever bytes are available, even when length extends beyond the end of the file.

For files such as avatars, where no part count is provided, clients can default to a 1 MiB request size.

File metadata

media.FileMetadata describes how a file should be presented to the recipient.

If no media-specific metadata is provided, the file is presented as a generic downloadable object, similar to MetadataFile.

Variant	Fields	Meaning
`image`	`width`, `height`, optional `preview`, `animated`	Image dimensions, preview data, and animation state
`video`	`width`, `height`, `duration`	Video dimensions and duration in seconds
`audio`	`duration`	Audio duration in seconds
`file`	None	Generic file with no media-specific metadata
`customEmoji`	`width`, `height`, `emoji`, `pack`, `animated`	Custom emoji presentation data

Protocol types

Upload

media.UploadFilePart — uploads one numbered part.
media.UploadedFileRef — references the uploaded parts when attaching the file.

Stored files

media.File — the server’s permanent record of a stored file.
media.FileRef — identifies a stored file for downloading.

Download

media.DownloadFilePart — requests a byte range.
media.FilePart — contains the returned bytes.

Media

media.MediaRef — attaches a file or other media to a protocol object.
media.FileMetadata — describes how the file should be presented.