04-API 提取与代码接入

分类：代理提取　|　更新日期：2026-09-14

五步完成 API 接入：白名单 → 参数 → 链接 → 代码 / 客户端 → 运维，每步含界面位置与校验点。

本页目录

第一步：添加白名单（API 提取的硬性前置）
第二步：设置提取参数并生成链接
第三步：用代码调用提取接口
第四步：把 API 提取接到指纹浏览器
第五步：安全与运维建议

API 提取不使用子账号，而是用「app_key + IP 白名单」鉴权，适合自研程序与支持“API 提取”模式的指纹浏览器。本页按“白名单 → 参数 → 代码 → 客户端 → 运维”五步展开，每步都给出界面位置与校验点。

① 添加白名单 → ② 设置提取参数 → ③ 生成链接 → ④ 程序 / 客户端接入 → ⑤ 校验与运维

两类前置条件 ① 网络：设备前置节点必须是境外出口；② 白名单：把该前置节点的出口 IP 加入白名单，否则链接会返回鉴权失败或空结果。

第一步：添加白名单（API 提取的硬性前置）

进入白名单管理
- 界面位置：动态住宅代理 → 代理使用 → 白名单管理
- 怎么操作：点击「白名单管理」标签。
- 预期结果：页面显示「本机 IP」、「添加到白名单」按钮与已添加列表，并提示可添加的条数上限。
确认前置节点的真实出口 IP
- 界面位置：页面上的「本机 IP」或本机终端
- 怎么操作：在真正发起请求的那台机器 / 那个前置环境里执行 curl -s api.ip.cc，记录返回的 IP 与国家。
- 预期结果：得到的 IP 与页面显示的「本机 IP」一致（若前置于代理节点，通常不一致，以命令结果为准）。
把该 IP 加入白名单
- 界面位置：「添加到白名单」按钮，或下方输入框 +「添加」
- 怎么操作：一键添加，或手工填写 IP 后点「添加」；建议在备注中写明用途与日期，便于后续清理。
- 预期结果：列表出现该 IP，添加时间与备注正确。
复核白名单
- 界面位置：白名单列表（IP 地址 / 添加时间 / 备注 / 操作）
- 怎么操作：确认没有多余条目；不再使用的条目及时删除。
- 提示：白名单最多 10 个 IP，请为每个前置节点单独登记用途。

# 确认真实出口国家/地区与 IP（用于核对白名单是否填对）
curl -s -m 15 api.ip.cc

看红色标注 1—3 的先后顺序　进入「白名单管理」→ 查看本机 IP → 用命令行确认真实出口；示例中本机出口为 SG（新加坡）

看「最多可添加 10 个 IP 白名单」提示　一键「添加到白名单」，或手工填写后点「添加」；页面会提示已添加数量与上限

看备注与添加时间两列　示例中已添加 2 条 IP 白名单，其中一条备注为“本机IP”，可编辑或删除

前置 IP 会变，白名单必须同步 若你的海外前置是动态 IP（家宽定时重播、动态出口节点、移动网络），出口 IP 变化后 API 提取会立刻失效。建议：① 为前置节点绑定固定出口 IP；② 或改用账密认证方式，避免依赖白名单。

第二步：设置提取参数并生成链接

