# 聚搜GO API

Base URL: `https://jusouai.cn`；鉴权：`Authorization: Bearer <你的密钥>`；一份积分，所有引擎通用。

## POST /v1/anysearch/search · AnySearch 搜索

与 AnySearch 官方 /v1/search 一致：请求体、返回体原样，只把 request_id 换成我方的。

计费：1 积分/次

兼容官方 `https://api.anysearch.com/v1/search`：换成 `https://jusouai.cn/v1/anysearch/search` + 聚搜GO 密钥。

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `query` | string | 是 | 搜索词 |
| `max_results` | integer | 否 | 返回条数，1-10 |
| `tag` | string | 否 | 官方垂直领域参数，原样透传 |
| `params` | object | 否 | 官方扩展参数，原样透传 |
| `format` | string | 否 | 官方返回格式参数，原样透传 |

```bash
curl https://jusouai.cn/v1/anysearch/search \
  -H "Authorization: Bearer $JUSOU_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "量子计算 最新进展", "max_results": 5}'
```

## POST /v1/search · 统一搜索

一种写法调任意引擎，返回统一结构；某引擎不支持的公共参数返回 400 说明，不静默忽略。

计费：按所选引擎计

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `engine` | string | 是 | 引擎：anysearch；必填，不自动路由 |
| `query` | string | 是 | 搜索词 |
| `num_results` | integer | 否 | 返回条数（按各引擎上限） |
| `depth` | string | 否 | basic / advanced / deep（引擎不支持时报错） |
| `time_range` | string | 否 | day / week / month / year |
| `include_domains` | array | 否 | 只搜这些域名 |
| `exclude_domains` | array | 否 | 排除这些域名 |
| `language` | string | 否 | 语言，如 zh |
| `raw` | boolean | 否 | true 时附带该引擎官方原生返回 |
| `extra` | object | 否 | 引擎专属参数，原样透传 |

```bash
curl https://jusouai.cn/v1/search \
  -H "Authorization: Bearer $JUSOU_KEY" \
  -H "Content-Type: application/json" \
  -d '{"engine": "anysearch", "query": "量子计算", "num_results": 5}'
```

## POST /v1/redeem · 兑换卡密

不带密钥时：兑换并开户，返回 api_key（只显示一次）。带密钥时：兑换到当前账户。

计费：免费

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `code` | string | 是 | 兑换码，形如 JS-XXXX-XXXX-XXXX |

```bash
curl https://jusouai.cn/v1/redeem \
  -H "Content-Type: application/json" \
  -d '{"code": "JS-ABCD-EFGH-JKLM"}'
```

## GET /v1/me · 余额与权益

total = 可用积分合计；entitlements 列出每项权益及到期时间。

计费：免费

```bash
curl https://jusouai.cn/v1/me \
  -H "Authorization: Bearer $JUSOU_KEY"
```

## GET /v1/engines · 引擎目录

当前开放（live）与即将上线（coming）的引擎、简介与接口路径；只有 live 的引擎可以调用。

计费：免费

```bash
curl https://jusouai.cn/v1/engines
```

## GET /v1/usage · 调用流水

最近的调用，每条带引擎 / 操作 / 档位 / 本次扣分（points，未扣为 0）。可按引擎、时间筛选。

计费：免费

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `limit` | integer | 否 | 条数，1-500，默认 50（查询参数） |
| `engine` | string | 否 | 只看这个引擎（查询参数） |
| `period` | string | 否 | today / 7d / 30d，不填为全部（查询参数） |

```bash
curl https://jusouai.cn/v1/usage \
  -H "Authorization: Bearer $JUSOU_KEY"
```

## GET /v1/usage/summary · 按引擎扣分明细

某段时间内各引擎的调用次数、扣分次数、扣分合计，以及按操作 · 档位的细分。

计费：免费

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `period` | string | 否 | today（默认）/ 7d / 30d（查询参数，北京时间按天算） |

```bash
curl https://jusouai.cn/v1/usage/summary \
  -H "Authorization: Bearer $JUSOU_KEY"
```

## GET /v1/pricing · 价目表

每个引擎每个操作 · 档位每次调用的固定积分（含触发条件），以及在售套餐（calls_est = 约可调用基础搜索次数）。一份积分所有引擎通用。

计费：免费

```bash
curl https://jusouai.cn/v1/pricing
```

## 计费口径

- 一份积分，所有引擎通用：任何套餐的积分都能调所有已开放引擎，不按引擎划分；只是不同引擎、档位每次扣分不同。
- 按调用次数扣固定积分，一次一价：基础搜索 1 积分/次，高级档（AI 搜索、深度搜索、更多结果条数）3–5 积分起；每次扣多少由「接口 · 档位」决定（见下方价目），没有附加费，也不会事后补扣。
- 档位由请求参数决定（如某个参数取某个值），对照价目里的「触发条件」；没写到的取值按该操作的默认档计。
- 调用成功（含结果为空）照价目扣分；参数错误、引擎故障、超时、繁忙、暂不可用都不扣分。
- 每次响应头带 x-request-id、x-points-charged（本次扣分，未扣为 0）和 x-points-tier（本次计费档位）。
- 控制台「按引擎扣分明细」可看今日 / 近 7 天 / 近 30 天各引擎的调用次数与扣分；GET /v1/usage/summary 同口径。

## 价目（按引擎）

基础搜索 1 积分/次；一份积分，所有引擎通用。

### AnySearch（anysearch）

| 接口 | 档位 | 触发条件 | 积分/次 |
|---|---|---|---|
| `POST /v1/anysearch/search`（搜索） | `standard`（默认） | 任意参数 | 1 |

## 错误码

| HTTP | code | 含义 | 积分 |
|---|---|---|---|
| 400 | `invalid_request` | 参数错误（网关拦截或引擎判定参数错） | 不扣 |
| 400 | `operation_unavailable` | 该引擎的这个接口 / 档位暂未开放 | 不扣 |
| 400 | `invalid_code` | 兑换码无效或已被使用 | — |
| 401 | `unauthorized` | 缺少密钥或密钥无效 | 不扣 |
| 402 | `insufficient_points` | 积分不足 | 不扣 |
| 403 | `forbidden` | 账户已停用 | 不扣 |
| 404 | `engine_not_found` | 引擎不存在 | 不扣 |
| 404 | `endpoint_not_found` | 该引擎没有这个接口 | 不扣 |
| 429 | `rate_limited` | 超过套餐每秒请求数（排队超过上限） | 不扣 |
| 429 | `engine_busy` | 引擎繁忙 | 不扣 |
| 502 | `engine_error` | 引擎暂时异常（已自动重试） | 不扣 |
| 503 | `engine_unavailable` | 引擎暂不可用或暂未开放 | 不扣 |
| 500 | `internal_error` | 服务内部错误 | 不扣 |