开发者 API

你可以在自己的代码中购买和管理代理：下单、读取套餐、续期、跟踪事件。你购买的一切都会成为一个套餐。套餐分为两类，由 family 字段区分：

	Residential	IPv4
`family`	`traffic_gateway`	`dedicated`
购买的是	以 GB 计的流量	N 个独享地址，按期限租用
如何付费	按 GB 计费，流量不过期	按地址按周期：1 周、2 周、1 个月、2 个月或 3 个月
连接	可生成任意数量、任意地理位置的连接字符串	固定的地址列表，共用一组登录名和密码
更换 IP	轮换或换 IP 链接	每 30 天可更换一次套餐内全部地址
产品	Residential	IPv4

购买、套餐列表和套餐详情是两类套餐共用的路由。仅一类套餐才有的操作单独说明：流量和固定地址。

基础地址与认证

https://ipv.rent

curl https://ipv.rent/api/v1/balance \
  -H 'Authorization: Bearer YOUR_API_KEY'

在 app.ipv.rent 注册，之后验证邮箱：未验证则无法登录。

密钥在控制台中创建：个人资料 → API密钥 → 创建密钥。密钥的完整内容只显示一次，每个账户最多 20 个有效密钥。

被吊销的密钥立即失效，事件日志中会记录 api_key.revoked 事件。

401 invalid_api_key - 密钥未被接受。403 insufficient_scope - 密钥缺少该路由所需的权限。

包含全部字段和示例的请求与响应 schema 见 OpenAPI 参考。

密钥权限

创建时未指定权限的密钥拥有全部权限。已创建密钥的权限集合无法修改。

权限	开放的内容
`catalog:read`	产品及其参数、地理目录、价格计算
`packages:read`	套餐列表、套餐详情、续期选项
`packages:write`	购买及所有套餐操作：加购流量、连接、密码、续期、更换地址、指纹、自动续期
`orders:read`	订单
`orders:write`	保留 - 目前没有任何路由需要它
`billing:read`	余额和交易
`events:read`	事件日志

路由

目录与购买 - 两类通用：

路由	权限	`Idempotency-Key`
`GET /api/v1/products`	`catalog:read`	-
`GET /api/v1/products/{product}/options`	`catalog:read`	-
`POST /api/v1/quote`	`catalog:read`	否
`POST /api/v1/packages`	`packages:write`	必填
`GET /api/v1/packages`	`packages:read`	-
`GET /api/v1/packages/{id}`	`packages:read`	-
`POST /api/v1/packages/{id}/password`	`packages:write`	否

仅 Residential：

路由	权限	`Idempotency-Key`
`GET /api/v1/geo/countries`, `/states`, `/cities`, `/asns`	`catalog:read`	-
`POST /api/v1/packages/{id}/proxies`	`packages:write`	否
`POST /api/v1/packages/{id}/topup`	`packages:write`	必填
`POST /api/v1/packages/{id}/rotation-secret`	`packages:write`	否

仅 IPv4：

路由	权限	`Idempotency-Key`
`GET /api/v1/packages/{id}/prolong-options`	`packages:read`	-
`POST /api/v1/packages/{id}/prolong`	`packages:write`	必填
`POST /api/v1/packages/{id}/replace`	`packages:write`	否
`POST /api/v1/packages/{id}/fingerprint`	`packages:write`	否
`POST /api/v1/packages/{id}/renewal`	`packages:write`	否

账户：

路由	权限	`Idempotency-Key`
`GET /api/v1/orders`, `/orders/{id}`	`orders:read`	-
`GET /api/v1/balance`, `/transactions`	`billing:read`	-
`GET /api/v1/events`	`events:read`	-

对套餐执行另一类套餐的操作，返回 422 unsupported_capability。

余额充值和密钥管理只能在控制台中进行。

频率限制

每个密钥每分钟 120 个请求，另外有修改操作的请求（POST）每分钟 30 个。每个响应都带有 RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset；超出限制返回 429，带 retry_after 和 Retry-After：等待指定的秒数后重试。

客服支持

Telegram：@ipvrent_support，邮箱 [email protected]。请附上错误响应体中的 request_id。

新闻和服务状态见频道 t.me/ipvrent。