跳转到内容
登录 注册

ISP代理API

在 panel 中 ISP Proxies 套餐页面上能做的所有操作，通过这个 API 同样可以实现：搜索可放置 IP 的地点、列出每个代理及其用户名、放置尚未放置的 IP，以及将 IP 迁移到另一个城市或 ISP。

身份验证

章节标题“身份验证”

所有端点均使用 api_token 查询参数进行身份验证。可在 panel 的 Account → API Tokens 下生成令牌。

?api_token=YOUR_API_TOKEN

每个路径都以 https://shifter.io/api/v1/isp/{membership} 开头。{membership} 路径参数接受两种形式的套餐标识符：套餐 panel URL 末尾的短代码（例如 Rxqk），或套餐页面上显示的套餐编号（例如 68057）。两者都会解析到同一个套餐。

此 API 仅能访问属于该令牌所有者的 ISP Proxies 套餐。访问其他任何套餐都会返回 404。

地点变更规则

章节标题“地点变更规则”
  • 每个 IP 在每个计费周期内可变更地点 5 次。套餐续订时该计数会重置，未使用的变更次数不会结转到下一个周期。试用套餐同样适用此规则。
  • 迁移后的 IP 会获得新的用户名和新的 proxy_id。旧用户名会立即失效，因此请立刻将客户端切换到新用户名。
  • 套餐密码保持不变。每个套餐只有一个密码，由该套餐下的所有用户名共享。
  • 用户名区分大小写。每个代理都通过 isp.shifter.io:443 连接，支持 HTTP(S) 或 SOCKS5。
  • 每个 IP 会保留你所选择的城市和 ISP。其背后的地址可能会不时刷新，就像家庭网络连接会从 ISP 获得新地址一样。

列出地点

章节标题“列出地点”
GET https://shifter.io/api/v1/isp/{membership}/locations

返回可放置 IP 的城市和 ISP 组合，以及每个组合当前可用的 IP 数量。没有可用数量的地点默认不会列出，除非你明确要求包含它们。

参数位置是否必需说明
membershippath是套餐 ID（短代码或套餐编号）
api_tokenquery是你的账户 API 令牌
countryquery否ISO 3166-1 alpha-2 国家代码，例如 US
qquery否搜索文本：城市（本地名称也可以）、地区、ISP 名称，或 ASN，例如 7922 或 AS7922
pagequery否页码，从 1 开始
per_pagequery否每页结果数，默认 100，最大 500
include_sold_outquery否设为 1 以包含没有可用 IP 的地点

示例：

终端窗口
curl "https://shifter.io/api/v1/isp/YOUR_PLAN_ID/locations?country=US&q=Dallas&api_token=YOUR_API_TOKEN"

响应：

{
  "ok": true,
  "page": 1,
  "per_page": 100,
  "total": 2,
  "has_more": false,
  "locations": [
    {
      "location_id": 1842,
      "country": "US",
      "region": "Texas",
      "city": "Dallas",
      "asn": 7922,
      "isp": "COMCAST-7922",
      "available": 7
    }
  ]
}

location_id 是固定不变的，因此可以存储下来以备后用。available 表示当前可在该地点放置的 IP 数量。可通过 has_more 判断是否需要请求下一页。

列出代理

章节标题“列出代理”
GET https://shifter.io/api/v1/isp/{membership}/proxies

返回该套餐的连接详情，以及每个已放置 IP 的用户名、地点和剩余地点变更次数。

参数位置是否必需说明
membershippath是套餐 ID（短代码或套餐编号）
api_tokenquery是你的账户 API 令牌

示例：

终端窗口
curl "https://shifter.io/api/v1/isp/YOUR_PLAN_ID/proxies?api_token=YOUR_API_TOKEN"

响应：

