cURL
curl --request POST \
--url https://api.brightdata.com/zone \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"zone": {
"name": "zone-name",
"type": "serp"
},
"plan": {
"domain_whitelist": "<string>",
"ips": 0,
"country": "any",
"country_city": "any",
"mobile": "false",
"serp": "false",
"city": "false",
"asn": "false",
"vip": "false",
"vips": "0",
"vip_country": "<string>",
"vip_country_city": "any",
"pool_ip_type": "<string>",
"ub_premium": false,
"solve_captcha_disable": true,
"custom_headers": false
}
}
'import requests
url = "https://api.brightdata.com/zone"
payload = {
"zone": {
"name": "zone-name",
"type": "serp"
},
"plan": {
"domain_whitelist": "<string>",
"ips": 0,
"country": "any",
"country_city": "any",
"mobile": "false",
"serp": "false",
"city": "false",
"asn": "false",
"vip": "false",
"vips": "0",
"vip_country": "<string>",
"vip_country_city": "any",
"pool_ip_type": "<string>",
"ub_premium": False,
"solve_captcha_disable": True,
"custom_headers": False
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
zone: {name: 'zone-name', type: 'serp'},
plan: {
domain_whitelist: '<string>',
ips: 0,
country: 'any',
country_city: 'any',
mobile: 'false',
serp: 'false',
city: 'false',
asn: 'false',
vip: 'false',
vips: '0',
vip_country: '<string>',
vip_country_city: 'any',
pool_ip_type: '<string>',
ub_premium: false,
solve_captcha_disable: true,
custom_headers: false
}
})
};
fetch('https://api.brightdata.com/zone', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.brightdata.com/zone",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'zone' => [
'name' => 'zone-name',
'type' => 'serp'
],
'plan' => [
'domain_whitelist' => '<string>',
'ips' => 0,
'country' => 'any',
'country_city' => 'any',
'mobile' => 'false',
'serp' => 'false',
'city' => 'false',
'asn' => 'false',
'vip' => 'false',
'vips' => '0',
'vip_country' => '<string>',
'vip_country_city' => 'any',
'pool_ip_type' => '<string>',
'ub_premium' => false,
'solve_captcha_disable' => true,
'custom_headers' => false
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.brightdata.com/zone"
payload := strings.NewReader("{\n \"zone\": {\n \"name\": \"zone-name\",\n \"type\": \"serp\"\n },\n \"plan\": {\n \"domain_whitelist\": \"<string>\",\n \"ips\": 0,\n \"country\": \"any\",\n \"country_city\": \"any\",\n \"mobile\": \"false\",\n \"serp\": \"false\",\n \"city\": \"false\",\n \"asn\": \"false\",\n \"vip\": \"false\",\n \"vips\": \"0\",\n \"vip_country\": \"<string>\",\n \"vip_country_city\": \"any\",\n \"pool_ip_type\": \"<string>\",\n \"ub_premium\": false,\n \"solve_captcha_disable\": true,\n \"custom_headers\": false\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.brightdata.com/zone")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"zone\": {\n \"name\": \"zone-name\",\n \"type\": \"serp\"\n },\n \"plan\": {\n \"domain_whitelist\": \"<string>\",\n \"ips\": 0,\n \"country\": \"any\",\n \"country_city\": \"any\",\n \"mobile\": \"false\",\n \"serp\": \"false\",\n \"city\": \"false\",\n \"asn\": \"false\",\n \"vip\": \"false\",\n \"vips\": \"0\",\n \"vip_country\": \"<string>\",\n \"vip_country_city\": \"any\",\n \"pool_ip_type\": \"<string>\",\n \"ub_premium\": false,\n \"solve_captcha_disable\": true,\n \"custom_headers\": false\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.brightdata.com/zone")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"zone\": {\n \"name\": \"zone-name\",\n \"type\": \"serp\"\n },\n \"plan\": {\n \"domain_whitelist\": \"<string>\",\n \"ips\": 0,\n \"country\": \"any\",\n \"country_city\": \"any\",\n \"mobile\": \"false\",\n \"serp\": \"false\",\n \"city\": \"false\",\n \"asn\": \"false\",\n \"vip\": \"false\",\n \"vips\": \"0\",\n \"vip_country\": \"<string>\",\n \"vip_country_city\": \"any\",\n \"pool_ip_type\": \"<string>\",\n \"ub_premium\": false,\n \"solve_captcha_disable\": true,\n \"custom_headers\": false\n }\n}"
response = http.request(request)
puts response.read_body账号管理 API
添加区域
使用 Bright Data 账户管理 API 添加区域。POST /zone 返回 200 OK,并以 JSON 形式返回区域或账户配置数据。
POST
/
zone
cURL
curl --request POST \
--url https://api.brightdata.com/zone \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"zone": {
"name": "zone-name",
"type": "serp"
},
"plan": {
"domain_whitelist": "<string>",
"ips": 0,
"country": "any",
"country_city": "any",
"mobile": "false",
"serp": "false",
"city": "false",
"asn": "false",
"vip": "false",
"vips": "0",
"vip_country": "<string>",
"vip_country_city": "any",
"pool_ip_type": "<string>",
"ub_premium": false,
"solve_captcha_disable": true,
"custom_headers": false
}
}
'import requests
url = "https://api.brightdata.com/zone"
payload = {
"zone": {
"name": "zone-name",
"type": "serp"
},
"plan": {
"domain_whitelist": "<string>",
"ips": 0,
"country": "any",
"country_city": "any",
"mobile": "false",
"serp": "false",
"city": "false",
"asn": "false",
"vip": "false",
"vips": "0",
"vip_country": "<string>",
"vip_country_city": "any",
"pool_ip_type": "<string>",
"ub_premium": False,
"solve_captcha_disable": True,
"custom_headers": False
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
zone: {name: 'zone-name', type: 'serp'},
plan: {
domain_whitelist: '<string>',
ips: 0,
country: 'any',
country_city: 'any',
mobile: 'false',
serp: 'false',
city: 'false',
asn: 'false',
vip: 'false',
vips: '0',
vip_country: '<string>',
vip_country_city: 'any',
pool_ip_type: '<string>',
ub_premium: false,
solve_captcha_disable: true,
custom_headers: false
}
})
};
fetch('https://api.brightdata.com/zone', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.brightdata.com/zone",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'zone' => [
'name' => 'zone-name',
'type' => 'serp'
],
'plan' => [
'domain_whitelist' => '<string>',
'ips' => 0,
'country' => 'any',
'country_city' => 'any',
'mobile' => 'false',
'serp' => 'false',
'city' => 'false',
'asn' => 'false',
'vip' => 'false',
'vips' => '0',
'vip_country' => '<string>',
'vip_country_city' => 'any',
'pool_ip_type' => '<string>',
'ub_premium' => false,
'solve_captcha_disable' => true,
'custom_headers' => false
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.brightdata.com/zone"
payload := strings.NewReader("{\n \"zone\": {\n \"name\": \"zone-name\",\n \"type\": \"serp\"\n },\n \"plan\": {\n \"domain_whitelist\": \"<string>\",\n \"ips\": 0,\n \"country\": \"any\",\n \"country_city\": \"any\",\n \"mobile\": \"false\",\n \"serp\": \"false\",\n \"city\": \"false\",\n \"asn\": \"false\",\n \"vip\": \"false\",\n \"vips\": \"0\",\n \"vip_country\": \"<string>\",\n \"vip_country_city\": \"any\",\n \"pool_ip_type\": \"<string>\",\n \"ub_premium\": false,\n \"solve_captcha_disable\": true,\n \"custom_headers\": false\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.brightdata.com/zone")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"zone\": {\n \"name\": \"zone-name\",\n \"type\": \"serp\"\n },\n \"plan\": {\n \"domain_whitelist\": \"<string>\",\n \"ips\": 0,\n \"country\": \"any\",\n \"country_city\": \"any\",\n \"mobile\": \"false\",\n \"serp\": \"false\",\n \"city\": \"false\",\n \"asn\": \"false\",\n \"vip\": \"false\",\n \"vips\": \"0\",\n \"vip_country\": \"<string>\",\n \"vip_country_city\": \"any\",\n \"pool_ip_type\": \"<string>\",\n \"ub_premium\": false,\n \"solve_captcha_disable\": true,\n \"custom_headers\": false\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.brightdata.com/zone")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"zone\": {\n \"name\": \"zone-name\",\n \"type\": \"serp\"\n },\n \"plan\": {\n \"domain_whitelist\": \"<string>\",\n \"ips\": 0,\n \"country\": \"any\",\n \"country_city\": \"any\",\n \"mobile\": \"false\",\n \"serp\": \"false\",\n \"city\": \"false\",\n \"asn\": \"false\",\n \"vip\": \"false\",\n \"vips\": \"0\",\n \"vip_country\": \"<string>\",\n \"vip_country_city\": \"any\",\n \"pool_ip_type\": \"<string>\",\n \"ub_premium\": false,\n \"solve_captcha_disable\": true,\n \"custom_headers\": false\n }\n}"
response = http.request(request)
puts response.read_body只有拥有 Admin 或 Ops 角色的用户才能执行此操作。
此 API 可能会修改你的账户设置、损害你的运营或产生费用。
将你的 API key 粘贴到授权字段中。要获取 API key,请创建账户,并了解如何生成新的 API key
ISP 代理区域示例
创建 ISP 区域需要特定的参数组合。以下字段不是可选的。省略它们会在不报错的情况下创建错误的区域类型或计费方案。仅将
zone.type 设置为 ISP 会创建一个 Datacenter 区域,而不是 ISP 区域。你还必须将 plan.pool_ip_type 设置为 static_res。国家/地区代码必须为小写(例如 us、gb)。大写代码会返回一个具有误导性的 “no IPs available” 错误。共享 ISP(按 GB 计费)
{
"zone": { "name": "my_isp_zone", "type": "ISP" },
"plan": {
"type": "static",
"pool_ip_type": "static_res",
"ips_type": "shared",
"bandwidth": "bandwidth",
"country": "us"
}
}
共享 ISP(无限带宽)
仅设置bandwidth: unlimited 不会激活无限计费。你还必须包含 unl_bw_tiers: std。
{
"zone": { "name": "my_isp_zone", "type": "ISP" },
"plan": {
"type": "static",
"pool_ip_type": "static_res",
"ips_type": "shared",
"bandwidth": "unlimited",
"unl_bw_tiers": "std",
"country": "us"
}
}
专用 ISP(无限带宽)
{
"zone": { "name": "my_isp_zone", "type": "ISP" },
"plan": {
"type": "static",
"pool_ip_type": "static_res",
"ips_type": "dedicated",
"bandwidth": "unlimited",
"unl_bw_tiers": "std",
"country": "us",
"ips": 10
}
}
Residential 代理区域
新的 Residential 区域需要通过 KYC 审核。 对于 2026 年 7 月 7 日之后创建的 Residential 区域,仅允许已通过 KYC 验证的公司添加区域。来自尚未完成 KYC 的账户的请求将被阻止,并返回 HTTP 403 及合规错误。2026 年 7 月 7 日(含)之前创建的 Residential 区域不受影响,可继续正常使用。请从 KYC 验证开始,并参阅 Residential 网络访问策略。
Residential 403 合规错误
对于 2026 年 7 月 7 日之后创建的 Residential 区域,来自不符合条件账户的添加区域请求将返回 HTTP 403 及以下合规错误之一。2026 年 7 月 7 日(含)之前创建的区域不受影响。完整目录请参阅代理错误目录。| 错误代码 | 触发条件 | 如何修复 |
|---|---|---|
kyc_required | 使用公司邮箱但尚未完成 KYC 的账户。 | 开始 KYC 验证。由人工合规审核人员审批 Residential 访问权限。 |
business_account_required | 使用个人邮箱的账户(非已验证公司)。 | 使用公司邮箱并联系 Bright Data 团队以确认企业资格。个人邮箱账户不具备 Residential 资格。 |
code 值进行分支处理。使用公司邮箱但未完成 KYC 的账户会收到 kyc_required:
{
"error": {
"code": "kyc_required",
"message": "Residential proxies are available to verified companies only, after KYC review, in accordance with Bright Data's compliance policy.",
"action": "Start verification at brightdata.com/cp/kyc. Applications are reviewed by our compliance team.",
"alternatives": [
{ "product": "ISP proxy", "plan": { "type": "static", "pool_ip_type": "static_res", "ips_type": "shared" } },
{ "product": "Web Unlocker API", "plan": { "type": "unblocker" } }
],
"docs": "https://docs.brightdata.com/compliance/kyc"
}
}
business_account_required,该错误不提供 KYC,因为个人账户不具备资格:
{
"error": {
"code": "business_account_required",
"message": "Residential proxies are available to verified companies only. Eligibility requires a corporate email and full verification with the Bright Data team.",
"action": "Contact the Bright Data team with a corporate email to determine business eligibility for Residential access.",
"alternatives": [
{ "product": "ISP proxy", "plan": { "type": "static", "pool_ip_type": "static_res", "ips_type": "shared" } },
{ "product": "Web Unlocker API", "plan": { "type": "unblocker" } }
],
"docs": "https://docs.brightdata.com/compliance/kyc"
}
}
alternatives 数组,其中给出了用于改为创建免 KYC 的 ISP 或 Web Unlocker API 区域的确切 plan 对象。要创建该 ISP 区域,请在 POST /zone 请求中用该 plan 对象替换 Residential 的 plan。授权
在 Authorization 头中使用您的 Bright Data API Key 作为 Bearer token。
认证方法:
- 从 Bright Data 账户设置获取您的 API Key: https://brightdata.com/cp/setting/users
- 在请求的 Authorization 头中包含 API Key
- 格式:
Authorization: Bearer YOUR_API_KEY
示例:
Authorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df
了解如何获取 Bright Data API Key: https://docs.brightdata.com/cn/api-reference/authentication#如何生成新的-api-key?
请求体
application/json
响应
201
区域已添加
此页面对您有帮助吗?
⌘I