Telegram Premium和Stars API
通过您的应用、机器人或商店发送Telegram Premium和Telegram Stars礼品。简洁的REST API支持JSON格式，单一API密钥，订单价格与网站相同并从余额扣款。
快速入门
- 创建账户并在「余额」页面充值。
- 打开我的账户，进入API页面，创建您的API密钥。密钥仅显示一次，请妥善保存在您的服务器上。
- 在每个请求的X-Api-Key头部中发送密钥。
基础URL与格式
所有请求使用HTTPS和JSON。成功响应为{ "ok": true, "data": ... }，错误响应为{ "ok": false, "error": { "code", "message" } }（含稳定错误码）。
https://buytgpremium.com/api/v1
curl https://buytgpremium.com/api/v1/balance \
-H "X-Api-Key: btk_YOUR_KEY"
{ "ok": true, "data": { "credit": "120.00", "currency": "USD" } }接口端点
| 方式 | 路径 | 功能说明 |
|---|---|---|
| GET | /balance | 查询USD余额 |
| GET | /products | 获取Premium有效期套餐和Stars面额范围 |
| GET | /recipient?username= | 校验用户名类型：个人/频道/群组/机器人/无效 |
| POST | /quote | 计算订单金额并校验余额是否充足 |
| POST | /orders | 使用余额支付礼品订单 |
| GET | /orders?limit=&batch= | 查询近期订单（最多100条） |
| GET | /orders/{code} | 通过订单号查询单笔订单 |
提交订单
Premium：产品 "premium"，时长 3、6 或 12 个月，最多 10 个用户名作为接收者。星星：产品 "stars"，星星数量从 3,500 到 550,000，一个用户名作为接收者。总金额将立即从您的余额中扣除，并为每位接收者生成一个订单。
curl -X POST https://buytgpremium.com/api/v1/orders \
-H "X-Api-Key: btk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"product":"premium","months":12,"recipients":["alice","bob"]}'
{ "ok": true, "data": { "batch": "B-7KQ2-...", "total": "34.00", "currency": "USD",
"orders": [ { "code": "G-4MZ8-...", "product": "premium", "recipient": "alice", "months": 12,
"price": "17.00", "status": "completed" }, ... ] } }curl -X POST https://buytgpremium.com/api/v1/orders \
-H "X-Api-Key: btk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"product":"stars","stars":5000,"recipient":"alice"}'错误代码
| 代码 | 含义 |
|---|---|
| 缺少API密钥 / 无效的API密钥 | 未提供API密钥/密钥错误或已被替换（401） |
| 无效输入 / 无效接收者 | 请检查产品、月数、星星数量或用户名 (400) |
| recipient_not_user | 该用户名是频道、群组或机器人，或不存在 |
| insufficient_credit | 余额不足；请充值 |
| network_error | 临时网络错误；您的余额未变动，请重试 |
| rate_limited | 每分钟每个密钥超过 120 个请求（429，请参阅 Retry-After） |
限制与安全
- 每分钟每个密钥 120 次请求；每 10 分钟 60 次接收者检查。
- 每个账户一个密钥。替换会立即停用旧密钥。
- 请将密钥保存在服务器上。切勿放入网页或移动应用。