切换到「API 提取」标签
- 界面位置：动态住宅代理 → 代理使用 → API 提取
- 怎么操作：点击标签，页面会保留上一次的参数配置。
- 预期结果：标签高亮，右侧出现 API 链接区域。
设置提取数量
- 界面位置：「提取数量」输入框
- 怎么操作：自建程序按并发需要填写（最多 500）；配置到指纹浏览器时必须填 1。
- 预期结果：结果链接中的 num= 与填写值一致。
选择国家 / 州 / 城市
- 界面位置：「选择国家/地区 / 选择州 / 选择城市」下拉框
- 怎么操作：按目标业务区域逐级选择；不需要定向时保留随机 / 全球混播。
- 预期结果：链接中的 cc / state / city 与选择一致。
设置 IP 时效
- 界面位置：「IP 时效」下拉框
- 怎么操作：1—120 分钟；短时效适合轮换采集，长时效适合会话延续。
- 预期结果：链接中的 life= 与所设时长一致。
选择数据格式与协议
- 界面位置：「数据格式」「代理协议」下拉框
- 怎么操作：程序解析建议 json，命令行建议 txt；协议只支持 http / socks5，按目标端选择。
- 预期结果：链接中的 format=、protocol= 与选择一致。
选择分隔符
- 界面位置：「分隔符」下拉框
- 怎么操作：按脚本解析习惯选择换行回车 / 换行 / 回车 / Tab。
- 提示：多条结果粘连成一行，通常是分隔符与解析方式不匹配导致的。
点击「生成链接」并复制
- 界面位置：右侧「API 链接」区域
- 怎么操作：点「生成链接」→ 点「复制」；也可点「打开链接」在浏览器预览返回内容。
- 预期结果：浏览器打开链接能看到 IP 与端口列表（txt 为多行，json 为结构化数据）。

看左右两栏的对应关系　左侧设置参数，右侧给出 API 链接与「复制 / 打开链接」按钮

看红色标注 1—5　进入 API 提取 → 设置提取数量 → 选择国家 / 州 / 城市 → 生成链接 → 复制或打开链接

看链接与「复制 / 打开链接」按钮　可在浏览器直接打开预览结果，也可复制到程序或指纹浏览器中使用

参数	含义	填写建议
提取数量 / `num`	单次返回的 IP 数量，最多 500 个	自建程序按需批量；配置到指纹浏览器时必须为 1。
国家 / 地区 / 州 / 城市	IP 的地理定向范围	粒度可为「国家」「国家 + 州」「国家 + 州 + 城市」；不需要定向时选择随机 / 全球混播。
IP 时效 / `life`	单个 IP 的最长可用时间，1—120 分钟	短时效更适合轮换型采集；长时效适合需要会话延续的任务。
数据格式 / `format`	`txt` 或 `json`	程序解析用 `json`；命令行或简单脚本用 `txt`。
代理协议 / `protocol`	返回结果适配 http 与 socks5（仅这两种）	按目标端选择；指纹浏览器通常用 socks5 或 http；其它协议不支持。
分隔符 / `lb`	多条结果的分隔方式（换行回车 / 换行 / 回车 / Tab）	按脚本解析习惯选择，避免多条粘连成一个长字符串。

链接结构逐段解释

https://api.duckip.cn/web_v1/ip/get-ip-v3?app_key=XXXXXX&pt=X&num=2&cc=DE&state=BAVARIA&city=NUREMBERG&life=30&lb=%5Cn&format=txt&protocol=1

参数	说明
`app_key`	开放的应用密钥，可在控制台个人中心 / API 提取页获取。
`pt`	产品类型标识，由控制台生成，请勿手工修改。
`num`	单个 IP 提取数量，最多 500 个。
`life`	单个 IP 地址最大可用时间，最大 120 分钟。
`cc`	国家 / 地区代码，例如 `DE`、`US`、`GB`。
`state`	州 / 省代码，例如 `BAVARIA`、`ALASKA`。
`city`	城市代码，例如 `NUREMBERG`、`ANCHORAGE`。
`format`	返回数据格式：`txt` 或 `json`。
`protocol`	代理协议：`1` 表示 http 与 socks5。
`lb`	多条结果的分隔符：换行回车 / 换行 / 回车 / Tab。

第三步：用代码调用提取接口

下面示例演示「调用 API 拿到 IP → 用该 IP 访问目标站点」的完整闭环。各语言的差异只在代理设置部分，逻辑一致。

curl -sS "https://api.duckip.cn/web_v1/ip/get-ip-v3?app_key=你的app_key&num=1&cc=DE&state=BAVARIA&city=NUREMBERG&life=30&format=txt&protocol=1&lb=1"

# 拿到 ip:port 后，用它访问目标站点验证
curl -sS -m 20 -x "http://ip:port" https://api.ip.cc

import requests

