SuperNova Proxy SuperNova
登录 注册 →

开发者API文档

使用我们的API优化您的工作流程或用于代理转售

开发者API文档

通过API可让您的服务与我们的系统对接。当您的软件支持API调用或需要以自有品牌转售代理时，此功能非常实用。请先登录账户，在本页顶部找到API密钥生成表单。所有API请求均需使用该密钥。每个账户仅允许存在一个有效API密钥，您可随时刷新密钥，旧密钥将自动失效。

使用建议：

1. 国家、州/地区及城市列表至少每分钟更新一次，或在创建/更新代理链接前务必更新

2. 代理链接格式极少变更。如需特殊格式支持请联系客服

3. 请严格遵守子账户限制！若转售代理链接，必须设置限额保护，否则可能造成账户资金损失

4. 可使用自有域名代替我们的连接网关：通过ping命令获取当前网关IP后，更新DNS记录指向该IPv4地址。我们仅支持IPv4连接并自动屏蔽IPv6流量，需要协助请联系客服。

基础信息

所有请求需在header中添加API密钥：

Content-Type: application/json
Authorization: ApiKey 00000000-0000-0000-0000-000000000000

错误响应将包含HTTP状态码、简短描述及'success'=false标志：

{
  "data": {
    "general": "API key not recognized or user is blocked"
  },
  "success": false
}

所有API端点均实施速率限制。频繁请求将触发429错误，需提升限额请联系客服。响应header中将显示剩余可用请求次数：

< X-Ratelimit-Limit: 5
< X-Ratelimit-Remaining: 4
< X-Ratelimit-Reset: 15

账户余额

获取当前账户余额的请求示例：

curl -X GET https://supernovanet.org/api/v1/balance -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000" ### Get Balance
GET https://supernovanet.org/api/v1/balance
Authorization: ApiKey 00000000-0000-0000-0000-000000000000

请求成功的响应内容如下：

HTTP/1.1 200 OK
Date: Thu, 01 Apr 2025 00:00:00 GMT
Content-Type: application/json
Content-Length: 73
X-Ratelimit-Limit: 5
X-Ratelimit-Remaining: 4
X-Ratelimit-Reset: 15
Connection: close

{
  "data": {
    "balance_string": "$14.97",
    "balance_float": 14.97
  },
  "success": true
}

支持国家

获取可用国家列表的请求。注意：该列表包含所有代理类型的国家，等效于选择全部代理类型，不支持按类型筛选。

curl -X GET https://supernovanet.org/api/v1/inventory/countries -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000"

请求成功的响应内容如下：

{
    "data": [{
        "name": "France",
        "iso": "FR"
    }, 
    ... // More countries in the list
    {
        "name": "Latvia",
        "iso": "LV"
    }],
    "success": true
}

可用州/地区与国家

获取指定国家的州/地区列表。注意：该列表包含所有代理类型（移动、住宅、混合）的地区数据，等效全选代理类型且不可筛选。未指定国家时返回错误，指定国家后始终返回全部州/地区。

curl -X GET "https://supernovanet.org/api/v1/inventory/targeting?country=US" -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000"

可通过State ID筛选指定州内的城市：

curl -X GET "https://supernovanet.org/api/v1/inventory/targeting?country=US&state=4361885" -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000"

请求成功的响应内容如下：

{
    "data": {
        "states": [{
                "name": "Maryland",
                "id": 4361885
            },
            ... // More states
            {
                "name": "Illinois",
                "id": 4896861
            }
        ],
        "cities": [{
                "name": "Kissimmee",
                "id": 4160983
            },
            ... // More cities
            {
                "name": "Ellsworth",
                "id": 4963692
            }
        ]
    },
    "success": true
}

代理链接格式

获取代理链接格式的请求（后续生成链接需使用格式ID！）

curl -X GET https://supernovanet.org/api/v1/formats -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000"

请求成功的响应内容如下：

{
    "data": [{
        "id": 1,
        "name": "login:pass@host:port",
        "description": "No scheme: login:pass@host:port",
        "format": "{login}:{password}@{host}:{port}"
    }, 
    ... // More formats in the list
    {
        "id": 2,
        "name": "login:pass@ip:port",
        "description": "No scheme: login:pass@ip:port",
        "format": "{login}:{password}@{ip}:{port}"
    }],
    "success": true
}

