跳到正文
只只HTTP代理只只HTTP代理- Zzhttp.com -认证领赠送余额 注册
本中心目录
API 文档 · 静态 IP 功能

批量搜索静态实例

只读批量精确 IP 搜索，与订单/分组/地区/状态取交集。完整 IPv4/IPv6 校验并去重，每次最多 500 个。无效、空集合、超限整批拒绝，不泄露其他账户匹配情况。

只只HTTP技术团队维护更新于 2026年10月6日

接口与认证

POST/openapi/v1/static/instances/search

只读批量精确 IP 搜索，与订单/分组/地区/状态取交集。完整 IPv4/IPv6 校验并去重，每次最多 500 个。无效、空集合、超限整批拒绝，不泄露其他账户匹配情况。

使用 HTTPS 和账户 API 令牌。响应包含 Cache-Control: no-store 和 X-Request-Id。

示例为合成数据与占位凭据，仅说明结构。接口合同不代表目标环境已开放，开放状态以控制台为准。

下载 OpenAPI · 导入 Apifox / Postman

请求参数

查询与路径参数
字段类型必填默认值 / 限制说明
api_keystring是Query · 唯一非空账户 API 令牌，在受控服务端保存；示例使用占位符。

请求示例 · application/json

请求示例
字段类型必填默认值 / 限制说明
ipsstring[]是最少项 1；最多项 10000完整 IP、IPv4:port 或 [IPv6]:port；端口 1–65535。带端口精确匹配 IP 与端口，不带端口匹配全部端口。IPv6 带端口须加方括号；拒绝 CIDR、zone、片段。原始最多10000项，按IP与端口去重后1–500项。地址文本保留首个原文精确匹配。
orderNostring否—平台订单号；查询筛选时精确匹配本人订单。
groupIdinteger | null否最小 0筛选分组：省略或 null 为全部，0 为未分组，正整数为本人分组。
countryCodestring否—国家三字码，例如 USA；使用国家目录返回值。
cityCodestring否—城市编码，使用城市目录返回值。
statusstring否—实例状态精确筛选：provisioning、active、expired、cancelled 或 failed。
pageinteger否默认 1；最小 1；最大 1000000页码，从 1 开始，默认 1。
pageSizeinteger否默认 20；最小 1；最大 1000每页数量，默认 20；最大值见字段限制。
activatedFromstring否格式 date-time开通时间下界，含边界；含时区 RFC3339，可单独指定。
activatedTostring否格式 date-time开通时间上界，含边界；含时区 RFC3339，可单独指定，不能早于下界。

请求示例

Shell · STATIC_API_KEY 使用账户令牌
curl --request POST \
  "https://api.zzhttp.com/openapi/v1/static/instances/search?api_key=${STATIC_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"ips":["203.0.113.10","2001:db8::1"],"orderNo":"STATIC-DEMO-001","groupId":0,"countryCode":"USA","cityCode":"NYC","status":"active","page":1,"pageSize":20}'

成功响应

成功

响应不包含代理密码，凭据仅由专用接口返回。

