> 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 等模型的代理配置，以便于部署、监控和维护。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET 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?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.