# API 参考

> Kerox 公开 HTTP API（OpenAPI 3.1），所有模型共用统一任务接口。

- **Base URL**: `https://api.kerox.ai/v1`
- **OpenAPI 3.1 JSON**: https://api.kerox.ai/openapi.json
- **交互式文档**: https://kerox.ai/zh/docs/api
- **鉴权**: `Authorization: Bearer <api-key>`

## 接口列表

| 方法与路径 | 说明 |
| --- | --- |
| `POST /v1/tasks` | 创建生成任务（支持 wait_seconds 同步等待最多 60 秒） |
| `GET /v1/tasks/{id}` | 查询任务状态、输出、费用与错误 |
| `GET /v1/tasks` | 任务列表（支持状态、模型筛选与游标翻页） |
| `POST /v1/tasks/{id}/cancel` | 取消 queued 状态的任务并退回冻结金额 |
| `GET /v1/models` | 获取已发布模型、参数 schema 与价格 |
| `GET /v1/models/{id}` | 获取单个模型的完整配置与价格 |
| `POST /v1/estimate` | 预估任务费用，不建任务、不冻结资金 |
| `POST /v1/files` | 上传参考文件（预签名直传 ≤ 200 MB 或表单直传 ≤ 4 MB） |
| `GET /v1/files/{id}` | 查询文件上传状态 |
| `GET /v1/account` | 查询余额、冻结金额、限流与并发数 |
| `GET /v1/usage` | 按天与按模型查询用量和花费 |
| `GET /openapi.json` | 机器可读的 OpenAPI 3.1 规范 |
| `GET /health` | 健康检查（无需鉴权） |
