Skip to main content

​
快速开始

这份 Quick Start 面向第一次接入 NexaLayer 的开发者，目标是跑通最小链路： 
API Key -> 产品列表 -> 创建 Session -> 获取 proxy.full_url -> 上报结果 -> 查询健康 -> 终止 Session

​
1. 输入邮箱领取 API Key

BASE_URL="https://api.nexalayer.net/v1"

curl -X POST "$BASE_URL/account/request-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com"
  }'
响应不会直接返回 API Key。系统会把 API Key 发送到邮箱，邮箱首次领取时会自动获得 $1 试用额度： 
{
  "data": {
    "status": "email_sent",
    "claim_status": "granted",
    "trial_balance": 1,
    "backend_ready": true,
    "message": "If the email address is valid, the API key has been sent."
  }
}
如果同一个邮箱再次请求，系统只会重发已有 API Key，不会重复发放试用额度。试用额度适合创建小流量 Dynamic Session 验证链路；正式使用前可通过 USDT 自助充值，最低充值 $10。 
export NEXALAYER_API_KEY="ak_xxx"

​
2. 查询产品

curl "$BASE_URL/products?type=dynamic" \
  -H "X-API-Key: $NEXALAYER_API_KEY"
产品响应里的 product_no 用于创建 Session。动态产品适合短周期、批量、需要按失败原因轮换的任务；静态产品适合账号保活、固定地区、长期会话。

​
3. 创建 Dynamic Session

PRODUCT_NO="dynamic_ipweb"

curl -X POST "$BASE_URL/sessions" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NEXALAYER_API_KEY" \
  -H "Idempotency-Key: create-dynamic-001" \
  -d "{
    \"session_type\": \"dynamic\",
    \"product_no\": \"$PRODUCT_NO\",
    \"quantity\": 0.25,
    \"protocol\": \"socks5\",
    \"rotation_mode\": \"on_demand\"
  }"
Dynamic Session 按 4/GB扣费，因此‘quantity=0.25‘会预扣4 / GB 扣费，因此 `quantity=0.25` 会预扣 1。Static Session 最低 $10 / 月。Session 创建、查询、遥测、健康和终止管理暂时不收平台费。 创建接口是异步的。成功受理后通常返回 status=creating，下一步轮询详情。

​
4. 轮询到 active

SID="sess_xxx"

curl "$BASE_URL/sessions/$SID" \
  -H "X-API-Key: $NEXALAYER_API_KEY"
当 status=active 时，会返回： 
{
  "data": {
    "session_id": "sess_xxx",
    "status": "active",
    "proxy": {
      "host": "proxy.example.net",
      "port": 6666,
      "username": "user",
      "password": "pass",
      "protocol": "socks5",
      "full_url": "<redacted-proxy-url>"
    }
  }
}
proxy.full_url 适合传给 curl、Python requests 或支持代理 URL 的工具。Playwright 通常需要拆成 server、username、password。

​
5. 上报执行结果

curl -X POST "$BASE_URL/sessions/$SID/report-event" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NEXALAYER_API_KEY" \
  -d '{
    "event_type": "success",
    "status_code": 200,
    "target_host": "example.com",
    "latency_ms": 1200
  }'
这些事件会影响健康评分和轮换建议。

​
6. 查询健康

curl "$BASE_URL/sessions/$SID/health" \
  -H "X-API-Key: $NEXALAYER_API_KEY"
典型返回： 
{
  "data": {
    "health_score": 100,
    "risk_level": "low",
    "success_rate": 1,
    "consecutive_failures": 0,
    "recommendation": "ok"
  }
}

​
7. 清理 Session

curl -X DELETE "$BASE_URL/sessions/$SID" \
  -H "X-API-Key: $NEXALAYER_API_KEY"
自动化脚本应把清理放进 finally 或退出钩子，避免留下未终止的资源。