REST API v2

概览

这是 AI 智能体驱动的接口。每次调用都是由 action 选定的一个动词,所以智能体搜索目录、读回费率和限额,然后行动，先搜后做,在任何资金动用之前先确认价格。MCP 服务器和 CLI 封装的是同一批调用;本页是底层的原始协议。

本 API 遵循广泛采用的 SMM API v2 形态,因此现有的面板软件、脚本和智能体集成只需极少改动即可使用。每个操作都通过单一端点完成,并用 action 参数选择动词。响应是 JSON，脚本或 LLM 都易于解析和串联。

端点

POST https://api.socialgo.com/api/v2

身份验证

身份验证按请求进行，无会话、无握手,这正是它能被智能体调用的原因。每次调用都发送你的私密 key。在仪表板的账户 → API中查找并轮换它。请像对待密码一样对待密钥:保存在服务器端,绝不放进客户端代码或智能体提示词。

请求格式

通过 POST 发送 application/x-www-form-urlencoded 表单参数。每个响应都是 JSON。每次调用都包含两个参数:

• key，你的 API 密钥(必填)
• action，要执行的动词(必填)

错误格式

失败时响应会带一个 error 字段,内含可读消息,HTTP 状态码也反映问题(例如 400 错误请求、401 密钥无效)。形态可预测,脚本或智能体无需猜测即可据此分支。

{
  "error": "Incorrect request"
}

操作

每个动词只干一件事。智能体按顺序串联它们:用 services 找到要买什么,用 add 买下,用 status 跟踪。读取调用(services、status、balance)让它在写入调用(add、refill、cancel)花钱之前确认价格和资金。

1. 列出服务

智能体首先读取的目录:它能下单的每项服务,含服务 ID、类别、费率(每千单位价格)和最小/最大数量。它用返回的 service ID 下单，并用费率在花钱前确认成本。

请求

key=YOUR_API_KEY
action=services

响应

[
  {
    "service": 1,
    "name": "Instagram Followers",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.90",
    "min": "50",
    "max": "10000",
    "refill": true,
    "cancel": true
  },
  {
    "service": 2,
    "name": "Instagram Likes",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.40",
    "min": "10",
    "max": "20000",
    "refill": false,
    "cancel": true
  }
]

2. 添加订单

写入调用。为单项服务下单，传入 service ID、目标 link 和 quantity。响应返回可跟踪的新 order ID。智能体只在确认费率和限额后才运行这个调用。

参数

• service，服务列表中的服务 ID
• link，帖子/主页/频道的 URL
• quantity，要投放的单位数量

请求

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000

响应

{
  "order": 23501
}

3. 添加订单，滴灌投放

把一个订单拆成若干较小批次,分散在一段时间内投放,形成更平稳的曲线。设置 runs(投放次数)和 interval(每次之间的分钟数)。投放总量为 quantity × runs，智能体用这道算式来确定活动规模,不必你手动算。

附加参数

• runs，投放批次数
• interval，每次投放之间的分钟数

请求

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000
runs=10
interval=60

响应

{
  "order": 23502
}

4. 订单状态

返回单个订单的当前状态:费用、起始计数、状态、剩余数量和币种。智能体借此盯订单而无需你刷新仪表板，也借此发现值得标记补单的掉量。

请求

key=YOUR_API_KEY
action=status
order=23501

响应

{
  "charge": "0.90",
  "start_count": "4250",
  "status": "In progress",
  "remains": "200",
  "currency": "USD"
}

可能的 status 值: Pending, In progress, Processing, Completed, Partial, Canceled.

5. 多个订单状态

一次调用查询多个订单，在 orders 参数中传入以逗号分隔的 ID 列表。响应以订单 ID 为键,智能体一次往返即可轮询整场活动,而不必每单一次调用。

请求

key=YOUR_API_KEY
action=status
orders=23501,23502,23503

响应

{
  "23501": {
    "charge": "0.90",
    "start_count": "4250",
    "status": "Completed",
    "remains": "0",
    "currency": "USD"
  },
  "23502": {
    "charge": "9.00",
    "start_count": "1200",
    "status": "In progress",
    "remains": "500",
    "currency": "USD"
  },
  "23503": {
    "error": "Incorrect order ID"
  }
}

6. 补单

为支持补单的服务订单(服务列表中 refill: true)请求补单,返回可跟踪的补单 ID。传入单个 order 或以逗号分隔的 orders 列表，智能体即可在状态检查标记掉量后批量请求补单。

请求(单个)

key=YOUR_API_KEY
action=refill
order=23501

响应

{
  "refill": 4001
}

请求(多个)

key=YOUR_API_KEY
action=refill
orders=23501,23502

响应

[
  { "order": 23501, "refill": 4001 },
  { "order": 23502, "refill": { "error": "Refill not available" } }
]

7. 取消

请求取消尚未处理的订单(cancel: true 的服务)。传入以逗号分隔的 orders 列表;响应按订单报告结果。当有东西被误排队时,智能体会用这个动作撤销。

请求

key=YOUR_API_KEY
action=cancel
orders=23501,23502

响应

[
  { "order": 23501, "cancel": 1 },
  { "order": 23502, "cancel": { "error": "Incorrect order ID" } }
]

8. 余额

返回你的账户余额和币种。智能体读取它来在下单前限制花费，你自己的面板也读取它来显示资金。这是确认有钱可花的最廉价调用。

请求

key=YOUR_API_KEY
action=balance

响应

{
  "balance": "182.45",
  "currency": "USD"
}

用任何工具调用

一个端点、普通表单参数，shell、定时任务或智能体都能以同样方式驱动它。下面是一笔从命令行下出的完整订单:

curl -X POST https://api.socialgo.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=1" \
  -d "link=https://instagram.com/example" \
  -d "quantity=1000"

注意事项与最佳实践

• 先读后写。调用 services(或 balance)确认费率、限额和资金,再调用 add，这正是仪表板和 MCP 服务器使用的先搜后做护栏,确保没有确认价格就不花钱。
• 缓存服务列表并定期刷新，ID、费率和限额会变化。
• 提交订单前校验 min/max 数量,以避免被拒绝的调用。
• 用多订单调用批量轮询状态,而不是每单一个请求。
• 把密钥保存在服务器端。一旦暴露,立即从仪表板轮换它。