接入文档

面向程序化访问的一站式网关：支持 HTML、图片与流式响应。请求进入后由统一调度引擎根据目标站策略自动匹配处理路径（标准 / 高级 / Premium），您只需提供 URL 与 API Key。

接口端点

GET/proxy/v1/fetch?url=目标URL— 返回 HTML（默认）
GET/proxy/v1/fetch?url=目标URL&raw=1— 返回 JSON（含处理方式/耗时/积分详情）
GET/proxy/v1/img?url=图片URL— 返回图片二进制
GET/proxy/v1/fetch/stream?url=目标URL— 流式响应（V2s，适合大页面）
GET/proxy/v1/turnstile?url=目标URL— Turnstile 验证码处理

认证方式

在请求头或 Query 参数中传入 API Key（两种方式等效）：

# 方式一：请求头（推荐）
X-CS-ApiKey: cs_your_api_key_here

# 方式二：Query 参数
?apikey=cs_your_api_key_here

代码示例

# 请求带站点策略的页面（返回 HTML）
curl "https://cloude.maibiruumen.com/proxy/v1/fetch?url=https://example.com" \
  -H "X-CS-ApiKey: cs_your_api_key_here"

# JSON 模式（含处理方式/耗时/积分详情）
curl "https://cloude.maibiruumen.com/proxy/v1/fetch?url=https://example.com&raw=1" \
  -H "X-CS-ApiKey: cs_your_api_key_here"

# 通过 Query 参数传 Key（适合简单场景）
curl "https://cloude.maibiruumen.com/proxy/v1/fetch?url=https://example.com&apikey=cs_your_api_key_here"

响应头说明

响应头说明示例值
X-CS-Credits-Remaining请求后剩余积分9876
X-CS-Request-Id请求唯一 ID（排查问题用）req_abc123
X-CS-Engine实际命中的处理路径（脱敏分级）standard / advanced / premium
X-CS-Response-Time总耗时（含引擎处理）1.24s

JSON 响应结构（raw=1 时）

{
  "success": true,
  "url": "https://example.com",
  "status": 200,
  "engine": "standard",           // 命中的处理路径标识（脱敏分级，可能值见"积分规则"）
  "elapsed": 1.24,                // 耗时（秒，含调度与回源）
  "credits_remaining": 9876,      // 本次扣减后剩余积分
  "html": "<html>...</html>"      // 页面 HTML 内容
}

积分消耗规则

✅标准通路（standard）— 直接放行 / 基础 WAF / 防盗链 / UA·Referer 校验扣 1 积分
✅高级通路（advanced）— JS 质询 / Managed Challenge / Cookie 协商扣 2 积分
✅Premium 通路（premium）— 前置人机验证 / Turnstile 令牌协商扣 3 积分
❌失败请求（5xx / 超时 / 目标站错误）不扣积分
❌限流拒绝（429）不扣积分
❌参数错误 / 鉴权失败（400 / 401 / 402）不扣积分

* 通路等级由系统按目标站策略动态判定，无需在请求中指定。同一域名首次进入更高通路并取得有效凭据后，命中的会话凭据会自动短期缓存，后续多数请求会回落到更低成本通路，整体均摊成本通常显著低于单次峰值。

支持的防护类型（全自动识别）

防护类型代表产品/场景处理方式速度影响
标准通路 · TLS / UA 指纹常规反爬、防盗链、Referer 校验浏览器级 TLS 指纹仿真 + Header 自动补齐无影响
标准通路 · 基础 WAF / 主机面板规则常见主机面板专业规则集 / Nginx 反代Cookie 与 Referer 链路自动补齐无影响
标准通路 · 自建 CDN / 频控反代层频率与令牌策略Session 持久化 + 自适应退避几乎无影响 (+50ms)
高级通路 · 短时 JS 质询全球 CDN 边缘 JS Challenge / Managed Challenge无头浏览器执行 JS + Cookie 短期缓存首次 5-15s，后续命中缓存
高级通路 · 交互前 Cookie 校验需先完成轻量交互才下发会话 Cookie 的页面调度引擎自动完成协商并复用会话首次较慢，后续无影响
Premium 通路 · 前置人机验证Turnstile 等访客前机审场景Token 协商 + 完整浏览器指纹模拟5-20s（建议尽量复用同一 ApiKey 命中缓存）

* 所有通路均由系统自动识别和处理，API 调用方式完全相同。强度更高的通路单次成本更高，但命中后通常会自动建立短期缓存以摊薄后续请求成本。

错误码说明

HTTP 状态码含义处理建议
200请求成功正常处理响应内容
400参数错误（缺少 url 等）检查请求参数
401API Key 无效或未传检查 X-CS-ApiKey 头
402积分不足前往购买套餐充值积分
429触发限流（超过 QPS 限制）降低请求频率或升级套餐
503目标站抓取失败可稍后重试，失败不扣积分

常见问题 (FAQ)

积分是什么？怎么计算？
每次成功请求按命中的处理路径计费：标准通路 1 积分、高级通路（JS 质询 / Managed Challenge / Cookie 协商）2 积分、Premium 通路（前置人机验证 / Turnstile 令牌协商）3 积分。失败、超时、限流、参数错误等情况不扣积分。同一域名命中的会话凭据会被短期缓存，后续多数请求会回落到更低成本通路。
积分会过期吗？
购买的积分从购买时起30天有效，试用积分从领取时起3天有效。到期未用完的积分自动清零。再次购买会重置过期时间为新购买后30天。
是共享环境还是独享？
当前为共享网关模式，所有用户共用同一套引擎集群。每个用户的数据（API Key、积分、请求日志）是严格隔离的。如需独享环境，请联系 support@cloudshield.cc 获取企业定制方案。
支持哪些网站？
支持大多数公开可访问且未签订独占防护合约的站点。覆盖通路包括标准（基础 WAF / 防盗链 / 自建频控）、高级（JS 质询 / Managed Challenge / Cookie 协商）以及 Premium（前置人机验证 / Turnstile）。具体兼容性以目标站点当前生效的策略为准。
可以退款吗？
购买后7天内可联系 support@cloudshield.cc 申请退款，已部分消费的积分包可按比例退还。试用积分不可退款。
如何联系技术支持？
邮箱 support@cloudshield.cc 或 Telegram @cloudshield_support，工作日 24 小时内响应。

频率限制（QPS）

套餐QPS 限制并发数月积分
新手试用22200
入门版 ¥29/月3510,000
常规版 ¥99/月101050,000
标准版 ¥199/月 🔥1515150,000
专业版 ¥399/月2020400,000
三皇版 ¥799/月30301,000,000