响应字段（含嵌套字段）
字段类型必填默认值 / 限制说明
codeinteger是固定 200统一数字业务码：HTTP 与业务码成功均为 200；异步受理不代表交付完成。
messagestring是—服务端结果说明。
requestIdstring是—本次请求的追踪 ID，用于排障，不是业务幂等编号。
dataobject是—本接口业务数据。
data.itemsobject[]是—结果或提交明细数组，具体字段见下级。
data.items[].instanceIdinteger是最小 1；格式 int64实例 ID，属于当前账户；分组绑定此 ID。
data.items[].offerIdinteger是最小 1；格式 int64当前可采购商品 ID，来自商品列表。
data.items[].statusstring是枚举 provisioning / active / expired / cancelled / failed当前状态；枚举见限制，按逐项结果确认终态。
data.items[].ipstring是—实例实际 IP 地址。
data.items[].portinteger是最小 0；格式 int64实例直连端口。
data.items[].protocolsstring[]是—支持协议；实例列表为字符串数组，凭据响应为逗号分隔字符串。
data.items[].countryCodestring是—国家三字码，例如 USA；使用国家目录返回值。
data.items[].cityCodestring是—城市编码，使用城市目录返回值。
data.items[].ispTypeinteger是最小 0；格式 int64IP 类型：1 标准静态住宅，2 原生静态住宅。
data.items[].expiresAtstring | null是格式 date-time实例到期时间，RFC3339；未知为 null。
data.items[].activatedAtstring | null是格式 date-time实例激活时间，RFC3339；未激活为 null。
data.items[].capabilitiesobject是—真实货源或实例能力；声明不替代提交时业务校验，缺失快照可为空对象。
data.items[].capabilities.purchaseobject否—采购期限规则。
data.items[].capabilities.purchase.allowedDaysinteger[]否—允许的期限天数集合；非空时优先采用该集合。
data.items[].capabilities.purchase.minDaysinteger否最小 0无 allowedDays 集合时的最短期限。
data.items[].capabilities.purchase.maxDaysinteger否最小 0最长期限，0 表示不设上限。
data.items[].capabilities.purchase.stepDaysinteger否最小 0从最短期限起允许的增量天数。
data.items[].capabilities.renewobject否—续费期限规则。
data.items[].capabilities.renew.allowedDaysinteger[]否—允许的期限天数集合；非空时优先采用该集合。
data.items[].capabilities.renew.minDaysinteger否最小 0无 allowedDays 集合时的最短期限。
data.items[].capabilities.renew.maxDaysinteger否最小 0最长期限，0 表示不设上限。
data.items[].capabilities.renew.stepDaysinteger否最小 0从最短期限起允许的增量天数。
data.items[].capabilities.convertTrialobject否—试用转正式期限规则。
data.items[].capabilities.convertTrial.allowedDaysinteger[]否—允许的期限天数集合；非空时优先采用该集合。
data.items[].capabilities.convertTrial.minDaysinteger否最小 0无 allowedDays 集合时的最短期限。
data.items[].capabilities.convertTrial.maxDaysinteger否最小 0最长期限，0 表示不设上限。
data.items[].capabilities.convertTrial.stepDaysinteger否最小 0从最短期限起允许的增量天数。
data.items[].capabilities.trialDaysinteger否最小 0试用期限天数；0 表示不提供试用。
data.items[].capabilities.changeIpboolean否—是否支持换 IP。
data.items[].capabilities.selectReplacementboolean否—是否支持选择替换节点。
data.items[].capabilities.customCredentialsboolean否—是否支持客户指定账密。
data.items[].capabilities.randomCredentialsboolean否—是否支持随机生成账密。
data.items[].capabilities.maxBatchSizeinteger否最小 0货源能力声明的批量上限；服务端请求限制仍适用。
data.items[].groupIdinteger | null是最小 1所属自定义分组 ID，未分组为 null；新实例默认未分组。
data.pageinteger是最小 0；格式 int64页码，从 1 开始，默认 1。
data.pageSizeinteger是最小 0；格式 int64每页数量，默认 20；最大值见字段限制。
data.totalinteger是最小 0；格式 int64筛选后的总记录数，不是当前页条数。
JSON · HTTP 200
{
  "code": 200,
  "message": "成功",
  "requestId": "00000000-0000-4000-8000-000000000001",
  "data": {
    "items": [
      {
        "instanceId": 101,
        "offerId": 17,
        "status": "active",
        "ip": "203.0.113.10",
        "port": 9000,
        "protocols": [
          "http",
          "socks5"
        ],
        "countryCode": "USA",
        "cityCode": "NYC",
        "ispType": 1,
        "expiresAt": "2026-10-06T08:00:00Z",
        "activatedAt": "2026-10-06T08:00:00Z",
        "capabilities": {
          "purchase": {
            "allowedDays": [
              30
            ]
          },
          "renew": {
            "allowedDays": [
              30
            ]
          },
          "convertTrial": {},
          "trialDays": 0,
          "changeIp": false,
          "selectReplacement": false,
          "customCredentials": true,
          "randomCredentials": true,
          "maxBatchSize": 100
        },
        "groupId": null
      }
    ],
    "page": 1,
    "pageSize": 20,
    "total": 1
  }
}

错误与重试

读取请求遇到 429 按 Retry-After 等待；500/503 可有限重试。分组创建结果不明时先查询分组列表；移动同一目标可安全重试。

错误码、HTTP 状态、错误响应字段及恢复方式统一见错误码与处理建议。

API 文档静态 API 概览API 文档查询静态实例列表

这篇内容解决了你的问题吗？

反馈只用于改进公开文档，不会提交账号或请求信息。