> For the complete documentation index, see [llms.txt](https://docs.ipwo.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipwo.net/kai-fa-zhe-wen-dang/ai-agent-kai-fa/ru-he-zai-gemini-api-zhong-shi-yong-ipwo-dai-li.md).

# 如何在 Gemini API 中使用 IPWO 代理

在部分网络环境下，开发者可能需要通过代理服务器访问 Gemini API。通过配置 IPWO 住宅代理，您可以为 Gemini API 请求提供稳定的网络连接，并根据业务需求选择不同国家或地区的出口 IP。

本文将介绍如何在 Python 和 Node.js 环境中为 Gemini API 配置 IPWO 代理。

***

### 环境准备

开始之前，请确保您已经：

* 拥有 [IPWO 住宅代理账号](/readme/zhu-ce-deng-lu.md)
* [获取代理用户名和密码](/kai-fa-zhe-wen-dang/kuai-su-kai-shi/huo-qu-dai-li-xin-xi.md)
* 获取代理服务器地址和端口
* 拥有 Gemini API Key

示例代理信息：

```
Proxy Host: us.ipwo.net
Proxy Port: 7878

Username: username
Password: password
```

***

### 安装 Gemini SDK

#### Python

```bash
pip install google-genai httpx
```

#### Node.js

```bash
npm install @google/genai https-proxy-agent
```

***

### Python 示例

Gemini SDK 支持通过环境变量使用代理。

```python
import os
from google import genai

os.environ["HTTP_PROXY"] = "http://username:password@us.ipwo.net:7878"
os.environ["HTTPS_PROXY"] = "http://username:password@us.ipwo.net:7878"

client = genai.Client(
    api_key="YOUR_GEMINI_API_KEY"
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Explain what a residential proxy is."
)

print(response.text)
```

***

### 使用 httpx 自定义代理

如果您的项目已经使用 httpx 管理网络请求，可以通过系统代理环境变量统一配置。

```python
import os

os.environ["HTTP_PROXY"] = "http://username:password@us.ipwo.net:7878"
os.environ["HTTPS_PROXY"] = "http://username:password@us.ipwo.net:7878"
```

随后正常调用 Gemini SDK 即可。

***

### Node.js 示例

通过 HTTPS Proxy Agent 配置代理访问 Gemini API。

```javascript
import { GoogleGenAI } from "@google/genai";
import { HttpsProxyAgent } from "https-proxy-agent";

const proxyAgent = new HttpsProxyAgent(
  "http://username:password@us.ipwo.net:7878"
);

process.env.HTTP_PROXY =
  "http://username:password@us.ipwo.net:7878";

process.env.HTTPS_PROXY =
  "http://username:password@us.ipwo.net:7878";

const ai = new GoogleGenAI({
  apiKey: process.env.GEMINI_API_KEY
});

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: "Explain what a residential proxy is."
});

console.log(response.text);
```

***

### 使用环境变量配置代理

部分应用程序和 AI 框架会自动读取系统代理配置。

#### Linux/macOS

```bash
export HTTP_PROXY=http://username:password@us.ipwo.net:7878
export HTTPS_PROXY=http://username:password@us.ipwo.net:7878
```

#### Windows

```cmd
set HTTP_PROXY=http://username:password@us.ipwo.net:7878
set HTTPS_PROXY=http://username:password@us.ipwo.net:7878
```

***

### 验证代理是否生效

建议在调用 Gemini API 前先测试代理连接。

```bash
curl -x "us.ipwo.net:7878" \
-U "username:password" \
ipinfo.io
```

如果返回代理出口 IP 及地理位置信息，则说明代理连接正常。

***

### 常见问题

#### Connection Timeout

可能原因：

* 网络无法访问代理节点
* 代理账号已过期
* 本地防火墙限制连接

建议：

* 更换代理节点测试
* 检查代理账户状态
* 使用 curl 验证代理连通性

***

#### Proxy Authentication Failed

可能原因：

* 用户名错误
* 密码错误
* 代理认证格式错误

请检查：

```
username
password
host
port
```

是否与控制台提供的信息一致。

***

#### Gemini API 返回 401 Unauthorized

此错误通常与 Gemini API Key 有关，而非代理配置问题。

请检查：

* API Key 是否有效
* API Key 是否配置正确
* Google AI Studio 项目是否已启用 Gemini API
* API 配额是否充足

***

#### Gemini API 返回 429 Too Many Requests

说明请求频率超过当前配额限制。

建议：

* 降低请求频率
* 增加重试机制
* 使用队列控制并发请求

***

### 最佳实践

* 长时间运行的 AI 应用建议使用 Sticky Session，提高连接稳定性。
* 将 API Key 和代理信息存储在环境变量中，避免硬编码。
* Docker、云服务器和自动化工作流环境建议统一配置系统代理。
* 对于高并发场景，建议增加重试机制和请求限流策略。
* 在多模型应用中统一管理 OpenAI、Claude、Gemini 的代理配置，降低维护成本。

***

### 相关阅读

完成 Gemini API 代理配置后，您可能还需要：

* [OpenAI SDK 使用代理](/kai-fa-zhe-wen-dang/ai-agent-kai-fa/ru-he-zai-openai-sdk-zhong-shi-yong-ipwo-dai-li.md)
* [LangChain 使用住宅代理](/kai-fa-zhe-wen-dang/ai-agent-kai-fa/ru-he-zai-langchain-xiang-mu-zhong-pei-zhi-ipwo-dai-li.md)
* [Browser Use 使用住宅代理](/kai-fa-zhe-wen-dang/ai-agent-kai-fa/ru-he-zai-browser-use-zhong-pei-zhi-ipwo-dai-li.md)
* [MCP 工具代理配置指南](/kai-fa-zhe-wen-dang/ai-agent-kai-fa/ru-he-wei-mcp-gong-ju-he-mcp-server-pei-zhi-ipwo-zhu-zhai-dai-li.md)
* [获取和配置住宅代理](/kai-fa-zhe-wen-dang/kuai-su-kai-shi/huo-qu-dai-li-xin-xi.md)
* [如何检测代理是否生效](/dai-li-jian-ce-yu-yin-si-an-quan/ru-he-jian-ce-dai-li-shi-fou-sheng-xiao.md)
* [407 Proxy Authentication Required](/kai-fa-zhe-wen-dang/chang-jian-cuo-wu/407-proxy-authentication-required.md)
* [超时 Timeout](/kai-fa-zhe-wen-dang/chang-jian-cuo-wu/chao-shi-timeout.md)

> 提示：如果您正在构建 AI Agent、多模型路由系统或自动化工作流，建议统一管理 Gemini、Claude、OpenAI 等模型的代理配置，以便于部署、监控和维护。