Telegram Bot创建贴纸包的API调用步骤详解：从上传文件到发布全流程

Telegram 作为主打隐私与速度的即时通讯工具，其开放的 Bot API 为开发者提供了强大的扩展能力。其中，创建自定义贴纸包是很多社群运营者与开发者的刚需——无论是品牌吉祥物、表情包还是特色素材，通过 Bot 上传并发布贴纸包，能够显著增强聊天趣味性与品牌识别度。本文将基于官方 Bot API，完整演示创建贴纸包的调用步骤，从准备素材到最终发布，并附上 Python 代码示例与常见问题排查，帮助你少走弯路。

一、创建贴纸包的核心概念与前置准备

在调用 API 之前，你需要理解几个关键概念：

贴纸包（Sticker Set）：由一系列贴纸组成的集合，每个贴纸包都有一个唯一的名称（由 Bot 提供，格式通常为 name_by_username）。贴纸包分为普通贴纸和动画贴纸，本文以静态贴纸为例。
贴纸文件：必须是 PNG 或 WEBP 格式，尺寸建议 512×512 像素，最大不超过 512KB（动画贴纸要求另计）。
Bot Token：通过 @BotFather 创建机器人后获得的密钥，是所有 API 调用的凭证。

前置准备：

安装 Python 3.6+ 环境，并安装 requests 库（pip install requests）。
准备一组符合格式要求的贴纸图片，建议用 Photoshop 或在线工具统一处理为 512×512 的 PNG。
确保你的 Bot 已通过 BotFather 设置好 inline 相关权限（创建贴纸包不需额外权限，但建议开启 Inline Mode 以便后续使用）。

二、第一步：创建贴纸包（createNewStickerSet）

贴纸包必须通过 createNewStickerSet 方法创建。该接口要求 Bot 必须由用户通过 @BotFather 发送 /newstickerset 命令并完成初始化，且创建时用户需要向 Bot 发送一个 emoji 来关联贴纸。实际上，API 只要求一个有效的 user_id（通常是创建者的 Telegram 用户 ID），而 emoji 是必填字段。

请求格式：POST https://api.telegram.org/bot<token>/createNewStickerSet

参数：

user_id（Integer）：创建贴纸包的 Telegram 用户 ID。
name（String）：贴纸包名称，必须由字母、数字和下划线组成，且以 _by_ 加 Bot 用户名结尾，例如 my_awesome_stickers_by_MyStickerBot。
title（String）：贴纸包显示标题，例如“我的精选贴纸”。
sticker（InputSticker）：包含 sticker（文件或 file_id）、emoji_list（一个或多个 emoji）、mask_position（可选）等字段。注意新 API 要求使用 sticker 参数而不是旧的 png_sticker，且必须提供 sticker_format（可以是 static、animated 或 video）。

Python 实现示例（使用 multipart/form-data 上传文件）：

import requests

TOKEN = "你的 Bot Token"
CHAT_ID = "你的用户ID"
API_URL = f"https://api.telegram.org/bot/"

# 准备贴纸文件路径和 emoji
sticker_file = open("sticker.png", "rb")
emoji = "😀"

params = {
    "user_id": CHAT_ID,
    "name": "my_stickers_by_YourBotUsername",
    "title": "我的贴纸包",
    "sticker_format": "static"
}
files = {
    "sticker": sticker_file
}
data = {
    "emoji_list": emoji
}

response = requests.post(API_URL + "createNewStickerSet", data=params, files=files, data=data)
print(response.json())

注意：新版 API 中，emoji_list 必须作为 JSON 字符串传递（例如 ["😀"]），而不是直接传字符串。同时，如果使用 requests，需要将 emoji_list 通过 json 参数传入。我们稍后在完整示例中会处理。

三、第二步：上传贴纸文件与获取 file_id

创建贴纸包时，可以直接将图片文件作为 multipart 上传，也可以先通过 getFile 或上传文件的 sendSticker 等方法获得 file_id，然后使用 file_id 添加更多贴纸。推荐先上传一次并获得 file_id，因为后续 addStickerToSet 只能使用 file_id。

上传文件的方法：调用 sendSticker 或 uploadStickerFile（注意 uploadStickerFile 只接受 PNG/WEBP，且需要提供 sticker_format 参数）。这里以 uploadStickerFile 为例：

