> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexalayer.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速开始

> 用 API Key 查询产品、创建 Session、获取 proxy.full_url、上报执行结果并清理资源。

# 快速开始

这份 Quick Start 面向第一次接入 NexaLayer 的开发者，目标是跑通最小链路：

```text theme={null}
API Key -> 产品列表 -> 创建 Session -> 获取 proxy.full_url -> 上报结果 -> 查询健康 -> 终止 Session
```

## 1. 输入邮箱领取 API Key

```bash theme={null}
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 试用额度：

```json theme={null}
{
  "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。

```bash theme={null}
export NEXALAYER_API_KEY="ak_xxx"
```

## 2. 查询产品

```bash theme={null}
curl "$BASE_URL/products?type=dynamic" \
  -H "X-API-Key: $NEXALAYER_API_KEY"
```

产品响应里的 `product_no` 用于创建 Session。动态产品适合短周期、批量、需要按失败原因轮换的任务；静态产品适合账号保活、固定地区、长期会话。

## 3. 创建 Dynamic Session

```bash theme={null}
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` 会预扣 $1。Static Session 最低 \$10 / 月。Session 创建、查询、遥测、健康和终止管理暂时不收平台费。

创建接口是异步的。成功受理后通常返回 `status=creating`，下一步轮询详情。

## 4. 轮询到 active

```bash theme={null}
SID="sess_xxx"

curl "$BASE_URL/sessions/$SID" \
  -H "X-API-Key: $NEXALAYER_API_KEY"
```

当 `status=active` 时，会返回：

```json theme={null}
{
  "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. 上报执行结果

```bash theme={null}
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. 查询健康

```bash theme={null}
curl "$BASE_URL/sessions/$SID/health" \
  -H "X-API-Key: $NEXALAYER_API_KEY"
```

典型返回：

```json theme={null}
{
  "data": {
    "health_score": 100,
    "risk_level": "low",
    "success_rate": 1,
    "consecutive_failures": 0,
    "recommendation": "ok"
  }
}
```

## 7. 清理 Session

```bash theme={null}
curl -X DELETE "$BASE_URL/sessions/$SID" \
  -H "X-API-Key: $NEXALAYER_API_KEY"
```

自动化脚本应把清理放进 `finally` 或退出钩子，避免留下未终止的资源。