# 城市代理 API 与网关文档

> Banyan Proxies 文档：网关主机与端口、用于国家、城市、ASN 和会话的用户名分段、错误代码，以及经过测试的 curl、Python 和 Node.js 示例。

- URL: https://banyanproxies.com/zh/docs/
- 最后更新: 2026-10-18
- Publisher: Banyan Proxies (https://banyanproxies.com)

连接所需的一切：一个网关、一种用户名格式，以及可直接粘贴的测试示例。账号与订单 API 记录在[API 文档](https://banyanproxies.com/docs/api/)中。

**快速回答 — 如何连接 Banyan Proxies 住宅代理？**

连接 `gw.banyanproxies.com`，HTTP 和 HTTPS 使用端口 7777，SOCKS5 使用端口 7778，并配合您的代理密码和由各分段组成的用户名：`USERNAME-country-in-city-pune-asn-24560-session-a1-ttl-15`。只使用您需要的分段。每个套餐（1 GB 起价 US$1.88）都包含城市和 ASN 定位。

## 我可以使用哪些用户名分段？

完整格式：`USERNAME-country-{cc}-city-{city}-asn-{asn}-session-{id}-ttl-{minutes}`。请保持顺序；不需要的分段可以省略。

| 分段 | 示例 | 含义 |
| --- | --- | --- |
| `-country-<cc>` | `-country-id` | 两位 ISO 国家代码，小写 |
| `-city-<name>` | `-city-surabaya` | 城市名称，小写，空格用下划线 |
| `-asn-<number>` | `-asn-7713` | ISP 网络编号，不含 "AS" |
| `-session-<id>` | `-session-cart2` | 将请求绑定到一个粘性 IP |
| `-ttl-<minutes>` | `-ttl-20` | 粘性时长，最长 30 分钟 |

## 我应该使用哪个主机、端口和认证方式？

| 属性 | 值 |
| --- | --- |
| 主机 | `gw.banyanproxies.com` |
| HTTP / HTTPS 端口 | 7777 |
| SOCKS5 端口 | 7778 |
| 认证 | 所有套餐均支持用户名和密码，或 IP 允许列表（最多 10 个 IP）。可创建带独立凭据和流量上限的子用户。API 密钥可随时撤销 |
| 轮换 | 每个新连接都会从 IP 池中分配一个 IP，通常与上一个不同；如需每个请求都换新 IP，请每个连接只发一个请求（关闭 keep-alive） |
| 粘性会话 | 最长 30 分钟（IP 可能提前更换） |
| 已封锁 | 银行、政府和支付门户网站，以及 SMTP（发邮件）端口 25、465 和 587 |

## 我可以复制哪些代码示例？

每个示例都会请求一个 IP，并打印查询服务看到的结果。请替换 USERNAME 和 PASSWORD。[城市定向页面](https://banyanproxies.com/zh/targeting/city/)和[粘性会话指南](https://banyanproxies.com/zh/guides/sticky-sessions/)中有更多内容。

*通过 SOCKS5 使用 curl：一个惠灵顿 IP*

```bash
curl --socks5-hostname gw.banyanproxies.com:7778 \
  -U "USERNAME-country-nz-city-wellington:PASSWORD" \
  https://ipinfo.io/json
```

*Python (httpx)：IP 失败时用新会话重试*

```python
import uuid

import httpx

HOST = "gw.banyanproxies.com"
PORT = 7777


def fetch(url, city="lahore", country="pk", tries=3):
    for _ in range(tries):
        sid = uuid.uuid4().hex[:8]
        user = f"USERNAME-country-{country}-city-{city}-session-{sid}-ttl-10"
        proxy = f"http://{user}:PASSWORD@{HOST}:{PORT}"
        try:
            with httpx.Client(proxy=proxy, timeout=30) as client:
                r = client.get(url)
                r.raise_for_status()
                return r.text
        except httpx.HTTPError as exc:
            print("retrying with a new IP:", exc)
    return None


print(fetch("https://ipinfo.io/json"))
```

*Node.js (undici)：一个胡志明市 IP*

```javascript
// npm install undici
const { ProxyAgent, fetch } = require("undici");

const user = "USERNAME-country-vn-city-ho_chi_minh_city";
const token = "Basic " + Buffer.from(`${user}:PASSWORD`).toString("base64");
const dispatcher = new ProxyAgent({
  uri: "http://gw.banyanproxies.com:7777",
  token,
});

async function main() {
  const res = await fetch("https://ipinfo.io/json", { dispatcher });
  const info = await res.json();
  console.log(info.ip, info.city, info.region);
}

main().catch((err) => console.error(err.message));
```

*Playwright (Python)：一个带有悉尼 IP 和匹配时区的浏览器*

```python
from playwright.sync_api import sync_playwright

PROXY = {
    "server": "http://gw.banyanproxies.com:7777",
    "username": "USERNAME-country-au-city-sydney-session-syd1-ttl-15",
    "password": "PASSWORD",
}

with sync_playwright() as p:
    browser = p.chromium.launch(proxy=PROXY)
    context = browser.new_context(
        timezone_id="Australia/Sydney",
        locale="en-AU",
    )
    page = context.new_page()
    page.goto("https://ipinfo.io/json")
    print(page.inner_text("body"))
    browser.close()
```

## 常见错误代码是什么意思？

| 代码或症状 | 可能原因 | 该怎么办 |
| --- | --- | --- |
| 407 Proxy Authentication Required（需要代理认证） | 用户名、密码或段语法错误 | 重新复制凭据；检查连字符和下划线 |
| 连接超时 | 端口错误或防火墙拦截 | HTTP 使用 7777，SOCKS5 使用 7778 |
| 仅某个城市报错 | 该地当前在线的家庭设备较少 | 稍后重试、改用附近城市，或去掉城市段 |
| 目标返回 403 或 429 | 目标拒绝或限流 | 放慢速度；遵守网站条款和 robots.txt |
| 连接银行或 SMTP 端口被拒绝 | 目标被封锁 | 这些目标按政策被封锁 |

## 其余文档在哪里？

- **[API 文档](https://banyanproxies.com/docs/api/)** — 账户、充值、订单、用量和 API 密钥均通过 HTTPS。
- **[城市定向](https://banyanproxies.com/zh/targeting/city/)** — 每个城市的拼写规则和示例。
- **[ASN 定向](https://banyanproxies.com/zh/targeting/asn/)** — 主要家庭 ISP 的网络编号。
- **[快速上手](https://banyanproxies.com/zh/guides/getting-started/)** — 从充值到首次请求。

## 出问题时我该去哪里？

先查看[服务状态](https://banyanproxies.com/zh/status/)，然后遇到位置疑问时查看[代理城市检查器](https://banyanproxies.com/zh/guides/verify-proxy-city/)，术语问题查看[术语表](https://banyanproxies.com/zh/glossary/)。通过[联系页面](https://banyanproxies.com/zh/contact/)写信给支持团队。

## 开发者还会问什么？

### 我需要按国家或城市使用特殊端点吗？

不需要。一个网关服务所有位置；用户名决定 IP 所在位置。

### 我可以用 IP 白名单代替密码吗？

所有套餐均支持用户名和密码，或 IP 允许列表（最多 10 个 IP）。可创建带独立凭据和流量上限的子用户。API 密钥可随时撤销.

### 示例都经过测试吗？

每个 Python 示例在发布前都会编译，每个 JavaScript 示例都会做语法检查。请先安装它们提到的库：httpx、undici 或 Playwright。

---

Banyan Proxies: Banyan Proxies 是一家覆盖南亚、东南亚和大洋洲各城市的住宅代理服务商，支持加密货币支付且无需上传身份证件：可按城市定向获取孟买、雅加达、马尼拉、曼谷、卡拉奇、悉尼等地的家庭 IP，按 GB 计费。