# 上传贴纸文件并获得 file_id
params = {
    "user_id": CHAT_ID,
    "sticker_format": "static"
}
files = {
    "sticker_file": open("sticker2.png", "rb")
}
resp = requests.post(API_URL + "uploadStickerFile", data=params, files=files)
file_id = resp.json()["result"]["file_id"]
print("file_id:", file_id)

注意：如果上传成功，返回的 file_id 可以用于 addStickerToSet，且有一定的有效期（通常 24 小时，但通过 sendSticker 等得到的 file_id 是永久的，推荐用 sendSticker 发送给自己或一个测试群组来获取永久 file_id）。

四、第三步：添加更多贴纸到已有贴纸包（addStickerToSet）

如果你需要为贴纸包增加更多贴纸，可以使用 addStickerToSet 方法。该接口允许你通过 file_id 添加新贴纸，并指定 emoji。

请求参数：

user_id：贴纸包创建者的用户 ID。
name：贴纸包名称。
sticker：包含 file_id 和 emoji 的 JSON 对象，同时需要带有 format 字段（新 API 中是 format 还是 sticker_format？注意，addStickerToSet 的 sticker 参数同样要求提供 format 字段，但官方文档中使用的是 format，而 createNewStickerSet 中则是 sticker_format 作为顶层参数。请以官方最新文档为准。为了稳妥，我们在添加时也提供 format。

sticker_data = {
    "file_id": file_id,
    "emoji_list": "["🎉"]",
    "format": "static"
}
params = {
    "user_id": CHAT_ID,
    "name": "my_stickers_by_YourBotUsername",
    "sticker": json.dumps(sticker_data)
}
resp = requests.post(API_URL + "addStickerToSet", data=params)
print(resp.json())

注意：emoji_list 必须是 JSON 数组字符串，否则会报错。

五、第四步：设置贴纸包为官方预览（setStickerSetThumb）与发布

创建贴纸包后，默认只有创建者可以通过 Bot 直接发送贴纸包中的贴纸（使用 sendSticker 并指定 sticker 的 file_id）。要让其他用户使用，需要将贴纸包设为“公共”状态吗？实际上，贴纸包没有公开/私有之分，任何用户都可以通过搜索贴纸包名称（如 @MyStickerPack）来添加。但为了让贴纸包在聊天中能正常显示，最好设置一个“封面”（缩略图），可以使用 setStickerSetThumb 方法。

参数：user_id、name、thumb（上传的图片文件或 file_id）。注意该方法目前只支持静态图片。

thumb_file = open("thumb.png", "rb")
params = {
    "user_id": CHAT_ID,
    "name": "my_stickers_by_YourBotUsername",
    "thumb": thumb_file
}
resp = requests.post(API_URL + "setStickerSetThumb", data=params, files={"thumb": thumb_file})
print(resp.json())

设置好封面后，你的贴纸包基本完成。用户只需在 Telegram 中搜索你的贴纸包名称（去掉 _by_ 后缀，例如搜索“my_stickers”），即可看到并添加。

六、贴纸包发布后的管理与维护

发布后，你还可以通过以下 API 管理贴纸包：

getStickerSet：获取贴纸包详细信息，包括贴纸列表、标题、封面等。
deleteStickerFromSet：从贴纸包中删除单个贴纸（需提供贴纸的 file_id）。
setStickerPositionInSet：调整贴纸在贴纸包中的顺序。
setStickerEmojiList：修改某张贴纸的关联 emoji。
setStickerKeywords：添加或修改贴纸的搜索关键词（仅供贴纸商店用）。

这些方法配合使用，可以像运营产品一样持续优化你的贴纸包。建议在 Bot 中加入管理命令，让管理员可以通过聊天指令完成这些操作。

七、完整示例：一键创建含多张贴纸的贴纸包

下面提供一个完整的 Python 脚本，合并了以上步骤，并处理了 JSON 序列化问题：

import requests
import json

TOKEN = "你的Bot Token"
USER_ID = "你的用户ID"
API_URL = f"https://api.telegram.org/bot/"
STICKER_SET_NAME = "my_awesome_stickers_by_YourBotUsername"

# 1. 准备贴纸文件列表 (文件名, emoji)
stickers = [
    ("sticker1.png", "😀"),
    ("sticker2.png", "😂"),
    ("sticker3.png", "😎")
]

