打开控制台
公开文档

API 参考

自动化代理购买与续订。

管理密钥
参考
zh

简介

用于查询套餐、查看订阅、购买新代理、续订有效订阅以及配置自动 IP 轮换的编程接口。

API 使用单一端点：/api/proxy。对于 GET 操作，请在 query string 中传递 op；对于 POST 操作，请在 JSON body 中传递 op。

快速开始

在 Dashboard -> API Keys 创建 API key，并在每个请求的 header 中携带该 key。

BASE="https://makeadsafe.com"
API_KEY="rk_your_long_lived_api_key"

所有 ID 均为小写字母和数字。

通过 POST /api/proxy 携带 {"op":"trial","planId":"..."} 申请试用，仅对部分 API key 开放。如需为你的 key 启用该能力，请联系支持。试用使用情况会被监控，如有滥用，可能会被限制或关闭。

可用套餐

返回 API key 所有者可用的有效代理套餐。

curl -sS 
  -H "x-api-key: $API_KEY" 
  "$BASE/api/proxy?op=plans"
{
  "ok": true,
  "plans": [
    {
      "id": "k17m3q5v7n9p1r2t4w6y8z0a",
      "connectionType": "private",
      "durationMs": 2592000000,
      "priceAmountCents": 1200,
      "popular": true,
      "remainingProxies": 20,
      "network": {
        "name": "NL-AMS",
        "city": "Amsterdam",
        "country": "NL",
        "networkType": "mobile"
      }
    }
  ]
}

有效订阅

返回你的订阅信息，包括凭据、协议 URL 以及 IP 轮换数据。

curl -sS 
  -H "x-api-key: $API_KEY" 
  "$BASE/api/proxy?op=subscriptions"
{
  "ok": true,
  "subscriptions": [
    {
      "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
      "status": "active",
      "activeUntil": 1762592000000,
      "userNote": "Client A",
      "rotationPolicy": 10,
      "label": "12001 - NL - Private",
      "networkLabel": "NL-AMS Amsterdam",
      "credentials": {
        "username": "u_6k8s9d",
        "password": "p_2n4m6q"
      },
      "protocols": {
        "http": "http://u_6k8s9d:[email protected]:12001",
        "socks5": "socks5://u_6k8s9d:[email protected]:12001",
        "vless": "vless://...",
        "shadowsocks": "ss://..."
      },
      "rotate": {
        "rotatePath": "/r/abcd1234",
        "available": true
      }
    }
  ]
}

续费套餐

返回可用于续订指定订阅的套餐。

SUB_ID="j97b2f6m1k4n8p3r5t7v9x0z"

curl -sS 
  -H "x-api-key: $API_KEY" 
  "$BASE/api/proxy?op=renewal-plans&subscriptionId=$SUB_ID"
{
  "ok": true,
  "renewalPlans": [
    {
      "id": "k17m3q5v7n9p1r2t4w6y8z0a",
      "connectionType": "private",
      "durationMs": 2592000000,
      "priceAmountCents": 1200
    }
  ]
}

可用网络

返回可用于切换特定订阅的网络。

SUB_ID="j97b2f6m1k4n8p3r5t7v9x0z"

curl -sS 
  -H "x-api-key: $API_KEY" 
  "$BASE/api/proxy?op=available-networks&subscriptionId=$SUB_ID"
{
  "ok": true,
  "networks": [
    {
      "id": "b1c2d3e4f5g6h7j8k9m0n1p2",
      "networkLabel": "DE-BER Berlin",
      "country": "DE"
    }
  ]
}

在 switch-network 请求中，将 networks[].id 用作 targetNetwork。

购买订阅

使用所选套餐从你的余额创建一个或多个新订阅。

可选字段：

  • couponCode：为购买应用有效优惠券。
  • repeatCount：正整数，默认值为 1；会按倍数增加每个新订阅的时长和价格。
  • quantity：正整数，默认值为 1；允许一次请求创建多个订阅。
  • os：应用于所有新建代理的被动操作系统指纹；可选值为 ios、macos、android、win10 或 win11。不适用于 multi 套餐。
{
  "op": "purchase",
  "planId": "k17m3q5v7n9p1r2t4w6y8z0a",
  "couponCode": "MYCODE",
  "repeatCount": 3,
  "os": "ios",
  "quantity": 2
}
curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"purchase","planId":"k17m3q5v7n9p1r2t4w6y8z0a","repeatCount":3,"os":"ios","quantity":2}' 
  "$BASE/api/proxy"
{
  "ok": true,
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "subscriptionIds": [
    "j97b2f6m1k4n8p3r5t7v9x0z",
    "n38k2f6m1k4n8p3r5t7v9x0z"
  ],
  "subscriptions": [
    {
      "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
      "status": "active",
      "activeUntil": 1767776000000,
      "label": "12001 - NL - Private",
      "networkLabel": "NL-AMS Amsterdam"
    },
    {
      "subscriptionId": "n38k2f6m1k4n8p3r5t7v9x0z",
      "status": "active",
      "activeUntil": 1767776000000,
      "label": "12002 - NL - Private",
      "networkLabel": "NL-AMS Amsterdam"
    }
  ]
}

