# 通用 API

这些接口与具体模型无关，可用于接入前检查、模型发现和任务查询。示例中的平台地址按当前品牌配置填入；需要鉴权的请求使用 `Authorization: Bearer $API_KEY`。

| 接口 | 用途 | 鉴权 |
| --- | --- | --- |
| `GET /v1/models` | 当前可调用 LLM 型号和原生协议 | 无需登录 |
| `GET /v1/media-models` | 启用的媒体模型、输入 schema 和公开价格配置 | 无需登录 |
| `GET /v1/balance` | API Key 所属账户的积分余额 | Bearer API Key |
| `GET /v1/tasks/{task_id}` | 查询单个媒体任务 | Bearer API Key |

响应示例均为字段节选，数值、模型名和 ID 为示意值。

## 查询模型

### LLM 模型

```bash
curl "https://newrouters.com/v1/models"
```

```json
{
  "data": [
    {
      "id": "MODEL_ID",
      "model": "MODEL_ID",
      "protocol": "openai"
    }
  ]
}
```

- 使用响应中的 `id` / `model` 作为准确模型 ID。
- `protocol` 为 `openai`、`claude` 或 `gemini`，按对应模型文档使用原生请求结构。
- 还会返回 `capabilities`、`context_limit` 和 `max_output_tokens`。
- 列表反映当前供给；公开目录不代表你的 API Key 已获全部模型调用权限。

### 媒体模型与参数

```bash
curl "https://newrouters.com/v1/media-models"
```

```json
{
  "data": [
    {
      "model": "MODEL_ID",
      "type": "image",
      "contract_version": 1,
      "request_schema": { "type": "object" }
    }
  ]
}
```

返回启用的图片、视频或音频模型，并包含 `display_name`、`description`、`request_schema` 与 `pricing`。`request_schema` 描述任务的 **input**，不是整个 `model + input` 请求。用它核对必填字段、枚举和限制；公开价格配置不替代账户实际价格。

## 查询余额

```bash
curl "https://newrouters.com/v1/balance" \
  -H "Authorization: Bearer $API_KEY"
```

HTTP `200`：

```json
{
  "points": "123.456789"
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `points` | decimal string | Key 所属账户的积分余额，以字符串返回 |

- 返回的是账户积分，不是人民币或美元金额，也不是单个 Key 的限额余量。
- 响应直接为 `{ "points": "..." }`，没有 `data` 包装。
- 无效或缺失 Key 返回 `401`；Key 所属账户不存在时返回 `404`。
- 客户端处理积分时保留十进制精度。

## 查询任务

### 单个任务

```bash
curl "https://newrouters.com/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer $API_KEY"
```

`TASK_ID` 替换为创建响应的 `id`，不要使用上游任务 ID。HTTP `200` 表示查询成功，是否生成完成由 `status` 判断。

```json
{
  "id": "TASK_ID",
  "status": "succeeded",
  "model": "MODEL_ID",
  "result": { "assets": ["https://example.com/output.png"] },
  "error": null
}
```

| status | 处理方式 |
| --- | --- |
| `pending` | 已受理，继续查询同一任务 |
| `processing` | 处理中，继续查询同一任务 |
| `succeeded` | 读取 `result.assets[]` 的资产 URL |
| `failed` | 读取 `error.code` 和 `error.message` |

完整响应还包括 `type`、`request`、积分估算与结算字段、创建和完成时间。用创建任务所属账户的 Key 查询；不要把创建接口的 `202` 当作生成完成。

`/v1/account/*` 是控制台会话接口，不能默认用 Bearer API Key 调用。例如账单明细 `/v1/account/billing/usage` 要求登录会话；服务端查询余额使用上面的 `/v1/balance`。

[快速开始](/zh/docs/quickstart) · [模型文档](/zh/docs)