{
  "ok": true,
  "host": "isp.shifter.io",
  "port": 443,
  "password": "YOUR_PLAN_PASSWORD",
  "ips_total": 10,
  "ips_placed": 3,
  "ips_unplaced": 7,
  "changes_per_ip": 5,
  "period_ends_at": "2026-10-20T08:00:00+00:00",
  "proxies": [
    {
      "proxy_id": 5531,
      "username": "us-texas-dallas-as7922-Ksj25",
      "location_id": 1842,
      "country": "US",
      "region": "Texas",
      "city": "Dallas",
      "asn": 7922,
      "isp": "COMCAST-7922",
      "changes_left": 5
    }
  ]
}
字段说明
host / port该套餐下每个代理的连接地址
password套餐密码，由所有用户名共享
ips_total套餐中包含的 IP 数量
ips_placed / ips_unplaced已放置在地点上的 IP 数量，以及仍可放置的 IP 数量
changes_per_ip每个 IP 每个计费周期可获得的地点变更次数
period_ends_at当前计费周期结束及变更次数重置的时间
proxies[].username用于连接的用户名。区分大小写
proxies[].isp该 ASN 对应的 ISP 名称。若名称未知可能为 null
proxies[].changes_left该 IP 在当前周期内剩余的地点变更次数

要进行连接，请将这些字段组合成代理 URL：

http://us-texas-dallas-as7922-Ksj25:YOUR_PLAN_PASSWORD@isp.shifter.io:443
socks5://us-texas-dallas-as7922-Ksj25:YOUR_PLAN_PASSWORD@isp.shifter.io:443

迁移单个 IP

章节标题“迁移单个 IP”
POST https://shifter.io/api/v1/isp/{membership}/proxies/{proxy_id}/location

将一个 IP 迁移到另一个地点。此操作会使用该 IP 的一次地点变更次数。

参数位置是否必需说明
membershippath是套餐 ID（短代码或套餐编号）
proxy_idpath是要迁移的 IP 的 proxy_id
api_tokenquery是你的账户 API 令牌
location_idbody是要将该 IP 迁移到的地点

示例：

终端窗口
curl -X POST "https://shifter.io/api/v1/isp/YOUR_PLAN_ID/proxies/5531/location?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"location_id":1901}'

响应：

{
  "ok": true,
  "message": "Location changed. Use the new username from now on.",
  "old_proxy_id": 5531,
  "proxy": {
    "proxy_id": 5534,
    "username": "us-texas-austin-as7018-Pq7rT",
    "location_id": 1901,
    "country": "US",
    "region": "Texas",
    "city": "Austin",
    "asn": 7018,
    "isp": "ATT-INTERNET4",
    "changes_left": 4
  }
}

该 IP 现在拥有新的 proxy_id 和新的 username。旧用户名（以及 old_proxy_id）会在响应返回后立即失效。

迁移多个 IP

章节标题“迁移多个 IP”
POST https://shifter.io/api/v1/isp/{membership}/proxies/location

在一次请求中迁移多个 IP，每个 IP 都迁移到你为其指定的地点。

参数位置是否必需说明
membershippath是套餐 ID（短代码或套餐编号）
api_tokenquery是你的账户 API 令牌
movesbody是{"proxy_id", "location_id"} 键值对数组，每次请求最多 1,000 个
dry_runbody否设为 true 以在不做任何变更的情况下检查请求。默认 false
  • 该请求是全有或全无的：如果有任何一项迁移无法完成，所有 IP 都不会迁移，并且你会收到一个错误。
  • 如果某一项的 IP 已经在目标地点上，该项会被跳过且不会消耗变更次数。其 proxy_id 会列在 skipped 中。
  • 当 dry_run: true 时不会写入任何数据。响应会显示本应发生的结果，moved 中的 proxy_id 和 username 均设为 null，因为新的值只有在真正迁移后才会存在。

示例：

终端窗口
curl -X POST "https://shifter.io/api/v1/isp/YOUR_PLAN_ID/proxies/location?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"moves":[{"proxy_id":5531,"location_id":1901},{"proxy_id":5532,"location_id":1842}],"dry_run":false}'

响应：