API = ("https://api.duckip.cn/web_v1/ip/get-ip-v3"
       "?app_key=你的app_key&num=1&cc=DE&state=BAVARIA&city=NUREMBERG"
       "&life=30&format=json&protocol=1&lb=1")

resp = requests.get(API, timeout=15)
print(resp.text)                      # 先打印，确认实际返回结构

item = resp.json()["data"][0]         # 字段名以实际返回为准
proxy = "http://{}:{}".format(item["ip"], item["port"])
# 若返回中包含账号密码，请拼成 http://user:pass@ip:port

r = requests.get("https://api.ip.cc/",
                 proxies={"http": proxy, "https": proxy}, timeout=20)
print(r.json())

const https = require("https");

const API = "https://api.duckip.cn/web_v1/ip/get-ip-v3?app_key=你的app_key&num=1&cc=DE&life=30&format=json&protocol=1&lb=1";

https.get(API, (res) => {
  let body = "";
  res.on("data", (chunk) => (body += chunk));
  res.on("end", () => {
    const data = JSON.parse(body);
    console.log(data);            // 打印后按真实字段取 ip / port
  });
}).on("error", console.error);

<?php
// 第一步：调用提取接口，拿回一行 ip:port（调用方 IP 需在白名单内）
$ch = curl_init("https://api.duckip.cn/web_v1/ip/get-ip-v3?app_key=YOUR_APP_KEY&num=1&cc=DE&life=30&format=txt&protocol=1&lb=1");
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 20]);
$text = curl_exec($ch);
if ($text === false) {
    exit("提取失败: " . curl_error($ch));
}
curl_close($ch);

$ipPort = trim(explode("\n", trim($text))[0]);   // 形如 ip:port
echo "提取到代理: {$ipPort}\n";

// 第二步：用提取到的 ip:port 访问目标站点
$ch = curl_init("https://api.ip.cc/");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROXY          => $ipPort,
    CURLOPT_PROXYTYPE      => CURLPROXY_HTTP,
    CURLOPT_TIMEOUT        => 20,
]);
$body = curl_exec($ch);
if ($body === false) {
    exit("访问失败: " . curl_error($ch));
}
echo curl_getinfo($ch, CURLINFO_HTTP_CODE) . " " . $body . PHP_EOL;
curl_close($ch);

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
	"strings"
)

func main() {
	// 把整条链接从控制台复制过来；app_key 用 ASCII 字符，避免 URL 解析异常
	api := "https://api.duckip.cn/web_v1/ip/get-ip-v3?app_key=YOUR_APP_KEY&num=1&cc=DE&life=30&format=txt&protocol=1&lb=1"

	resp, err := http.Get(api)
	if err != nil {
		fmt.Println("提取失败:", err)
		return
	}
	defer resp.Body.Close()
	raw, err := io.ReadAll(resp.Body)
	if err != nil {
		fmt.Println("读取失败:", err)
		return
	}

	ipPort := strings.TrimSpace(strings.Split(string(raw), "\n")[0]) // 形如 ip:port
	proxyURL, err := url.Parse("http://" + ipPort)
	if err != nil {
		fmt.Println("代理地址解析失败:", err)
		return
	}

	// 用提取到的 ip:port 作为代理访问目标站点
	client := &http.Client{Transport: &http.Transport{Proxy: http.ProxyURL(proxyURL)}}
	r, err := client.Get("https://api.ip.cc/")
	if err != nil {
		fmt.Println("经代理访问失败:", err)
		return
	}
	defer r.Body.Close()
	body, _ := io.ReadAll(r.Body)
	fmt.Println(r.Status, string(body))
}

import java.net.InetSocketAddress;
import java.net.ProxySelector;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

