连接与更换 IP

前面几节介绍 Residential。固定地址的连接方式不同：见下方单独一节。

连接字符串

POST /api/v1/packages/{id}/proxies 的响应中返回 host、port、username、password。

登录名是现成的字符串：定向和模式已编码在其中，不能自行拼装。

端口代表模式和协议，不能修改。

residential.ipv.rent:10000:USERNAME:PASSWORD          # 反检测浏览器、代理管理器
http://USERNAME:[email protected]:10000   # curl, requests, Node, Go
socks5://USERNAME:[email protected]:12000

curl -x 'http://USERNAME:[email protected]:10000' https://api.ipify.org

模式与协议

模式	行为
`rotating`	每次连接使用新地址
`sticky`	地址保持 `ttl_minutes`：3..1440，默认 60

每组（模式、协议）对应的端口见套餐详情中的 connection_options：

模式	HTTP	SOCKS5
`rotating`	9000	11000
`sticky`	10000	12000

不支持邮件协议（SMTP、IMAP、POP3）和 UDP。

定向

{
  "count": 10,
  "geo": {
    "country": "us",
    "state": "california",
    "city": "los angeles"
  }
}

取值为地理目录中的代码。

各层级均为可选：不传 geo 则使用全球地址池。
state、city 和 asn 需要 country。
国家以下的定向尽量满足：如果请求的地区、城市或运营商没有可用地址，则从同一国家的其他位置出口。

值不在目录中、未知的键或未指定国家就细分 - 返回 422 invalid_targeting，附带 field 和 value。

更换 IP

在 rotating 模式下地址自动更换。

每个 sticky 字符串都有自己的 rotation_url 链接：对其发送 GET 会释放当前地址，下一次连接将获得另一个地址。无需认证。

curl -s https://ipv.rent/r/9f3c1e...

HTTP	`status`	含义
200	`ok`	地址已释放
200	`not_in_use`	没有活动会话；下一次连接仍会获得新地址
200	`unconfirmed`	请求已发送，未得到确认
404	`not_found`	链接无效
410	`expired`	链接对应的资源已过期；流量套餐不会出现
429	`rate_limited`	请求过于频繁
503	`error`	更换地址失败

限制：每个地址每分钟 20 次请求，每个套餐 120 次，每个调用方 IP 300 次。无法单独吊销某一个链接 - POST /api/v1/packages/{id}/rotation-secret 会一次性使全部链接失效。

固定地址

IPv4 套餐是现成的地址列表。无需生成字符串：所有信息都在套餐详情 GET /api/v1/packages/{id} 中。

内容	获取位置
地址	`addresses[].host`
HTTP 端口	`addresses[].port_http`
SOCKS5 端口	`addresses[].port_socks`
登录名和密码	`credentials` - 套餐内所有地址共用一组

198.51.100.11:10010:USERNAME:PASSWORD             # 反检测浏览器、代理管理器
http://USERNAME:[email protected]:10010      # curl, requests, Node, Go
socks5://USERNAME:[email protected]:10011

curl -x 'http://USERNAME:[email protected]:10010' https://api.ipify.org

出口地址就是列表中的地址本身，在整个租期内不变。
UDP 通过 SOCKS5 工作 - 适用于游戏、通话和基于 QUIC 的服务。
没有定向和换 IP 链接：国家和位置在购买时选择。
可以通过更换获得新地址 - 一次更换套餐内全部地址，每 30 天一次。
不支持邮件协议（SMTP、IMAP、POP3）。

无法使用时

现象	原因
生成连接后认证失败	套餐密码已重新生成
所有 worker 同时失效	流量已用尽，请检查 `traffic.left_gb`
地址不在请求的地理位置	请求的位置没有可用地址，分配了同一国家的其他位置；地理目录会将这类国家标记为 `pool: thin` - 请改用上一级
生成连接时返回 422 `package_unavailable`	套餐尚未交付（等待 `status: active`）、`ttl_minutes` 超出 3..1440，或套餐不支持该模式或协议
固定地址在购买后不立即响应	套餐交付最多需要 2 分钟
固定地址全部同时停止响应	已到期：`status: expired`，请续期套餐
固定地址认证失败	密码已重新生成，或套餐在到期后续期并签发了新密码 - 请从详情中获取 `credentials`
旧的固定地址无法使用	地址已更换：`replacement.state: done`，新地址在 `addresses` 中