要点摘要
以代理商的视角整理了标准 SMM面板 API v2 的请求方式、6 种 action、响应示例、错误信息和请求限制。
SMM面板 API 是从其他面板或自己开发的程序中自动提交订单并查看状态的连接方式。1PANEL PLUS 使用标准 SMM面板 API v2，如果您已有对接其他面板的代码，只需更换地址和密钥即可立即接入。API 和网站使用相同的服务、相同的每 1,000 个价格和相同的余额。
谁会使用 SMM面板 API？
- 代理商：在自己的面板上架服务，自动转交客户订单
- 营销机构：在指定时间一次性提交多个频道的订单
- 开发者：编写在开播或新视频上传时自动下单的脚本
- 运营者：把余额和订单状态汇总显示在自己的管理页面上
如何获取 API 密钥？
首笔充值到账后，在控制台的 API 密钥页面生成。密钥只在生成的那一刻显示一次，请立即复制并妥善保管。生成新密钥后旧密钥会立即失效，如果认为密钥已泄露，生成新密钥替换即可。
如何发送 API 请求？
所有请求都通过 POST 发送到同一个地址 https://1panelplus.com/api/v2。表单字段 (application/x-www-form-urlencoded 或 multipart) 或 JSON 正文 (Content-Type: application/json) 任选其一，所有请求都要同时带上 key 和 action。响应全部为 JSON。
请求示例 (表单字段)：key=YOUR_API_KEY&action=balance
请求示例 (JSON)：{"key": "YOUR_API_KEY", "action": "balance"}
| action | 同时发送的参数 | 返回的值 |
|---|---|---|
| services | 无 | 服务列表 |
| add | service、link、quantity 或 comments | order (订单编号) |
| status | 单个 order 或 orders (逗号分隔，最多 100 个) | charge、start_count、status、remains、currency |
| refill | order | refill (补量编号) |
| refill_status | refill | status |
| balance | 无 | balance、currency |
- action
- services
- 同时发送的参数
- 无
- 返回的值
- 服务列表
- action
- add
- 同时发送的参数
- service、link、quantity 或 comments
- 返回的值
- order (订单编号)
- action
- status
- 同时发送的参数
- 单个 order 或 orders (逗号分隔，最多 100 个)
- 返回的值
- charge、start_count、status、remains、currency
- action
- refill
- 同时发送的参数
- order
- 返回的值
- refill (补量编号)
- action
- refill_status
- 同时发送的参数
- refill
- 返回的值
- status
- action
- balance
- 同时发送的参数
- 无
- 返回的值
- balance、currency
如何用 services 获取服务列表？
发送 action=services，会以数组形式返回全部在售服务。每项服务包含 service (服务编号)、name、type、category、rate、min、max、refill、cancel。rate 是每 1,000 个的价格 (USD)，如果 type 为 Package，则为 1 个套餐的价格。带补量期的服务 refill 为 true，cancel 始终为 false。category 同时写有平台名称和分类，可以直接照搬到您自己面板的分类中。
响应示例：[{"service": 服务编号, "name": "服务名称", "type": "Default", "category": "YouTube - 分类名称", "rate": "每 1,000 个价格", "min": "最低数量", "max": "最高数量", "refill": true, "cancel": false}]
价格和服务可能会变化，代理商最好定期重新获取 services，使自己面板的价格以及最低和最高数量保持同步。
如何用 add 提交订单？
向 action=add 同时发送 service (服务编号)、link (公开链接) 和 quantity (数量)，订单即被受理，金额立即从余额中扣除。响应中的 order 是订单编号，请保存此编号用于 status 和 refill。首笔充值到账的账号即可下单。
- 普通服务：发送 service、link、quantity
- Custom Comments 服务：以 comments 代替 quantity 发送。每行一条评论，每行最多 500 个字符，行数即为数量
- Package 服务：无需发送数量，按一个套餐下单
请求示例：key=YOUR_API_KEY&action=add&service=SERVICE_ID&link=https://www.youtube.com/watch?v=videoid&quantity=1000
响应示例：{"order": 订单编号}
如何用 status 查看订单状态？
向 action=status 发送 order (单个订单编号)，会返回该订单的状态；在 orders 中用逗号连接订单编号发送，一次最多可查询 100 个。管理多个订单时，用 orders 批量查询可以大幅节省请求次数。
响应示例 (单个)：{"charge": "付款金额", "start_count": "起始数值", "status": "In progress", "remains": "剩余数量", "currency": "USD"}
响应示例 (多个)：{"订单编号1": {"charge": "...", "start_count": "...", "status": "Completed", "remains": "0", "currency": "USD"}, "订单编号2": {"error": "Incorrect order ID"}}
| status 值 | 含义 |
|---|---|
| Pending | 已受理，正在等待开始或转入处理 |
| In progress | 正在送达 |
| Completed | 已全部送达 |
| Partial | 部分已送达，剩余金额已退回余额 |
| Canceled | 未能处理，全额已退回余额 |
- status 值
- Pending
- 含义
- 已受理，正在等待开始或转入处理
- status 值
- In progress
- 含义
- 正在送达
- status 值
- Completed
- 含义
- 已全部送达
- status 值
- Partial
- 含义
- 部分已送达，剩余金额已退回余额
- status 值
- Canceled
- 含义
- 未能处理，全额已退回余额
charge 是付款金额减去退款金额后的值，所以部分完成或取消后，实际花费的金额会立即显示。订单状态大约每 1 分钟自动更新一次，status 也以 1 分钟左右的间隔查询就足够了。
refill 和 refill_status 怎么用？
向 action=refill 发送 order，即申请补量，并返回 refill (补量编号)。对带补量期服务的已完成或部分完成订单，在订单结束之日起的补量期内、没有进行中的补量且距上次申请已满 24 小时时受理。向 action=refill_status 发送 refill，会以 Pending、In progress、Completed、Rejected 之一告知状态。
响应示例：{"refill": 补量编号} 以及 {"status": "Completed"}
补量规则与网站相同。详细条件整理在了解补量期中。
如何用 balance 查看余额？
发送 action=balance，会返回当前余额和币种 (USD)。代理商可以在转交订单前查看余额，并设置余额低于一定金额时发送提醒，订单就能不间断地持续下去。
响应示例：{"balance": "当前余额", "currency": "USD"}
API 错误信息是什么意思？
错误以 JSON 返回，error 字段中是英文句子。每个句子对应固定的原因，在程序中直接比对处理即可。
| error 值 | 含义 |
|---|---|
| Invalid API key | 密钥缺失或不正确 |
| Too many requests | 超过了每分钟请求次数，请稍后再发送 |
| Add funds first | 首笔充值到账后才能下单 |
| Incorrect service ID | 不是在售的服务编号 |
| Incorrect link | 链接格式不正确 |
| Quantity out of range | 数量超出服务的最低和最高范围 |
| Incorrect comments | 评论行为空或某一行超过 500 个字符 |
| Not enough funds on balance | 余额少于订单金额 |
| Incorrect order ID | 不是该账号的订单编号 |
| Incorrect refill ID | 不是该账号的补量编号 |
| Incorrect action | action 值不是 6 种之一 |
- error 值
- Invalid API key
- 含义
- 密钥缺失或不正确
- error 值
- Too many requests
- 含义
- 超过了每分钟请求次数，请稍后再发送
- error 值
- Add funds first
- 含义
- 首笔充值到账后才能下单
- error 值
- Incorrect service ID
- 含义
- 不是在售的服务编号
- error 值
- Incorrect link
- 含义
- 链接格式不正确
- error 值
- Quantity out of range
- 含义
- 数量超出服务的最低和最高范围
- error 值
- Incorrect comments
- 含义
- 评论行为空或某一行超过 500 个字符
- error 值
- Not enough funds on balance
- 含义
- 余额少于订单金额
- error 值
- Incorrect order ID
- 含义
- 不是该账号的订单编号
- error 值
- Incorrect refill ID
- 含义
- 不是该账号的补量编号
- error 值
- Incorrect action
- 含义
- action 值不是 6 种之一
补量申请可能返回 Refill is not available for this service (没有补量期的服务)、Order is not finished yet (尚未结束的订单)、Refill period has ended (补量期已过的订单)、Refill already requested, try again later (有进行中的补量或未满 24 小时的订单)。
API 请求最多可以发送多少次？
每个密钥每分钟最多可请求 300 次。状态查询用 orders 每 100 个打包，服务列表只在需要时重新获取，就能宽裕使用。例如，进行中的订单有 1,000 个，每分钟发送 10 次请求即可全部查询。
代理商如何确定售价？
通过 API 获取的 rate 是 1PANEL PLUS 的每 1,000 个价格，您自己面板的售价由代理商自行决定。例如，在 rate 为 $2.00 的服务上加价 25% 出售，每 1,000 个就是 $2.50；客户订购 4,000 个时，销售金额为 $10.00，从 1PANEL PLUS 扣除的金额为 $8.00。此价格是用于演示计算的示例。
API 接入按什么顺序进行比较好？
- 为余额充值，并在控制台生成 API 密钥
- 用 balance 确认密钥和连接
- 用 services 获取服务列表，上架到自己的面板
- 以最小数量发送一次 add，获取订单编号
- 用 status 确认状态有变化后，开启自动下单
curl、PHP、Python、Node.js 示例和全部字段说明请见API 文档，其他问题可以在常见问题的 API 分类中查看。