Telethon中SendMultiMediaRequest发送多文件失败及报错排查

尝试使用Telethon库的SendMultiMediaRequest函数发送包含多张图片和文本的Telegram消息，但消息未发送，报错：❌ Unexpected error occurred: Media invalid (caused by SendMultiMediaRequest)。简化后的代码如下：

# Cast to ensure proper data types for channel ID and access hash
channel = InputPeerChannel(channel_id=int(channel_id), access_hash=int(access_hash))

media_group = []
# 'test.png', 'test2.png' are random and different png images
for i, path in enumerate(['test.png', 'test2.png']):
    
    # Upload each image to Telegram
    uploaded_photo = await client.upload_file(path)
    if not uploaded_photo:
        raise RuntimeError(f"Failed to upload file: {path}")

    # Define the input media for each photo
    media = InputMediaUploadedPhoto(file=uploaded_photo)

    # Append the image to the media group
    media_group.append(InputSingleMedia(
        media=media,
        message=text_message if i == 0 else "",  # Text only for the first image
        random_id=random.getrandbits(63)  # Random ID for each media
    ))

# Calculate the schedule time
schedule_time = datetime.now() + timedelta(minutes=60)

# Send the post as a message
await client(SendMultiMediaRequest(
    peer=channel,
    multi_media=media_group,
    schedule_date=schedule_time
))

咨询问题：

1. 是否正确使用了SendMultiMediaRequest？
2. 如何正确发送多个媒体文件并附带文本说明？

1. 当前SendMultiMediaRequest的使用存在错误 #

核心问题有两个：

• InputSingleMedia的message字段设置错误：媒体组消息中，仅第一个InputSingleMedia可携带文本，后续条目必须设为None而非空字符串""。Telegram API会将空字符串判定为无效内容，触发媒体错误。
• random_id不统一：同属一个媒体组的所有InputSingleMedia必须使用相同的random_id，这是Telegram识别媒体组的关键标识。每个条目单独生成随机ID会被视为独立消息，导致报错。

2. 正确的多媒体+文本发送方式 #

方式一：修正底层SendMultiMediaRequest的使用 #

修改后的代码如下：

# Cast to ensure proper data types for channel ID and access hash
channel = InputPeerChannel(channel_id=int(channel_id), access_hash=int(access_hash))

media_group = []
# 生成媒体组共用的随机ID
group_random_id = random.getrandbits(63)
# 'test.png', 'test2.png' are random and different png images
for i, path in enumerate(['test.png', 'test2.png']):
    
    # Upload each image to Telegram
    uploaded_photo = await client.upload_file(path)
    if not uploaded_photo:
        raise RuntimeError(f"Failed to upload file: {path}")

    # Define the input media for each photo
    media = InputMediaUploadedPhoto(file=uploaded_photo)

    # Append the image to the media group
    media_group.append(InputSingleMedia(
        media=media,
        message=text_message if i == 0 else None,  # 仅第一个条目带文本，后续设为None
        random_id=group_random_id  # 整个媒体组使用同一个随机ID
    ))

# Calculate the schedule time
schedule_time = datetime.now() + timedelta(minutes=60)

# Send the post as a message
await client(SendMultiMediaRequest(
    peer=channel,
    multi_media=media_group,
    schedule_date=schedule_time
))

方式二：使用Telethon高层API（推荐） #

Telethon提供了更简洁的client.send_file接口，自动处理媒体上传、组标识、文本附加等细节，无需手动调用底层请求：

# Cast to ensure proper data types for channel ID and access hash
channel = InputPeerChannel(channel_id=int(channel_id), access_hash=int(access_hash))

# 准备媒体文件列表，支持本地路径或已上传的文件对象
media_files = ['test.png', 'test2.png']
# 计算定时发送时间
schedule_time = datetime.now() + timedelta(minutes=60)

# 发送媒体组，文本自动附加到第一个媒体上
await client.send_file(
    entity=channel,
    file=media_files,
    caption=text_message,
    schedule=schedule_time
)

内容的提问来源于stack exchange，提问作者Vadim Kovach