开放API

您可以通过我们的开放API获取站点 / 分组 / 状态等数据以便集成进您的业务系统。
开放API向所有用户免费提供，仅以少量积分消耗限制滥用。

Base URL：https://api.zzstan.com/api/v1/openapi

AppID / APISecret：请前往个人中心 → APISecret 创建。

统一响应格式

所有接口返回 { code, message, data }：成功 code 为 "0"；失败 code 为业务错误码，HTTP 状态码同时表达错误（401 鉴权 / 404 未找到 / 429 限流等）。

{
  "code": "0",
  "message": "ok",
  "data": { "site_id": 1, "site_name": "示例站点", "url": "...", "api_urls": [] }
}

签名认证（HMAC-SHA256）

在「个人中心 → APISecret」创建 AppID 与 APISecret，妥善保存 APISecret（仅显示一次）。
构造签名串：按固定 7 行、用 \n 拼接——请求方法、请求路径（含 /api/v1 前缀）、按 key 字典序排序的 query（k=v 原始值）、X-App-Id、X-Timestamp、X-Nonce、body 摘要（GET 为空串）。
用 APISecret 作为 key 对签名串做 HMAC-SHA256，输出十六进制字符串作为 X-Signature。
请求头携带 X-App-Id / X-Timestamp / X-Nonce / X-Signature。时间戳须与服务端相差 ±300 秒，nonce 不可重复（防重放）。

签名串格式（7 行，用换行符拼接）：

GET
/api/v1/openapi/site
url=https://api.example.com
<X-App-Id>
<X-Timestamp>
<X-Nonce>
(空串：GET 无 body)

数据结构

SiteInfo站点详情

字段	类型	说明	示例
site_id	int	站点 ID	1001
site_name	string	站点名称	示例中转站
url	string\|null	站点首页 URL	https://api.example.com
api_urls	string[]	站点 API URL 列表（主/备，按优先级）	["https://api.example.com", "https://backup.example.com"]

GroupInfo分组详情

数据接口

getSiteByURL100积分/万次按站点域名 / 站点URL / API URL 反查站点详情。匹配优先级：API 地址精确匹配 → 完整域名 → 顶级域名（www.aaa.com 可命中 aaa.com）。

GET/api/v1/openapi/site

调用示例（getSiteByURL，含签名实现）

以下示例以 getSiteByURL 完整演示签名与请求，更换 path 与 query 参数即可调用其它接口。

APP_ID="dc_oa_your_app_id"
API_SECRET="your_api_secret"
METHOD="GET"
REQ_PATH="/api/v1/openapi/site"
QUERY="url=https://api.example.com"
TIMESTAMP="$(date +%s)"
NONCE="$(openssl rand -hex 16)"
BODY_DIGEST=""

# 构造签名串并计算 HMAC-SHA256
SIGN_STRING="$(printf '%s\n%s\n%s\n%s\n%s\n%s\n%s' \
  "$METHOD" "$REQ_PATH" "$QUERY" "$APP_ID" "$TIMESTAMP" "$NONCE" "$BODY_DIGEST")"
SIGNATURE="$(printf '%s' "$SIGN_STRING" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $NF}')"

curl -G "https://api.zzstan.com$REQ_PATH" \
  --data-urlencode "url=https://api.example.com" \
  -H "X-App-Id: $APP_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

字段	类型	说明	示例
group_id	int	分组 ID	2001
group_name	string	分组（渠道）名称	Claude 专线
ratio	float\|null	计价倍率（相对官方基准价）	1.5
models	string[]	分组提供的模型 key 列表	["claude-sonnet-4-5", "claude-opus-4-5"]
concurrency_limit	int\|null	分组并发数限制（未采集时为 null）	50

ModelStat分组模型状态

字段	类型	说明	示例
model_key	string	模型 key	claude-sonnet-4-5
model_family	string\|null	模型家族（claude / gpt / glm 等）	claude
model_name	string\|null	模型展示名	Claude Sonnet 4.5
available	bool	当前是否可用（分组健康且站点未 outage）	true
ttft_p50_ms	float\|null	首 token 时间全网基准中位数（毫秒，跨站可比）	820.5
avg_latency_s	float\|null	该站该模型平均响应延迟（秒，实测）	2.31
online_rate	float\|null	在线率（%，实测聚合）	99.2
success_rate	float\|null	AI 请求成功率全网基准（%，跨站可比）	98.5

