ProxyWing
浏览端点

ProxyWing 开发者 API

子用户

转售您的住宅流量。在服务下创建子用户，向其划转或从其收回流量（GB），生成其代理字符串，并根据其自身的用量报告向其计费。

POST /residential/services/{svc_id}/subusers

创建子用户

在您的某个住宅服务下创建子用户，并从该服务的余额中向其转移流量。这就是转售您自有流量的方式：每个子用户都是一套独立的凭据，拥有自己的 GB 余额和独立的用量报告。在两种套餐上，gb 都必须是整数 GB（1、2、3……），最小为 1——小数值将被拒绝并返回 422。流量会立即从父服务中扣除。在高级版上，您可以自行选择 username 和 password；在标准版上，两者均由平台设置，提供其中任何一个都将返回 400 unsupported_for_tier。当服务剩余的未分配流量不足时，返回 409 insufficient_unallocated_traffic。Idempotency-Key 为必填项——省略将在任何流量转移之前返回 400。

验证 · Bearer Idempotency-Key

路径参数

  • svc_id string 必填

    住宅服务 ID，可从 GET /residential/services 获取。

请求体参数

  • gb number 必填

    分配给新子用户的整数 GB。最小为 1。

  • label string 可选

    您为此子用户设置的自定义标识，在该服务内唯一。

  • username string 可选

    仅限高级版。按发送内容原样使用；省略则生成 12 个字符的随机名称。

  • password string 可选

    仅限高级版。12–64 个字符；省略则由我们生成。

请求 POST /residential/services/{svc_id}/subusers
curl -X POST "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Idempotency-Key: b3f2a1c4-7e9d-4a2b-8c6f-1d5e9a0b3c7f" \
  -H "Content-Type: application/json" \
  -d '{"label":"acme-client-01","gb":5}'
响应 200 · application/json
{
  "id": "rsub_42",
  "service_id": "resi_100001",
  "tier": "premium",
  "label": "acme-client-01",
  "username": "uexxjq9gp4xn",
  "allocated_gb": 5,
  "used_gb": null,
  "available_gb": null,
  "status": "active",
  "created_at": "2026-07-26T08:12:44Z",
  "password": "MCCk99K80AtGEPY2"
}
GET /residential/services/{svc_id}/subusers

列出子用户

列出住宅服务下有效的子用户，以及其已分配的流量和状态。已删除和创建失败的子用户不会列出。此处不包含实时余额——请通过 GET .../subusers/{subuser_id}/traffic 读取。密码仅由创建和轮换密码操作返回，或通过 GET .../subusers/{subuser_id}/credentials 获取。

验证 · Bearer

路径参数

  • svc_id string 必填

    住宅服务 ID，可从 GET /residential/services 获取。

查询参数

  • limit integer 可选

    要返回的最大行数。默认 50。

  • offset integer 可选

    要跳过的行数，用于分页。

请求 GET /residential/services/{svc_id}/subusers
curl -X GET "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"
响应 200 · application/json
{
  "subusers": [
    {
      "id": "rsub_42",
      "service_id": "resi_100001",
      "tier": "premium",
      "label": "acme-client-01",
      "username": "uexxjq9gp4xn",
      "allocated_gb": 5,
      "used_gb": null,
      "available_gb": null,
      "status": "active",
      "created_at": "2026-07-26T08:12:44Z",
      "password": null
    }
  ]
}
GET /residential/services/{svc_id}/subusers/{subuser_id}

获取子用户

返回单个子用户，包括其当前的分配额度和状态。此处不包含实时余额——请通过 GET .../subusers/{subuser_id}/traffic 读取。密码仅由创建和轮换密码操作返回，或通过 GET .../subusers/{subuser_id}/credentials 获取。

验证 · Bearer

路径参数

  • svc_id string 必填

    住宅服务 ID，可从 GET /residential/services 获取。

  • subuser_id string 必填

    子用户 ID，例如 rsub_42。

请求 GET /residential/services/{svc_id}/subusers/{subuser_id}
curl -X GET "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"
响应 200 · application/json
{
  "id": "rsub_42",
  "service_id": "resi_100001",
  "tier": "premium",
  "label": "acme-client-01",
  "username": "uexxjq9gp4xn",
  "allocated_gb": 5,
  "used_gb": null,
  "available_gb": null,
  "status": "active",
  "created_at": "2026-07-26T08:12:44Z",
  "password": null
}
PUT /residential/services/{svc_id}/subusers/{subuser_id}

