理解代理IP API的基本概念
当你需要让程序通过不同的网络地址去访问目标网站时，代理IP的API就成了关键工具。简单来说，API就是一个你与天启代理服务器进行“对话”的专用通道。你按照特定的格式（接口文档）发送一个请求，天启代理的服务就会理解你的意图，并返回一个或多个可用的代理IP地址给你。这个过程就像自动售货机：你选择商品并付款（发送带参数的API请求），它就会吐出对应的饮料（返回代理IP）。对于天启代理这样的服务商，其API设计通常追求简洁高效，目的是让你能快速集成，把精力放在核心业务上。
如何获取并解读天启代理的接口文档
要调用API，第一步是找到并看懂“说明书”，也就是接口文档。通常，在天启代理的用户后台或技术文档页面，你可以找到详细的API文档。一份清晰的文档会包含以下几个核心部分：
1. 请求地址（Endpoint）：这是API的网址，所有请求都发往这个地址。
2. 请求参数：这是你告诉API具体需求的方式。常见参数包括：
- 订单号/密钥（key）：你的身份凭证，用于鉴权。
- 提取数量（num）：一次想获取几个IP。
- 协议类型（protocol）：指定需要HTTP、HTTPS还是SOCKS5代理。
- IP存活时长（time）：根据天启代理提供的套餐，选择短效或长效IP。
- 返回格式（format）：通常支持json、txt等，方便程序解析。
- 地区筛选（city/region）：可以指定需要哪个城市的IP节点。
3. 返回结果：文档会说明API成功或失败时返回的数据结构。成功时，你会得到一个IP列表，包含IP地址、端口、协议、过期时间等信息；失败时，会有对应的错误代码和提示信息。
4. 调用频率限制：为了避免滥用，API通常有每秒或每分钟的调用次数限制，文档里会明确说明。
解读文档时，不必一次性理解所有参数。先关注必填参数，如密钥和提取数量，实现基础功能，再逐步尝试可选参数来满足更精细的需求。
一步步调用API：从获取IP到使用
我们以一个典型的“获取动态短效IP”的流程为例，拆解步骤：
第一步：准备你的API密钥。登录天启代理后台，在“API接口”或类似栏目中找到你的唯一密钥（一串由字母数字组成的字符串），这是所有调用的基础。
第二步：拼接请求URL。根据文档，将请求地址和参数组合成一个完整的URL。例如，一个最简单的获取IP的请求可能长这样：
https://api.tianqiip.com/getip?key=你的密钥&num=1&format=json这个请求的意思是：向天启代理的API地址，使用我的密钥，申请1个IP，并以json格式返回。
第三步：发送HTTP请求并处理响应。在你的程序中，使用任何HTTP客户端（如Python的requests库、Java的OkHttp等）发送这个GET请求。服务器会返回一个JSON响应，类似：
{
"code": 0,
"msg": "success",
"data": [{"ip": “1.2.3.4", "port": 1234, "expire_time": "2023-10-01 12:00:00"}]
}第四步：在程序中使用代理IP。解析返回的JSON，拿到ip和port，将其配置到你的爬虫、数据采集工具或业务软件中。例如，配置为1.2.3.4:1234。
多语言代码示例
下面提供几个主流语言的简单示例，展示如何调用天启代理API并应用获取到的IP。
Python 示例
import requests
import json
1. 定义API请求参数
api_url = "https://api.tianqiip.com/getip"
params = {
'key': 'YOUR_API_KEY_HERE', 替换为你的天启代理API密钥
'num': 2, 提取2个IP
'format': 'json', 返回json格式
'protocol': 'http' 指定HTTP协议
}
2. 发送请求获取IP
try:
response = requests.get(api_url, params=params, timeout=10)
result = response.json()
if result.get('code') == 0: 判断请求成功
ip_list = result.get('data', [])
for proxy_info in ip_list:
proxy_ip = f"{proxy_info['ip']}:{proxy_info['port']}"
proxies = {"http": f"http://{proxy_ip}", "https": f"http://{proxy_ip}"}
3. 使用获取的代理IP访问一个测试网站
test_resp = requests.get('http://httpbin.org/ip', proxies=proxies, timeout=5)
print(f"代理IP {proxy_ip} 生效， 当前出口IP: {test_resp.json()['origin']}")
else:
print(f"获取IP失败: {result.get('msg')}")
except Exception as e:
print(f"请求过程中出现错误: {e}")Java 示例 (使用 OkHttp)
import okhttp3.;
import org.json.JSONObject;
import java.io.IOException;
public class TianQiProxyDemo {
public static void main(String[] args) {
OkHttpClient client = new OkHttpClient();
// 1. 构建请求URL
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://api.tianqiip.com/getip").newBuilder();
urlBuilder.addQueryParameter("key", "YOUR_API_KEY_HERE");
urlBuilder.addQueryParameter("num", "1");
urlBuilder.addQueryParameter("format", "json");
Request apiRequest = new Request.Builder().url(urlBuilder.build()).build();
try (Response response = client.newCall(apiRequest).execute()) {
if (response.isSuccessful() && response.body() != null) {
String responseBody = response.body().string();
JSONObject jsonResult = new JSONObject(responseBody);
// 2. 解析响应
if (jsonResult.getInt("code") == 0) {
JSONObject ipData = jsonResult.getJSONArray("data").getJSONObject(0);
String proxyHost = ipData.getString("ip");
int proxyPort = ipData.getInt("port");
String proxyStr = proxyHost + ":" + proxyPort;
// 3. 使用代理创建新的客户端并发起请求
Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress(proxyHost, proxyPort));
OkHttpClient proxyClient = client.newBuilder().proxy(proxy).build();
Request testRequest = new Request.Builder().url("http://httpbin.org/ip").build();
try (Response testResponse = proxyClient.newCall(testRequest).execute()) {
System.out.println("使用代理IP: " + proxyStr);
System.out.println("测试返回: " + testResponse.body().string());
}
} else {
System.out.println("获取IP失败: " + jsonResult.getString("msg"));
}
}
} catch (IOException e) {
e.printStackTrace();
}
}
}Node.js 示例 (使用 axios)
const axios = require('axios');
const { HttpsProxyAgent } = require('https-proxy-agent'); // 需要安装 https-proxy-agent
async function getAndUseProxy() {
const apiKey = 'YOUR_API_KEY_HERE';
const apiUrl = `https://api.tianqiip.com/getip?key=${apiKey}&num=1&format=json`;
try {
// 1. 调用天启代理API获取IP
const apiResponse = await axios.get(apiUrl);
const result = apiResponse.data;
if (result.code === 0) {
const proxyInfo = result.data[0];
const proxyUrl = `http://${proxyInfo.ip}:${proxyInfo.port}`;
console.log(`获取到代理IP: ${proxyUrl}`);
// 2. 创建代理Agent
const agent = new HttpsProxyAgent(proxyUrl);
// 3. 使用代理发起请求
const testResponse = await axios.get('http://httpbin.org/ip', {
httpsAgent: agent,
httpAgent: agent
});
console.log('通过代理访问，当前IP为:', testResponse.data.origin);
} else {
console.error('获取IP失败:', result.msg);
}
} catch (error) {
console.error('请求出错:', error.message);
}
}
getAndUseProxy();常见问题与解答（QA）
Q1: 调用API返回错误代码，比如“10001”或“10002”，是什么意思？
A1: 这些是API定义的错误码。通常“10001”代表密钥错误或为空，“10002”可能代表余额不足或套餐已用完。具体含义需要查阅天启代理最新的接口文档，里面会有详细的错误码说明。遇到错误时，首先核对密钥是否正确，然后检查账户状态。
Q2: 获取到的代理IP连接失败或速度很慢怎么办？
A2: 使用ping或telnet命令测试该IP和端口的网络连通性。如果连接不通，可能是IP已过期（特别是短效IP）。天启代理的API返回数据中通常包含IP的过期时间（expire_time），请注意判断。如果速度慢，可以尝试在API请求中指定不同的地区节点，选择离你目标网站或你自己网络更近的节点，天启代理全国200+城市节点的优势这时就能体现出来。
Q3: 我的程序需要高并发使用大量IP，API调用有什么注意事项？
A3: 高并发场景下，切忌在每次需要IP时都同步调用API，这极易触发频率限制并造成延迟。正确的做法是：单独部署一个IP获取与调度服务。这个服务定时（如每秒）从天启代理API批量获取一批IP，存入本地数据库或内存队列（如Redis）。你的业务程序则从这个本地队列中消费IP。这样既避免了API限流，也大大降低了获取IP的延迟。天启代理的企业级服务支持高并发调用，配合这种架构能稳定支撑业务。
Q4: 如何保证使用的代理IP是有效的？
A4: 建立IP有效性验证机制。从API获取IP后，在使用前，先用它快速访问一个稳定的、已知能通的网站（如百度首页）进行验证。对于长效静态IP，也需要定时（如每5分钟）验证其有效性，并及时从IP池中移除失效的IP。天启代理虽然提供高可用率的IP，但网络环境复杂，客户端自建验证环节是提升业务稳定性的最佳实践。
Q5: 天启代理支持哪些授权方式？我该如何选择？
A5: 天启代理主要支持终端IP授权（白名单）和账号密码授权两种方式。如果你的程序固定从少数几台服务器调用，使用终端IP授权最方便，直接在后台配置服务器公网IP即可，调用API时无需额外参数。如果你的程序部署环境不固定（如爬虫跑在多家云服务器），则适合使用账号密码授权，在连接代理时需填写用户名和密码。你可以在天启代理的用户后台根据业务场景进行配置。