QueryGroupsItem站点与其下分组

字段	类型	说明	示例
site	SiteInfo	站点详情	{ site_id, site_name, url, api_urls }
groups	GroupInfo[]	该站点下的分组列表	[{ group_id, group_name, ratio, models, concurrency_limit }]

参数	类型	必填	说明	示例
url	string	是	站点域名或站点URL 或 API URL	https://api.example.com

响应示例

{
  "code": "0",
  "message": "ok",
  "data": {
    "site_id": 1001,
    "site_name": "示例中转站",
    "url": "https://api.example.com",
    "api_urls": ["https://api.example.com", "https://backup.example.com"]
  }
}

getGroupsBySite100积分/万次按站点 ID 列出其下当前提供的分组。

GET/api/v1/openapi/groups

参数	类型	必填	说明	示例
site_id	int	是	站点 ID	1001

返回：GroupInfo[]。

响应示例

{
  "code": "0",
  "message": "ok",
  "data": [
    {
      "group_id": 2001,
      "group_name": "Claude 专线",
      "ratio": 1.5,
      "models": ["claude-sonnet-4-5", "claude-opus-4-5"],
      "concurrency_limit": 50
    },
    {
      "group_id": 2002,
      "group_name": "GPT 通道",
      "ratio": 1.2,
      "models": ["gpt-4o", "gpt-4o-mini"],
      "concurrency_limit": null
    }
  ]
}

groupStat100积分/万次按分组 ID 查其下模型的当前可用状态与性能指标。可选 model_key 仅返回某模型。

GET/api/v1/openapi/group-stat

参数	类型	必填	说明	示例
group_id	int	是	分组 ID	2001
model_key	string	否	仅返回该模型的状态	claude-sonnet-4-5

返回：ModelStat[]。

响应示例

{
  "code": "0",
  "message": "ok",
  "data": [
    {
      "model_key": "claude-sonnet-4-5",
      "model_family": "claude",
      "model_name": "Claude Sonnet 4.5",
      "available": true,
      "ttft_p50_ms": 820.5,
      "avg_latency_s": 2.31,
      "online_rate": 99.2,
      "success_rate": 98.5
    },
    {
      "model_key": "claude-opus-4-5",
      "model_family": "claude",
      "model_name": "Claude Opus 4.5",
      "available": false,
      "ttft_p50_ms": 1200.0,
      "avg_latency_s": 4.52,
      "online_rate": 95.0,
      "success_rate": 92.3
    }
  ]
}

queryGroups100积分/万次按条件筛选站点+分组，按站点去重最多返回 5 个站点。所有参数可选。

GET/api/v1/openapi/query-groups

参数	类型	必填	说明	示例
model_key	string	否	模型 key	claude-sonnet-4-5
model_family	string	否	模型家族（claude / gpt）	claude
max_ratio	float	否	最大倍率	2
max_ttft	float	否	最大平均响应延迟（秒，近似 ttft，基于实测 avg_latency_s）	3
min_success_rate	float	否	最小在线率（%，近似成功率，基于 online_rate）	95
min_concurrency	int	否	最小并发数限制（仅对非空 concurrency_limit 生效）	10
sort	string	否	排序字段：ratio(升序,默认) / ttft(升序) / success_rate(降序) / concurrency(降序)	ratio

返回：QueryGroupsItem[]（每项含 site 与 groups）。

响应示例

{
  "code": "0",
  "message": "ok",
  "data": [
    {
      "site": {
        "site_id": 1001,
        "site_name": "示例中转站",
        "url": "https://api.example.com",
        "api_urls": ["https://api.example.com"]
      },
      "groups": [
        {
          "group_id": 2001,
          "group_name": "Claude 专线",
          "ratio": 1.5,
          "models": ["claude-sonnet-4-5", "claude-opus-4-5"],
          "concurrency_limit": 50
        }
      ]
    }
  ]
}

站点	站点分组	人气	倍率	倍率变动	掺水率	延迟	7天可用率	可用状态

站点	站点分组	人气	倍率	倍率变动	掺水率	延迟	7天可用率	可用状态

站点	站点分组	人气	倍率	倍率变动	掺水率	延迟	7天可用率	可用状态

站点	站点分组	人气	倍率	倍率变动	掺水率	延迟	7天可用率	可用状态

站点	站点分组	人气	倍率	倍率变动	掺水率	延迟	7天可用率	可用状态