开发者 API
Hell World 个人 API 让您自己的程序和 AI 工具读取您的产品、用量和余额,并为您名下的产品生成代理串。
速览
- REST Base URL:
https://hellworld.io/hellworld/papi/v1 - OpenAPI 3.1:https://hellworld.io/hellworld/papi/v1/openapi.json
- MCP 地址:
https://hellworld.io/mcp - 鉴权:
Authorization: Bearer <your key>或X-API-Key: <your key> - 格式:除
/proxies/export返回纯文本外,所有响应都是 JSON。
本 API 供服务端调用:带浏览器 Origin 头的请求会被拒绝,返回 403 CORS_NOT_ALLOWED。
鉴权
密钥格式:hwp_live_<12 letters or digits>.<43 characters>(hwp_live_ 后接 12 位字母或数字、一个点号,再接 43 个字符)
Authorization: Bearer <your key>
X-API-Key: <your key>有效期:从当前时间起至少 1 小时、至多 1 年;密钥页默认建议 30 天。
每个账户只有一把密钥。它拥有 API 的全部权限,且必须设置到期时间。
创建、重新生成和延长密钥都需要发送到账户邮箱的验证码。默认情况下,再次查看密钥也需要验证码;完成一次验证后的 10 分钟内除外。
把密钥作为 Bearer token 放在 Authorization 头里,或放在 X-API-Key 头里。两个头都带时,值必须完全相同。不接受放在查询字符串里的密钥。
重新生成密钥后,旧密钥立即失效。如果怀疑密钥已泄露,请重新生成。
接口
以下路径均相对于 https://hellworld.io/hellworld/papi/v1。
| 方法 | 路径 | 返回内容 |
|---|---|---|
GET | /me | 您的密钥前缀、部分隐藏的邮箱、API 看到的客户端 IP、服务器时间和限流额度。 |
GET | /products | 您的产品列表,含状态、用量和生成能力(capabilities)。不含凭据。 |
GET | /products/{product} | 按 id 或代码查询单个产品。若您的多个产品共用同一个代码,返回 409 PRODUCT_AMBIGUOUS 并附候选 id。 |
GET | /products/{product}/locations/{kind} | 该产品生成代理时可用的位置代码(countries、states、cities、asns、isps)。 |
POST | /proxies/generate | 生成代理串,以 JSON 返回。 |
GET | /proxies/export | 以纯文本返回同样的代理串,每行一条。参数放在查询字符串里;不支持 format=json。 |
GET | /usage | 各产品的用量及其来源(upstream、cached、local 或 unknown),以及流量合计。 |
GET | /balance | 您的余额(USD,只读),附网站充值链接。 |
GET | /openapi.json | 本 API 的 OpenAPI 3.1 描述文档。无需密钥。 |
生成代理
| 参数 | 含义 |
|---|---|
product 必填 | 产品 id(32 位十六进制字符)或产品代码,例如 oxylab。见 /products。 |
count | 条数:1–1000,默认 1(经 MCP 为 1–100)。静态 ISP 产品忽略此参数,直接返回完整清单。 |
country | 国家/地区代码,例如 US。不传则随机选择位置。 |
state | 州/省代码;见 locations/states。部分产品只接受 state 和 city 其中之一:两个都传时返回 400 INVALID_PARAMETER,error.param 为 state。 |
city | 城市代码;见 locations/cities。 |
isp | ISP(运营商)代码(仅 ET-Hearth);见 locations/isps。 |
asn | ASN,取值 1 到 4294967295。不能与 state、city 或 zip 同时使用。 |
zip | 邮政编码,仅在产品的 capabilities 列出 zip 时可用。 |
os | 操作系统指纹,取值见产品的 capabilities。 |
session | rotating(轮换,默认)或 sticky(粘性)。 |
session_minutes | 粘性会话时长;可选值见 capabilities.session.sticky_minutes。 |
session_seed | 仅用于 session=sticky。种子、产品和参数都相同时,得到的会话标识相同;但不保证出口 IP 相同。 |
server | 网关区域,取值见 capabilities.servers。 |
protocol | http(默认)或 socks5(仅在产品的 capabilities 列出时可用)。 |
format | 输出格式,默认 host:port:user:pass。 |
可选格式:host:port:user:pass user:pass@host:port user:pass:host:port url json
生成代理串不会在代理网络一侧创建或修改任何东西:不涉及账号、订单或额度。
ET-Hearth 的定位参数(国家/地区、州/省、城市和 ISP 代码)会按代理网络的实时数据校验。这些数据没有缓存时会实时拉取;拉取不到时请求失败,返回 503 LOCATIONS_UNAVAILABLE。
产品不支持所请求的定位时,API 返回 400 UNSUPPORTED_PARAMETER;绝不会悄悄给您一个范围更宽的代理。
以冒号或 @ 分隔的格式不接受含有 :、@、空白或换行的凭据(400 FORMAT_UNSAFE);请改用 url 或 json。
静态 ISP 产品经 REST 返回完整清单(最多 1000 行)。经 MCP 最多返回 100 行;清单更长时请用 GET /proxies/export。
session_seed 只保证会话标识稳定,不保证出口 IP 不变。
安全
生成的代理串包含您的代理用户名和密码。您接入的任何程序或 AI 平台都会拿到它们。
用量与余额
status 是根据 Hell World 本地记录得出的展示分类。它既不代表可以生成,也不是代理网络的实时保证。某个产品能否生成,以那一次生成请求的资格校验为准。
usage.source 说明数字的来源:upstream(本次请求时从代理网络读取)、cached(最近 10 分钟内从代理网络读取;读取时间见 synced_at)、local(Hell World 自己的记录,不是从代理网络读取)或 unknown。只有部分产品会从代理网络读取;其余产品为 local 或 unknown,且 synced_at 为 null。
来源为 upstream 或 cached 的 usage 读自代理网络,可能还没反映刚完成的加量。其中的 limit、used 和 remaining 是代理网络对该产品当前给出的数字,可能与您购买的数量不同。
traffic_total 只累加流量数字可信的产品。
余额只读。请在网站上充值。
错误码
{"error": {"code", "message", "param", "hint", "docs_url"}, "request_id"}请按 error.code 做分支判断,不要依赖 message 文本。
429 和 503 响应可能带 Retry-After 头(单位:秒)。429 RATE_LIMITED 还会在 error.limit_dimension 里指明耗尽的是哪一项限额。
联系客服时请附上 request_id。
| 错误码 | HTTP 状态 | 含义 |
|---|---|---|
ACCOUNT_SUSPENDED | 403 | 账户已被停用。 |
AUTH_STATUS_INVALID | 503 | 账户状态不一致。请联系客服。 |
AUTH_STATUS_UNAVAILABLE | 503 | 暂时无法核验密钥或账户状态。请稍后重试。 |
CORS_NOT_ALLOWED | 403 | 请求来自浏览器(带 Origin 头)。请从服务端调用 API。 |
FORMAT_UNSAFE | 400 | 所选格式无法安全地表示这些凭据;请改用 url 或 json。 |
GENERATOR_OUTPUT_TOO_LARGE | 409, 500 | 结果超出大小上限。409 表示静态 ISP 清单超过了 MCP 允许的长度;请改用 /proxies/export。 |
GENERATOR_UNAVAILABLE | 503 | 生成服务暂时不可用。请稍后重试。 |
INTERNAL_ERROR | 500(及其他 5xx) | 服务器意外错误。 |
INVALID_PARAMETER | 400 | 某个参数缺失或无效;error.param 指明是哪一个。 |
INVALID_REQUEST | 400(及其他 4xx) | 请求本身格式错误,例如请求体不是 JSON 对象。 |
KEY_INVALID | 401 | 密钥不正确、已吊销或已过期。 |
LOCATIONS_UNAVAILABLE | 503 | 实时位置数据暂时不可用。请稍后重试。 |
METHOD_NOT_ALLOWED | 405 | 该路径不接受此 HTTP 方法。 |
NOT_ACCEPTABLE | 406 | Accept 头排除了该路径能返回的所有类型。 |
NOT_FOUND | 404 | 路径不存在,或个人 API 未开放。 |
PAYLOAD_TOO_LARGE | 413 | 请求体过大。 |
PRODUCT_AMBIGUOUS | 409 | 该代码匹配到您的多个产品;请改用候选 id 之一。 |
PRODUCT_DATA_INVALID | 409 | 该产品的连接数据不完整或过大。请联系客服。 |
PRODUCT_INACTIVE | 409 | 产品已过期或未激活。 |
PRODUCT_NOT_FOUND | 404 | 您的账户里没有这个产品。 |
PRODUCT_PROVISIONING | 409 | 产品仍在开通中。 |
RATE_LIMITED | 429 | 超出了限流或生成预算;见 Retry-After 和 limit_dimension。 |
RATE_LIMIT_UNAVAILABLE | 503 | 限流服务暂时不可用。请稍后重试。 |
UNAUTHENTICATED | 401 | 没有发送密钥,或密钥格式错误。 |
UNSUPPORTED_MEDIA_TYPE | 415 | 不支持该 Content-Type;请发送 application/json。 |
UNSUPPORTED_PARAMETER | 400 | 该产品不支持所请求的定位或选项。 |
限流
- 每个客户端 IP:每分钟 600 次请求。
- 每把密钥:每分钟 120 次读请求、60 次生成请求。
- 每个账户:每分钟 300 次请求、20,000 行生成结果、5,000,000 字节,同一时间最多 4 个生成请求。
响应头:X-RateLimit-Limit X-RateLimit-Remaining X-RateLimit-Reset X-Budget-Lines-Remaining
读接口计入读请求限额;generate 和 export 计入生成请求限额。
每个通过密钥校验的 MCP 请求都按一次生成类请求计数(见下文 MCP 一节)。
X-RateLimit-* 描述当前类别下的密钥限额;X-Budget-Lines-Remaining 出现在生成类响应中。
面向 AI 工具的 MCP 服务器MCP 服务器
MCP 地址为 https://hellworld.io/mcp,支持协议版本 2025-06-18 和 2026-07-28。
鉴权方式是放在请求头里的静态 API 密钥。Hell World 的 MCP 没有实现 OAuth,因此只能用 OAuth 连接的客户端暂时无法使用。
响应始终是 JSON。不提供 SSE 流,也不支持订阅。
成功的工具结果带有 structuredContent,同时以文本部分附上同一份 JSON,大小最多为 REST 响应的 2 倍再加 4 KiB。这层包装不计入字节预算。
错误结果会设置 isError,且只有文本部分:内容是原样的 REST 错误信封,或简短的 MCP 错误(如 RESPONSE_TOO_LARGE)。错误结果没有 structuredContent。
如果工具背后的 REST 响应超过 256 KiB,工具会返回 RESPONSE_TOO_LARGE;这类请求请直接用 REST API。
工具
| 工具 | 作用 |
|---|---|
list_products | 列出您的 Hell World 产品,含状态、用量和生成能力(capabilities)。不含凭据。 |
get_product | 按 id 或代码查询您的单个产品。若代码匹配到您的多个产品,错误里会列出候选 id。 |
list_locations | 该产品在 generate_proxies 中可用的位置代码。states、cities、asns 和 isps 需要提供 country;cities 和 isps(ET-Hearth)还需要 state。 |
generate_proxies 非幂等 | 为您的某个产品生成代理串(每次 count 为 1–100;静态 ISP 产品返回完整清单,经 MCP 最多 100 行)。代理串包含您的代理用户名和密码。不支持的定位会报错,绝不会退而给出范围更宽的代理。 |
get_usage | 各产品的用量及其来源(upstream、cached、local 或 unknown),以及流量合计。 |
get_balance | 您的账户余额(USD,只读),附网站充值链接。 |
哪些请求计入限额限额计数
| 情形 | 每 IP 限额 | 每密钥与每账户限额 |
|---|---|---|
还没到密钥校验就被 MCP 入口拒绝:路径错误、Host 错误、带浏览器 Origin、方法不是 POST、服务器繁忙、客户端地址缺失或无效,或密钥头发送了两次。 | 不计入 | 不计入 |
个人 API 已关闭:密钥校验返回 404 NOT_FOUND。 | 不计入 | 不计入 |
| 密钥校验失败:没带密钥,密钥格式错误、不正确、已吊销或已过期,账户被停用,或无法读取账户状态。错误按 REST API 的方式原样返回。 | 计入 | 不计入 |
密钥或账户限额已用尽(429 RATE_LIMITED,带 Retry-After),或限流服务不可用(503 RATE_LIMIT_UNAVAILABLE)。 | 计入 | 不计入 |
每 IP 限额已用尽(429)。 | 不计入 | 不计入 |
| 请求通过了密钥校验。从这一步起,无论之后发生什么都计一次:成功、请求体过大、JSON 无效、批量请求、订阅请求、MCP 库返回的协议错误,或工具执行失败。 | 计入 | 计入 |
工具代您调用 REST API。这次调用不再重复计数;但 generate_proxies 仍会预占并结算它的行数和字节预算。 | 不计入 | 不计入 |
密钥校验有应答,但应答丢失或无法使用(MCP 服务器返回 AUTH_STATUS_UNAVAILABLE 或 INTERNAL_ERROR)。该请求可能已被计数一次。 | 可能计入 | 可能计入 |
MCP 错误码
MCP 服务器返回的 HTTP 层错误:
| 错误码 | HTTP 状态 | 含义 |
|---|---|---|
HOST_NOT_ALLOWED | 403 | Host 头不是 hellworld.io。 |
CORS_NOT_ALLOWED | 403 | 请求来自浏览器。 |
NOT_FOUND | 404 | 路径不是 /mcp。 |
METHOD_NOT_ALLOWED | 405 | 只支持 POST。 |
INVALID_REQUEST | 400 | 客户端地址缺失,或密钥头发送了两次。 |
MCP_BUSY | 503 | 并发请求过多;请等待 Retry-After 秒后重试。 |
PAYLOAD_TOO_LARGE | 413 | 请求体超过 64 KiB。 |
AUTH_STATUS_UNAVAILABLE | 503 | 密钥校验没有给出可用的应答;请稍后重试。 |
INTERNAL_ERROR | 500 | MCP 服务器内部意外错误。 |
JSON-RPC 错误:
| 错误码 | HTTP 状态 | 含义 |
|---|---|---|
-32700 | 400 | 解析错误:请求体不是有效的 JSON。 |
-32600 | 400 | 无效请求:批量请求,或请求体不是对象。 |
-32601 | 200 | 方法不存在:不提供订阅。 |
-32603 | 500 | 内部错误,包括响应会超过 1 MiB 的情况。 |
-32020 | 400 | Mcp-Method、Mcp-Name 或 MCP-Protocol-Version 头与请求体不一致。 |
-32000 | 400 | 按 2025 版(旧版)协议格式发来的请求,其 MCP-Protocol-Version 头里的版本不受支持。 |
我们固定使用的 MCP 库还可能返回其他标准 JSON-RPC 错误。
工具错误码(出现在设置了 isError 的结果文本中):
| 错误码 | 含义 |
|---|---|
RESPONSE_TOO_LARGE | 该工具背后的 REST 响应超过 256 KiB;这次请求请直接用 REST API。 |
API_UNAVAILABLE | 无法连接 API;请稍后重试。 |
INVALID_PARAMETER | product 或 kind 的值不能用在请求路径里。 |
GENERATOR_OUTPUT_TOO_LARGE | 包装后的工具结果会超过 REST 响应的 2 倍再加 4 KiB。 |
INTERNAL_ERROR | API 返回了意外的内容。 |
密钥校验失败时,MCP 服务器原样返回 REST 错误(状态码、响应体、Retry-After 和请求 id)。
连接客户端
Claude Code — 项目级 .mcp.json(不含任何密钥,可以放心提交到仓库):
{
"mcpServers": {
"hellworld": {
"type": "http",
"url": "https://hellworld.io/mcp",
"headers": {
"Authorization": "Bearer ${HELLWORLD_API_KEY}"
}
}
}
}Cursor — 全局 ~/.cursor/mcp.json(放在所有仓库之外):
{
"mcpServers": {
"hellworld": {
"url": "https://hellworld.io/mcp",
"headers": {
"Authorization": "Bearer ${env:HELLWORLD_API_KEY}"
}
}
}
}设置环境变量,且不让密钥留在 shell 历史里:
read -rs HELLWORLD_API_KEY && export HELLWORLD_API_KEY注意
把密钥保存在环境变量或密码管理器里。切勿把真实密钥写在命令行上(它会留在 shell 历史和进程列表里),切勿提交到代码仓库,也切勿粘贴到 issue 或聊天里。
注意
不要用 claude mcp add --header 直接传入真实密钥;请改为在 .mcp.json 里引用环境变量。
OpenAPI
OpenAPI 3.1 文档描述了全部 9 个接口、它们的参数和所有错误码。
个人 API 开放后,获取该文档无需密钥。
支持导入 OpenAPI 的工具(例如 GPT Actions)可以直接使用它,再配上 API 密钥请求头即可。