Media group builder

This module provides a builder for media groups, it can be used to build media groups for aiogram.types.input_media_photo.InputMediaPhoto, aiogram.types.input_media_video.InputMediaVideo, aiogram.types.input_media_document.InputMediaDocument and aiogram.types.input_media_audio.InputMediaAudio.

Warning

aiogram.types.input_media_animation.InputMediaAnimation is not supported yet in the Bot API to send as media group.

Usage

media_group = MediaGroupBuilder(caption="Media group caption")

# Add photo
media_group.add_photo(media="https://picsum.photos/200/300")
# Dynamically add photo with known type without using separate method
media_group.add(type="photo", media="https://picsum.photos/200/300")
# ... or video
media_group.add(type="video", media=FSInputFile("media/video.mp4"))

To send media group use aiogram.methods.send_media_group.SendMediaGroup() method, but when you use aiogram.utils.media_group.MediaGroupBuilder you should pass media argument as media_group.build().

If you specify caption in aiogram.utils.media_group.MediaGroupBuilder it will be used as caption for first media in group.

await bot.send_media_group(chat_id=chat_id, media=media_group.build())

References

class aiogram.utils.media_group.MediaGroupBuilder(media: List[InputMediaAudio | InputMediaPhoto | InputMediaVideo | InputMediaDocument] | None = None, caption: str | None = None, caption_entities: List[MessageEntity] | None = None)[source]
add(*, type: Literal[InputMediaType.AUDIO], media: str | InputFile, caption: str | None = None, parse_mode: str | None = UNSET_PARSE_MODE, caption_entities: List[MessageEntity] | None = None, duration: int | None = None, performer: str | None = None, title: str | None = None, **kwargs: Any) None[source]
add(*, type: Literal[InputMediaType.PHOTO], media: str | InputFile, caption: str | None = None, parse_mode: str | None = UNSET_PARSE_MODE, caption_entities: List[MessageEntity] | None = None, has_spoiler: bool | None = None, **kwargs: Any) None
add(*, type: Literal[InputMediaType.VIDEO], media: str | InputFile, thumbnail: InputFile | str | None = None, caption: str | None = None, parse_mode: str | None = UNSET_PARSE_MODE, caption_entities: List[MessageEntity] | None = None, width: int | None = None, height: int | None = None, duration: int | None = None, supports_streaming: bool | None = None, has_spoiler: bool | None = None, **kwargs: Any) None
add(*, type: Literal[InputMediaType.DOCUMENT], media: str | InputFile, thumbnail: InputFile | str | None = None, caption: str | None = None, parse_mode: str | None = UNSET_PARSE_MODE, caption_entities: List[MessageEntity] | None = None, disable_content_type_detection: bool | None = None, **kwargs: Any) None

Add a media object to the media group.

Parameters:

kwargs – Keyword arguments for the media object. The available keyword arguments depend on the media type.

Returns:

None

add_audio(media: str | ~aiogram.types.input_file.InputFile, thumbnail: ~aiogram.types.input_file.InputFile | None = None, caption: str | None = None, parse_mode: str | None = <Default('parse_mode')>, caption_entities: ~typing.List[~aiogram.types.message_entity.MessageEntity] | None = None, duration: int | None = None, performer: str | None = None, title: str | None = None, **kwargs: ~typing.Any) None[source]

Add an audio file to the media group.

Parameters:
  • media

    File to send. Pass a file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass ‘attach://<file_attach_name>’ to upload a new one using multipart/form-data under <file_attach_name> name.

  • thumbnailOptional. Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail’s width and height should not exceed 320.

  • captionOptional. Caption of the audio to be sent, 0-1024 characters after entities parsing

  • parse_modeOptional. Mode for parsing entities in the audio caption. See formatting options for more details.

  • caption_entitiesOptional. List of special entities that appear in the caption, which can be specified instead of parse_mode

  • durationOptional. Duration of the audio in seconds

  • performerOptional. Performer of the audio

  • titleOptional. Title of the audio

Returns:

None