重命名子用户

更新子用户的 label。标签是您自己的元数据，绝不会发送到上游网络。此处不包含实时余额——请通过 GET .../subusers/{subuser_id}/traffic 读取。密码仅由创建和轮换密码操作返回，或通过 GET .../subusers/{subuser_id}/credentials 获取。

验证 · Bearer

路径参数

  • svc_id string 必填

    住宅服务 ID，可从 GET /residential/services 获取。

  • subuser_id string 必填

    子用户 ID，例如 rsub_42。

请求体参数

  • label string 可选

    此子用户的新标签。

请求 PUT /residential/services/{svc_id}/subusers/{subuser_id}
curl -X PUT "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"label":"acme-client-renamed"}'
响应 200 · application/json
{
  "id": "rsub_42",
  "service_id": "resi_100001",
  "tier": "premium",
  "label": "acme-client-01",
  "username": "uexxjq9gp4xn",
  "allocated_gb": 5,
  "used_gb": null,
  "available_gb": null,
  "status": "active",
  "created_at": "2026-07-26T08:12:44Z",
  "password": null
}
POST /residential/services/{svc_id}/subusers/{subuser_id}/allocate

为子用户添加流量

从父服务向此子用户转移更多流量。gb 必须是整数 GB（1、2、3……），最小为 1；小数值将被拒绝并返回 422。如果父服务没有那么多未分配流量，将返回 409 insufficient_unallocated_traffic。Idempotency-Key 为必填项——省略将在任何流量转移之前返回 400。

验证 · Bearer Idempotency-Key

路径参数

  • svc_id string 必填

    住宅服务 ID，可从 GET /residential/services 获取。

  • subuser_id string 必填

    子用户 ID，例如 rsub_42。

请求体参数

  • gb number 必填

    要转给子用户的整数 GB。最小为 1。

请求 POST /residential/services/{svc_id}/subusers/{subuser_id}/allocate
curl -X POST "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}/allocate" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Idempotency-Key: b3f2a1c4-7e9d-4a2b-8c6f-1d5e9a0b3c7f" \
  -H "Content-Type: application/json" \
  -d '{"gb":2}'
响应 200 · application/json
{
  "id": "rsub_42",
  "service_id": "resi_100001",
  "tier": "premium",
  "label": "acme-client-01",
  "username": "uexxjq9gp4xn",
  "allocated_gb": 7,
  "used_gb": null,
  "available_gb": null,
  "status": "active",
  "created_at": "2026-07-26T08:12:44Z",
  "password": null
}
POST /residential/services/{svc_id}/subusers/{subuser_id}/reclaim

从子用户收回流量

从子用户收回流量并归还给父服务。省略 gb 即可收回该子用户仍持有的全部流量。与分配不同，此处的 gb 可以是小数：一个获分配 3 GB、已使用 0.4 的子用户持有 2.6，这部分剩余量必须可以归还。请求量超过子用户持有量时，将返回 409 insufficient_subuser_traffic，并注明确切的可用量。Idempotency-Key 为必填项——省略将在任何流量转移之前返回 400。

验证 · Bearer Idempotency-Key

路径参数

  • svc_id string 必填

    住宅服务 ID，可从 GET /residential/services 获取。

  • subuser_id string 必填

    子用户 ID，例如 rsub_42。

请求体参数

  • gb number 可选

    要收回的 GB 数。省略则收回全部剩余余额。

请求 POST /residential/services/{svc_id}/subusers/{subuser_id}/reclaim
curl -X POST "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}/reclaim" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Idempotency-Key: b3f2a1c4-7e9d-4a2b-8c6f-1d5e9a0b3c7f" \
  -H "Content-Type: application/json" \
  -d '{"gb":2}'
响应 200 · application/json
{
  "id": "rsub_42",
  "service_id": "resi_100001",
  "tier": "premium",
  "label": "acme-client-01",
  "username": "uexxjq9gp4xn",
  "allocated_gb": 3,
  "used_gb": null,
  "available_gb": null,
  "status": "active",
  "created_at": "2026-07-26T08:12:44Z",
  "password": null
}
DELETE /residential/services/{svc_id}/subusers/{subuser_id}

删除子用户