public class Demo {
    public static void main(String[] args) throws Exception {
        // app_key 用 ASCII 字符（URI.create 不接受未编码的非 ASCII 字符）
        String api = "https://api.duckip.cn/web_v1/ip/get-ip-v3?app_key=YOUR_APP_KEY&num=1&cc=DE&life=30&format=txt&protocol=1&lb=1";

        HttpClient plain = HttpClient.newHttpClient();
        HttpResponse<String> extract = plain.send(
                HttpRequest.newBuilder(URI.create(api)).timeout(java.time.Duration.ofSeconds(20)).build(),
                HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        if (extract.statusCode() != 200) {
            System.out.println("提取失败: HTTP " + extract.statusCode() + " " + extract.body());
            return;
        }
        String ipPort = extract.body().trim().split("\\R")[0];     // 形如 ip:port
        System.out.println("提取到代理: " + ipPort);

        String[] hp = ipPort.split(":");
        HttpClient client = HttpClient.newBuilder()
                .proxy(ProxySelector.of(new InetSocketAddress(hp[0], Integer.parseInt(hp[1]))))
                .connectTimeout(java.time.Duration.ofSeconds(20))
                .build();

        HttpResponse<String> resp = client.send(
                HttpRequest.newBuilder(URI.create("https://api.ip.cc/")).timeout(java.time.Duration.ofSeconds(20)).build(),
                HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        System.out.println(resp.statusCode() + " " + resp.body());
    }
}

返回字段以实际为准 不同套餐 / 版本的返回结构可能略有差异。首次接入时请先打印完整响应，确认字段名（如 ip、port、账号密码字段等）后再写解析逻辑，不要照抄示例中的键名。

第四步：把 API 提取接到指纹浏览器

确认提取数量为 1
- 界面位置：控制台「API 提取」页
- 怎么操作：把提取数量改为 1 后再复制链接。
- 预期结果：链接中 num=1。
在环境的代理设置中选择「API 提取」方式
- 界面位置：指纹浏览器的新建 / 编辑环境 → 代理信息
- 怎么操作：代理方式选择「API 提取」或「使用代理平台 API 提取链接提取」，粘贴链接。
- 填写内容：服务商可保持“通用”；代理协议按目标端选择；提取方式可选“每次打开窗口都提取新 IP”。
设置刷新间隔与去重
- 界面位置：「刷新 URL」「校验重复」等选项
- 怎么操作：按业务设置刷新间隔；开启“校验重复”可避免同一环境拿到历史上用过的 IP。
- 提示：校验重复会带来额外提取次数，注意与流量 / 额度预算平衡。
点击「测试提取 / 检查代理」
- 界面位置：链接输入框右侧按钮
- 怎么操作：测试通过后再保存并打开环境。
- 预期结果：返回成功提示，并显示出口国家 / 城市。

看红色标注 1—4 与「校验重复」说明　代理方式选「使用代理IP平台API提取链接提取」→ 选择服务商与协议 → 粘贴提取链接 → 点「测试提取」

看「代理方式」与「代理检测」　可选择自定义代理或 API 提取方式，并设置代理类型、主机、端口、账号与密码

看“连接测试成功”与出口国家　示例中填入 socks5 代理后点击「检查代理」，返回“连接测试成功”与出口国家

接入指纹浏览器的两个前提 ① 提取数量必须为 1，否则同一环境的出口 IP 会漂移；② 白名单必须与前置节点出口 IP 一致，前置 IP 变化后要同步更新。

第五步：安全与运维建议

风险点	建议
`app_key` 泄露	不要把完整提取链接写进前端代码、客户端安装包或公开仓库；用后端中转或环境变量保存。
白名单被滥用	白名单最多 10 个 IP，请为不同前置节点分别添加并在备注中登记用途，定期清理不再使用的条目。
频繁提取消耗额度	按业务节奏缓存 IP（例如在 `life` 内复用），避免每次请求都重新提取。
IP 归属异常	先用多个检测站点交叉验证，再判断是参数问题还是第三方 IP 库滞后。
异常时无日志	记录提取时间、区域、返回 IP 与目标站点响应，便于定位问题在提取侧还是目标站点侧。

需要长期稳定的出口？ 如果业务对出口 IP 稳定性要求高（账号类、支付类、店铺类），建议使用账密认证 + 静态住宅代理，或为动态住宅代理固定 session 保持粘性，而不是依赖 API 轮换。

相关文档 代理使用说明（命令行 / 代码 / 客户端接入） | 参数详解与生成格式