add_document(media: str | ~aiogram.types.input_file.InputFile, thumbnail: ~aiogram.types.input_file.InputFile | None = None, caption: str | None = None, parse_mode: str | None = <Default('parse_mode')>, caption_entities: ~typing.List[~aiogram.types.message_entity.MessageEntity] | None = None, disable_content_type_detection: bool | None = None, **kwargs: ~typing.Any) None[source]

Add a document to the media group.

Parameters:
  • media – File to send. Pass a file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass ‘attach://<file_attach_name>’ to upload a new one using multipart/form-data under <file_attach_name> name. More information on Sending Files »

  • thumbnailOptional. Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail’s width and height should not exceed 320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can’t be reused and can be only uploaded as a new file, so you can pass ‘attach://<file_attach_name>’ if the thumbnail was uploaded using multipart/form-data under <file_attach_name>. More information on Sending Files »

  • captionOptional. Caption of the document to be sent, 0-1024 characters after entities parsing

  • parse_mode

    Optional. Mode for parsing entities in the document caption. See formatting options for more details.

  • caption_entitiesOptional. List of special entities that appear in the caption, which can be specified instead of parse_mode

  • disable_content_type_detectionOptional. Disables automatic server-side content type detection for files uploaded using multipart/form-data. Always True, if the document is sent as part of an album.

Returns:

None

add_photo(media: str | ~aiogram.types.input_file.InputFile, caption: str | None = None, parse_mode: str | None = <Default('parse_mode')>, caption_entities: ~typing.List[~aiogram.types.message_entity.MessageEntity] | None = None, has_spoiler: bool | None = None, **kwargs: ~typing.Any) None[source]

Add a photo to the media group.

Parameters:
  • media

    File to send. Pass a file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass ‘attach://<file_attach_name>’ to upload a new one using multipart/form-data under <file_attach_name> name.

  • captionOptional. Caption of the photo to be sent, 0-1024 characters after entities parsing

  • parse_mode

    Optional. Mode for parsing entities in the photo caption. See formatting options for more details.

  • caption_entitiesOptional. List of special entities that appear in the caption, which can be specified instead of parse_mode

  • has_spoilerOptional. Pass True if the photo needs to be covered with a spoiler animation

Returns:

None

add_video(media: str | ~aiogram.types.input_file.InputFile, thumbnail: ~aiogram.types.input_file.InputFile | None = None, caption: str | None = None, parse_mode: str | None = <Default('parse_mode')>, caption_entities: ~typing.List[~aiogram.types.message_entity.MessageEntity] | None = None, width: int | None = None, height: int | None = None, duration: int | None = None, supports_streaming: bool | None = None, has_spoiler: bool | None = None, **kwargs: ~typing.Any) None[source]

Add a video to the media group.

Parameters:
  • media – File to send. Pass a file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass ‘attach://<file_attach_name>’ to upload a new one using multipart/form-data under <file_attach_name> name. More information on Sending Files »

  • thumbnailOptional. Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail’s width and height should not exceed 320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can’t be reused and can be only uploaded as a new file, so you can pass ‘attach://<file_attach_name>’ if the thumbnail was uploaded using multipart/form-data under <file_attach_name>. More information on Sending Files »

  • captionOptional. Caption of the video to be sent, 0-1024 characters after entities parsing

  • parse_mode

    Optional. Mode for parsing entities in the video caption. See formatting options for more details.

  • caption_entitiesOptional. List of special entities that appear in the caption, which can be specified instead of parse_mode

  • widthOptional. Video width

  • heightOptional. Video height

  • durationOptional. Video duration in seconds

  • supports_streamingOptional. Pass True if the uploaded video is suitable for streaming

  • has_spoilerOptional. Pass True if the video needs to be covered with a spoiler animation

Returns:

None

build() List[InputMediaAudio | InputMediaPhoto | InputMediaVideo | InputMediaDocument][source]

Builds a list of media objects for a media group.

Adds the caption to the first media object if it is present.

Returns:

List of media objects.