删除该子用户。其仍持有的流量会先退回到父服务，因此不会有任何损失。该凭据会立即失效。高级版用户名在删除后仍会保留，无法再次使用。Idempotency-Key 为必填项——省略它将在任何流量转移之前返回 400。

验证 · Bearer Idempotency-Key

路径参数

  • svc_id string 必填

    住宅服务 ID，可从 GET /residential/services 获取。

  • subuser_id string 必填

    子用户 ID，例如 rsub_42。

请求 DELETE /residential/services/{svc_id}/subusers/{subuser_id}
curl -X DELETE "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Idempotency-Key: b3f2a1c4-7e9d-4a2b-8c6f-1d5e9a0b3c7f"
响应 200 · application/json
{
  "id": "rsub_42",
  "status": "deleted"
}
GET /residential/services/{svc_id}/subusers/{subuser_id}/credentials

获取子用户凭据

返回此子用户的网关、端口和凭据——即您交给自己客户的信息。在高级版上，定位令牌附加在“密码”之后；在标准版上，用户名是一个固定的共享值，令牌附加在“用户名”之后，而密码用于标识该子用户。targeting_field 会告诉您适用哪种情况。

验证 · Bearer

路径参数

  • svc_id string 必填

    住宅服务 ID，可从 GET /residential/services 获取。

  • subuser_id string 必填

    子用户 ID，例如 rsub_42。

请求 GET /residential/services/{svc_id}/subusers/{subuser_id}/credentials
curl -X GET "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}/credentials" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"
响应 200 · application/json
{
  "id": "rsub_42",
  "tier": "premium",
  "gateway": "premium.proxywing.com",
  "http_ports": [
    12345,
    54321
  ],
  "socks5_ports": [
    12345,
    54321
  ],
  "username": "uexxjq9gp4xn",
  "password": "MCCk99K80AtGEPY2",
  "targeting_field": "password"
}
POST /residential/services/{svc_id}/subusers/{subuser_id}/rotate-password

轮换子用户密码

为子用户签发新密码；旧密码立即无法再通过身份验证。在高级版上，定位令牌存放在密码中，因此轮换密码会使您已为该子用户分发的所有代理字符串失效——请重新签发。在标准版上，令牌存放在用户名中，因此之前签发的字符串只需换用新密码即可。Idempotency-Key 为必填项——省略将在任何流量转移之前返回 400。

验证 · Bearer Idempotency-Key

路径参数

  • svc_id string 必填

    住宅服务 ID，可从 GET /residential/services 获取。

  • subuser_id string 必填

    子用户 ID，例如 rsub_42。

请求体参数

  • password string 可选

    仅限高级版。省略则自动生成。

请求 POST /residential/services/{svc_id}/subusers/{subuser_id}/rotate-password
curl -X POST "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}/rotate-password" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Idempotency-Key: b3f2a1c4-7e9d-4a2b-8c6f-1d5e9a0b3c7f" \
  -H "Content-Type: application/json" \
  -d '{}'
响应 200 · application/json
{
  "id": "rsub_42",
  "service_id": "resi_100001",
  "tier": "premium",
  "label": "acme-client-01",
  "username": "uexxjq9gp4xn",
  "allocated_gb": 5,
  "used_gb": null,
  "available_gb": null,
  "status": "active",
  "created_at": "2026-07-26T08:12:44Z",
  "password": "7Qp2LmXe4RtVbN91"
}
GET /residential/services/{svc_id}/subusers/{subuser_id}/traffic

获取子用户流量

子用户的实时余额，从网络读取，而非来自我们的缓存。余额为零的子用户会在网关处被拒绝，直到您为其分配更多流量。

验证 · Bearer

路径参数

  • svc_id string 必填

    住宅服务 ID，可从 GET /residential/services 获取。

  • subuser_id string 必填

    子用户 ID，例如 rsub_42。

请求 GET /residential/services/{svc_id}/subusers/{subuser_id}/traffic
curl -X GET "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}/traffic" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"
响应 200 · application/json
{
  "id": "rsub_42",
  "allocated_gb": 5,
  "used_gb": 1.204,
  "available_gb": 3.796
}
GET /residential/services/{svc_id}/subusers/{subuser_id}/usage-report

子用户用量报告

按子用户统计某一日期范围内的用量，格式与服务级报告相同——因此您无需构建任何新内容，即可据此向自己的客户计费。

验证 · Bearer