活跃子账户

子账户可视为您系统的用户，支持活跃/归档状态，可设置有效期、消费额和流量限制。子账户是系统中统计使用情况的核心实体。

禁止将同一子账户用于多用户，因其共享连接密码和所有限额！

获取活跃子账户列表请求。可选参数p（页码）和l（每页数量），默认启用分页，单页最大数量(l)为300。

curl -X GET "https://supernovanet.org/api/v1/subaccounts/active?p=1&l=30" -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000"

请求成功的响应内容如下：

{
    "data": {
        "limit": 30,
        "page": 1,
        "total_rows": 1,
        "total_pages": 1,
        "rows": [{
            "port": "YOUR_SUBACCOUNT_IDENTIFICATOR", // Main identificator of your Subaccount
            "name": "My List №1",
            "total_traffic": 0, // In Bytes
            "total_spend": 0, // In Dollars
            "status": 1, // See below 
            "amount_limit": 123, // In Dollars
            "traffic_limit": 1, // In Gigabytes
            "date_limit": "2025-04-20T00:00:00+00:00",
            "last_bytes_at": null,
            "created_at": "2025-04-16T17:35:13.313+00:00"
        }]
    },
    "success": true
}

子账户状态类型：


WORKING = 0
PAUSED = 1
PAUSED DUE TO SUBACCOUNT LIMITS = 2
PAUSED DUE TO NO FUNDS = 3

归档子账户

无需使用的子账户可归档。获取归档子账户列表请求，可选参数p（页码）和l（每页数量），单页最大数量300。

curl -X GET "https://supernovanet.org/api/v1/subaccounts/archived?p=1&l=30" -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000"

请求成功的响应内容如下：

{
    "data": {
        "limit": 30,
        "page": 1,
        "total_rows": 1,
        "total_pages": 1,
        "rows": [{
            "port": "YOUR_SUBACCOUNT_IDENTIFICATOR", // Main identificator of your Subaccount
            "name": "My List №1",
            "total_traffic": 0, 
            "total_spend": 0, 
            "status": 1, // Status automatically set to Paused when you archive your subaccount!
            "amount_limit": 123, 
            "traffic_limit": 1,
            "date_limit": "2025-04-20T00:00:00+00:00",
            "last_bytes_at": null,
            "created_at": "2025-04-10T17:35:13.313+00:00",
            "archived_at":"2025-04-16T18:20:44.024+00:00" // Pay attention to new field in archived
        }]
    },
    "success": true
}

请求成功的响应内容如下：

添加子账户时可设置限额和密码，未指定密码时由系统自动生成

转售代理时请务必设置限额！

curl -X POST https://supernovanet.org/api/v1/subaccounts/add \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000" \
  -d '{
    "name": "Test Subaccount",
    "password": "testpassword123",
    "amount_limit": 100.0,
    "traffic_limit": 1024.0,
    "date_limit": "2025-12-31"
  }'
以下为各请求字段的说明：
{
  "name": "Test Subaccount", // Name of your Subaccount (for your convenience)
  "password": "testpassword123", // Password. Leave it blank and we will generate it by our own
  "amount_limit": 100.0, // Amount in US dollars after this subaccount will be stopped
  "traffic_limit": 1024.0, // Amount in Gigabytes after this subaccount will be stopped
  "date_limit": "2025-12-31" // Date after this subaccount will be stopped (last working date)
}'

请求成功的响应内容如下：

{
  "data": {
    "port": "YOUR_SUBACCOUNT_IDENTIFICATOR", // This identificator will be required to edit port later!
    "password": "testpassword123",
    "name": "Test Subaccount",
    "total_traffic": 0,
    "total_spend": 0,
    "status": 0,
    "amount_limit": 100,
    "traffic_limit": 1024,
    "date_limit": "2025-12-31T00:00:00+00:00",
    "last_bytes_at": null,
    "created_at": "2025-04-01T12:00:00.000+00:00"
  },
  "success": true
}

编辑子账户（列表或端口）

编辑子账户需提供端口标识符！请求格式相同但需添加port字段