如果只创建了一个订阅，网关可能返回 subscription 而不是 subscriptions。subscription/subscriptions 中的项目结构与 GET /api/proxy?op=subscriptions 返回的结构相同。

续订订阅

使用符合条件的续费套餐续订现有订阅。

可选字段：

  • couponCode：为续订应用有效优惠券。
  • repeatCount：正整数，默认值为 1；会同时按倍数增加续订时长和价格。
{
  "op": "renew",
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "planId": "q2w4e6r8t0y2u4i6o8p0a2s4",
  "couponCode": "MYCODE",
  "repeatCount": 3
}
curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"renew","subscriptionId":"j97b2f6m1k4n8p3r5t7v9x0z","planId":"q2w4e6r8t0y2u4i6o8p0a2s4","repeatCount":3}' 
  "$BASE/api/proxy"
{
  "ok": true,
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "endAt": 1770368000000
}

更改连接凭据

为已认证用户（JWT）或 API Key 拥有者名下的有效订阅重新生成连接凭据。

{
  "op": "change-credentials",
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z"
}
curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"change-credentials","subscriptionId":"j97b2f6m1k4n8p3r5t7v9x0z"}' 
  "$BASE/api/proxy"
{
  "ok": true,
  "password": "q7N3x9Lp",
  "vpn": "7f3d9d4a-8b9f-4a93-9f55-2d5e3b7f1c24"
}

设置自动轮换策略

为活跃订阅配置自动 IP 轮换。该设置仅适用于带有 "rotate": { "available": true } 的连接。

rotationPolicy 允许的值为 0、5、10、15、30、60（分钟）。传 0 可关闭自动轮换。

{
  "op": "set-rotation-policy",
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "rotationPolicy": 10
}
curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"set-rotation-policy","subscriptionId":"j97b2f6m1k4n8p3r5t7v9x0z","rotationPolicy":10}' 
  "$BASE/api/proxy"
{
  "ok": true
}

更改连接网络

将活跃订阅迁移到另一个可用网络。

{
  "op": "switch-network",
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "targetNetwork": "b1c2d3e4f5g6h7j8k9m0n1p2"
}
curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"switch-network","subscriptionId":"j97b2f6m1k4n8p3r5t7v9x0z","targetNetwork":"b1c2d3e4f5g6h7j8k9m0n1p2"}' 
  "$BASE/api/proxy"
{
  "ok": true,
  "subscription": {
    "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
    "status": "active",
    "activeUntil": 1762592000000,
    "userNote": "Client A",
    "rotationPolicy": 10,
    "label": "12001 - DE - Private",
    "networkLabel": "DE-BER Berlin",
    "credentials": {
      "username": "u_6k8s9d",
      "password": "p_2n4m6q"
    },
    "protocols": {
      "http": "http://u_6k8s9d:[email protected]:12001",
      "socks5": "socks5://u_6k8s9d:[email protected]:12001",
      "vless": "vless://...",
      "shadowsocks": "ss://..."
    },
    "rotate": {
      "rotatePath": "/r/abcd1234",
      "available": true
    }
  }
}

网关错误

  • 400 JSON body 无效
  • 400 Body 必须是对象
  • 400 缺少或未知 op
  • 400 planId/subscriptionId/targetNetwork/rotationPolicy 缺失或无效
  • 400 repeatCount 或 quantity 无效
  • 400 os 无效
  • 401 Unauthorized
  • 402 余额不足
  • 403 Forbidden
  • 404 未找到订阅
  • 409 当前订阅不支持该轮换策略设置
  • 409 已售罄、套餐/网络未激活，或订阅状态无效
  • 409 multi 套餐不支持选择操作系统
  • 429 Rate limited
  • 500 Internal error