路径参数

  • svc_id string 必填

    住宅服务 ID，可从 GET /residential/services 获取。

  • subuser_id string 必填

    子用户 ID，例如 rsub_42。

查询参数

  • date_from string 必填

    开始日期，YYYY-MM-DD。

  • date_to string 必填

    结束日期，YYYY-MM-DD。

  • unit string 可选

    B、KB、MB 或 GB。默认 GB。

请求 GET /residential/services/{svc_id}/subusers/{subuser_id}/usage-report
curl -X GET "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}/usage-report" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"
响应 200 · application/json
{
  "tier": "premium",
  "date_from": "2026-07-01",
  "date_to": "2026-07-26",
  "unit": "GB",
  "total": 1.204,
  "rows": [
    {
      "date": "2026-07-24",
      "data": 0.61,
      "requests": 8123
    }
  ]
}
POST /residential/services/{svc_id}/subusers/{subuser_id}/generate-proxy-list

生成子用户代理列表

为此子用户生成即用型代理字符串——即您交给自己客户的确切字符串。其格式与服务级生成器逐字节一致，因此您的客户无法分辨是哪个端点生成的。

验证 · Bearer

路径参数

  • svc_id string 必填

    住宅服务 ID，可从 GET /residential/services 获取。

  • subuser_id string 必填

    子用户 ID，例如 rsub_42。

请求体参数

  • count integer 可选

    要生成的字符串数量。1–1000，默认 10。

  • protocol string 可选

    "http"（默认）、"socks5" 或 "mix"。"mix" 仅限标准版套餐——同一端口同时响应 HTTP 和 SOCKS5；在高级版上请求该值将返回 400。

  • format string 可选

    输出格式，例如 hostname:port:username:password。

  • port integer 可选

    要使用的特定网关端口。必须是该协议已公布的端口之一——高级版接受 102 HTTP 和 102 SOCKS5 端口，标准版接受 111 HTTP、112 SOCKS5，以及用于 "mix" 的 5555。默认根据 `session` 使用该套餐的轮换端口或粘性端口（"mix" 为 5555）。

  • country string 可选

    ISO 国家代码，以逗号分隔。

  • city string 可选

    要定位的城市。要求恰好指定一个 `country`——若使用逗号分隔的多国家值，城市将被忽略。两种套餐均可用；可通过 `GET /residential/services/{svc_id}/access?country=US` 查询有效名称（高级版覆盖的城市远多于标准版）。空格会被移除，因此 "Los angeles" 将以 `LosAngeles` 发送。

  • isp string 可选

    要定位的 ASN，例如 Comcast 为 `7922`。与 `city` 一样，要求恰好指定一个 `country`，并可与其组合以同时锁定两者（芝加哥的 Comcast）。高级版接受 AS 号或提供商名称；标准版需要 AS 号。没有 ASN 查询端点——请自行提供 AS 号。

  • session string 可选

    rotating 或 sticky。默认 rotating。

  • session_ttl string 可选

    粘性会话时长，例如 10m、1h。

  • ipv4 boolean 可选

    仅限标准版套餐：限定使用仅 IPv4 的 IP 池。默认 true。

  • streaming boolean 可选

    仅限高级版套餐：使用高端流媒体 IP 池。默认 false。

  • direct boolean 可选

    仅限高级版套餐：直连模式，适用于 IMAP 等不适合默认路径的协议。默认 false。

  • skip_static_isp boolean 可选

    仅限高级版套餐：跳过静态 ISP 出口。默认 false。

  • host string 可选

    输出原始入口 IP，而非 DNS 网关主机名。必须是该套餐已公布的入口 IP 之一，或该套餐的网关名称；其他任何值都将返回 400。除非确有需要，否则请勿设置——网关主机名按地理位置路由，固定 IP 会使使用该字符串的所有用户都被发送到同一区域。可用 IP 由子用户凭据端点以 `entry_ips` 返回。

请求 POST /residential/services/{svc_id}/subusers/{subuser_id}/generate-proxy-list
curl -X POST "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}/generate-proxy-list" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"count":3,"protocol":"http","session":"rotating","country":"US"}'
响应 200 · application/json
{
  "gateway": "premium.proxywing.com",
  "port": 54321,
  "protocol": "http",
  "count": 3,
  "proxies": [
    "premium.proxywing.com:54321:uexxjq9gp4xn:MCCk99K80AtGEPY2_country-US"
  ]
}