# 2. 创建贴纸包（使用第一张贴纸）
first_sticker = stickers[0]
files = {"sticker": open(first_sticker[0], "rb")}
data = {
    "user_id": USER_ID,
    "name": STICKER_SET_NAME,
    "title": "我的专属贴纸包",
    "sticker_format": "static",
    "emoji_list": json.dumps([first_sticker[1]])
}
resp = requests.post(API_URL + "createNewStickerSet", data=data, files=files)
print("createNewStickerSet:", resp.json())

# 3. 上传剩余贴纸并逐一添加
for sticker_file, emoji in stickers[1:]:
    # 先上传，获得 file_id
    files = {"sticker_file": open(sticker_file, "rb")}
    data = {"user_id": USER_ID, "sticker_format": "static"}
    up_resp = requests.post(API_URL + "uploadStickerFile", data=data, files=files)
    file_id = up_resp.json()["result"]["file_id"]
    
    # 添加贴纸到贴纸包
    sticker_payload = {
        "file_id": file_id,
        "emoji_list": json.dumps([emoji]),
        "format": "static"
    }
    add_data = {
        "user_id": USER_ID,
        "name": STICKER_SET_NAME,
        "sticker": json.dumps(sticker_payload)
    }
    add_resp = requests.post(API_URL + "addStickerToSet", data=add_data)
    print("addStickerToSet:", add_resp.json())

# 4. 设置封面（可选）
thumb_file = open("thumb.png", "rb")
thumb_data = {"user_id": USER_ID, "name": STICKER_SET_NAME}
thumb_files = {"thumb": thumb_file}
thumb_resp = requests.post(API_URL + "setStickerSetThumb", data=thumb_data, files=thumb_files)
print("setStickerSetThumb:", thumb_resp.json())

print("贴纸包创建完成！")

运行前，请确保将 Token、用户 ID 和文件名替换为实际值。注意：你的 Bot 必须先与用户对话一次（用户点击 Start），否则 user_id 可能无效。

八、常见错误与解决方法

1. 错误“STICKER_PNG_NOPNG”：上传的文件不是有效的 PNG。请确保图片是真正的 PNG 文件（可尝试另存为 PNG）。

2. 错误“STICKERSET_NAME_OCCUPIED”：该贴纸包名称已被占用。请更换名称。

3. 错误“USER_ID_INVALID”：用户 ID 无效，通常是因为 Bot 尚未与该用户开始聊天。让用户先通过 BotFather 给你的 Bot 发消息，或使用 Bot 发送一条消息给用户。

4. 错误“emoji_list is required”：新版 API 要求 emoji_list 必须为 JSON 数组字符串，不能直接用逗号分隔的字符串。

5. 文件尺寸超限：静态贴纸最大 512KB，且最长边不超过 512 像素（WebP 格式建议 512×512）。

6. 权限不足：如果 Bot 不是贴纸包的所有者，则无法执行管理操作。确保使用创建者用户 ID。

遇到其他未知错误时，可查询官方 API 文档或使用 getMe 验证 Token 是否有效。

总结

本文详细梳理了 Telegram Bot 创建贴纸包的完整 API 调用步骤，涵盖初始化、上传文件、添加贴纸、设置封面及后期管理。核心要点是：遵循官方要求的参数格式（尤其是 emoji_list 和 sticker_format），正确上传文件并获取稳定的 file_id，同时注意用户 ID 的有效性。掌握这些步骤后，你可以轻松打造品牌贴纸包，甚至开发出支持用户自定义贴纸包的 Bot 服务。希望本文能成为你开发路上的实用指南。

Telegram Bot创建贴纸包的API调用步骤详解：从上传文件到发布全流程

一、创建贴纸包的核心概念与前置准备

二、第一步：创建贴纸包（createNewStickerSet）

三、第二步：上传贴纸文件与获取 file_id

四、第三步：添加更多贴纸到已有贴纸包（addStickerToSet）

五、第四步：设置贴纸包为官方预览（setStickerSetThumb）与发布

六、贴纸包发布后的管理与维护

七、完整示例：一键创建含多张贴纸的贴纸包

八、常见错误与解决方法

总结

Telegram 中文版下载

多平台客户端选择

常见问题

延伸阅读