{
  "ok": true,
  "dry_run": false,
  "message": "1 IP moved. Use the new username from now on. 1 IP was already there and stays as it is.",
  "moved": [
    {
      "old_proxy_id": 5531,
      "proxy_id": 5535,
      "username": "us-texas-austin-as7018-Zt3wQ",
      "location_id": 1901,
      "country": "US",
      "region": "Texas",
      "city": "Austin",
      "asn": 7018,
      "isp": "ATT-INTERNET4",
      "changes_left": 4
    }
  ],
  "skipped": [5532]
}

放置未放置的 IP

章节标题“放置未放置的 IP”
POST https://shifter.io/api/v1/isp/{membership}/proxies/place

放置尚未在任何地点上的 IP（代理列表中的 ips_unplaced）。放置 IP 不会消耗地点变更次数。

参数位置是否必需说明
membershippath是套餐 ID（短代码或套餐编号）
api_tokenquery是你的账户 API 令牌
placementsbody是{"location_id", "count"} 键值对数组：在每个地点上要放置多少个 IP

示例：

终端窗口
curl -X POST "https://shifter.io/api/v1/isp/YOUR_PLAN_ID/proxies/place?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"placements":[{"location_id":1901,"count":2}]}'

响应：

{
  "ok": true,
  "message": "2 IPs are ready.",
  "placed": 2,
  "ips_unplaced": 5,
  "proxies": [
    {
      "proxy_id": 5540,
      "username": "us-texas-austin-as7018-Hh8aa",
      "location_id": 1901,
      "country": "US",
      "region": "Texas",
      "city": "Austin",
      "asn": 7018,
      "isp": "ATT-INTERNET4",
      "changes_left": 5
    }
  ]
}

端到端示例

章节标题“端到端示例”

在奥斯汀查找一个地点，将两个 IP 迁移过去，然后读回从此以后要使用的用户名。此处使用 jq 来读取 JSON。

终端窗口
TOKEN="YOUR_API_TOKEN"
PLAN="YOUR_PLAN_ID"
BASE="https://shifter.io/api/v1/isp/$PLAN"


# 1. Find a location with IPs available
LOCATION=$(curl -s "$BASE/locations?country=US&q=Austin&api_token=$TOKEN" \
  | jq '.locations[0].location_id')


# 2. Move two IPs there
curl -s -X POST "$BASE/proxies/location?api_token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"moves\":[{\"proxy_id\":5531,\"location_id\":$LOCATION},{\"proxy_id\":5532,\"location_id\":$LOCATION}]}" \
  | jq -r '.moved[].username'


# 3. Read every current username and build proxy URLs
curl -s "$BASE/proxies?api_token=$TOKEN" \
  | jq -r '.password as $p | .proxies[] | "http://\(.username):\($p)@isp.shifter.io:443"'

请立即用步骤 2 或步骤 3 中的新用户名更新你的客户端：迁移完成后，旧用户名会立即失效。

错误

章节标题“错误”

失败的请求会返回 "ok": false，并附带可供程序识别的 error 代码和可读的 message：

{
  "ok": false,
  "error": "plan_inactive",
  "message": "This plan is not active, so locations cannot be assigned."
}
状态码error含义
404not_found该套餐或 IP 在你的账户中不存在。可能包含 proxy_ids
422validation某个参数缺失或无效
422no_changes_left一个或多个 IP 在本周期内的地点变更次数已用完。包含 proxy_ids
409out_of_stock某个地点没有足够的可用 IP。包含 location_id 和 available
409plan_inactive该套餐未处于激活状态，因此其 IP 无法被放置或迁移

速率限制

章节标题“速率限制”
请求限制
读取（GET）每个账户每分钟 60 次
写入（POST）每个账户每分钟 20 次

超过限制后，API 会返回 429。请等待后使用退避策略重试。要迁移多个 IP，请将它们放在一次 迁移多个 IP 请求中发送，而不是为每个 IP 单独发送一次请求。

另请参阅

章节标题“另请参阅”