未指定'port'字段时将创建新子账户！

curl -X POST https://supernovanet.org/api/v1/subaccounts/edit \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000" \
  -d '{
    "port": "YOUR_SUBACCOUNT_IDENTIFICATOR",
    "name": "Test Subaccount",
    "password": "testpassword123",
    "amount_limit": 100.0,
    "traffic_limit": 1024.0,
    "date_limit": "2025-12-31"
  }'
以下为各请求字段的说明：
{
  "port": "YOUR_SUBACCOUNT_IDENTIFICATOR", // Identificator of your Subaccount. Mandatory field for edit subaccount.
  "name": "Test Subaccount", // Name of your Subaccount (for your convenience)
  "password": "testpassword123", // Password. Leave it blank and we will generate it by our own
  "amount_limit": 100.0, // Amount in US dollars after this subaccount will be stopped
  "traffic_limit": 1024.0, // Amount in Gigabytes after this subaccount will be stopped
  "date_limit": "2025-12-31" // Date after this subaccount will be stopped (last working date)
}'

请求成功的响应内容如下：

{
  "data": {
    "port": "YOUR_SUBACCOUNT_IDENTIFICATOR", // This identificator will be required to edit port later!
    "password": "testpassword123",
    "name": "Test Subaccount",
    "total_traffic": 0,
    "total_spend": 0,
    "status": 0,
    "amount_limit": 100,
    "traffic_limit": 1024,
    "date_limit": "2025-12-31T00:00:00+00:00",
    "last_bytes_at": null,
    "created_at": "2025-04-01T12:00:00.000+00:00"
  },
  "success": true
}

启动/停止/归档/恢复

可实时管理子账户状态，变更将立即影响代理服务可用性。

curl -X POST https://supernovanet.org/api/v1/subaccounts/command \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000" \
  -d '{
    "port": "YOUR_SUBACCOUNT_IDENTIFICATOR",
    "command": "start"
  }'
以下为各请求字段的说明：
{
  "port": "YOUR_SUBACCOUNT_IDENTIFICATOR", // Identificator of your Subaccount. Mandatory field for edit subaccount.
  "command": "start" // Possible values of command: 'archive' 'restore' 'pause' 'start'
}'

请求成功的响应内容如下：

{
  "data": "ok",
  "success": true
}

生成代理连接链接

生成代理链接需指定子账户、链接类型、数量（最多10000）、轮换类型、国家（必填）、州（可选）、城市（可选）

注意请求URL中包含子账户标识符（'port'值）！

curl -X POST https://supernovanet.org/api/v1/subaccounts/YOUR_SUBACCOUNT_IDENTIFICATOR/generate-links \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000" \
  -d '{
    "link_type": 7,
    "mob": true,
    "res": true,
    "mix": true,
    "country": "US",
    "city": 123,
    "state": 45,
    "session": "rotate",
    "quantity": 1000
}'
以下为各请求字段的说明：
{
  "link_type": 7, // Mandatory. This ID is from Proxy Link Formats
  "mob": true, // Mandatory. If you need Mobile proxies. Please pay attention that one of mob, res or mix fields must be true!
  "res": true, // Mandatory. If you need Residential proxies. Please pay attention that one of mob, res or mix fields must be true!
  "mix": true, // Mandatory. If you need Mixed proxies. Please pay attention that one of mob, res or mix fields must be true!
  "country": "US", // Mandatory! Country from list of available ones
  "city": 123,  // Optional: city id from Available States/Regions and Countries. Ignored if no that City available.
  "state": 45, // Optional: city id from Available States/Regions and Countries. Ignored if no that State available.
  "session": "rotate", // Mandatory. Possible values: "rotate", "keep"
  "quantity": 1000 // Optional. Links quantity. By default is one. Up to 10000, but specify reasonable amount. 
}'

请求成功的响应内容如下：

{
  "data": [
    "http://YOUR_SUBACCOUNT_IDENTIFICATOR-iso-us-t-mrv-st-r-s-1cdvecqqnu:[email protected]:9090",
    "http://YOUR_SUBACCOUNT_IDENTIFICATOR-iso-us-t-mrv-st-r-s-xboz8dc60t:[email protected]:9090"
  ],
  "success": true
}