# 简介

> 通过统一接口调用多款图片与视频生成模型，保留原厂参数、按次透明计费并支持 Webhook 回调。

## Kerox 提供什么

Kerox 为字节跳动、阿里巴巴等厂商的图片与视频模型提供统一的 HTTP API。所有模型共用同一套任务生命周期（`POST /v1/tasks` 提交、轮询或 Webhook 收结果、下载输出文件），同时完整保留各模型的原厂输入参数。

- **接口地址**：`https://api.kerox.ai/v1`
- **身份鉴权**：`Authorization: Bearer <your-api-key>`
- **数据格式**：请求与响应均为 JSON（`/v1/files` 的表单直传除外）
- **计费方式**：美元字符串（保留 4 位小数，如 `"0.0300"`），直接从钱包余额扣费

## 核心接口一览

| 接口 | 作用 |
| --- | --- |
| `POST /v1/tasks` | 提交生成任务（支持 `wait_seconds` 同步等待最多 60 秒） |
| `GET /v1/tasks/{id}` | 查询任务状态、输出文件、实际花费与失败详情 |
| `GET /v1/tasks` | 按状态或模型筛选任务列表（游标翻页） |
| `POST /v1/tasks/{id}/cancel` | 取消仍在 `queued` 状态的任务并释放冻结金额 |
| `GET /v1/models` | 获取模型目录、实时 `input_schema` 与当前账户价格 |
| `POST /v1/estimate` | 提交前预估费用，不建任务、不冻结资金、不占限流配额 |
| `POST /v1/files` | 上传参考图、参考视频或音频（保留 7 天） |
| `GET /v1/account` | 查询余额、冻结中金额、限流上限与进行中的任务数 |
| `GET /v1/usage` | 按天、按模型查询用量和花费 |

## 原厂格式与统一格式

默认情况下，`input` 直接沿用模型厂商的原厂参数名（`format: "native"`），可在各模型的 `input_schema` 中查看。如果希望在多个模型间切换时不重写 `prompt`、`images`、`aspect_ratio`、`resolution`、`duration` 等高频字段，可以在支持的模型上使用 `format: "unified"`。

## 下一步

- [快速开始](https://kerox.ai/docs/quickstart): 大约两分钟内拿 Key、提交任务并拿到第一张生成图。
- [价格与计费](https://kerox.ai/docs/pricing-billing): 了解冻结、结算、失败退回，以及按 token 计费的视频怎么折算。
- [API 参考](https://kerox.ai/docs/api): 基于 OpenAPI 3.1 的交互式接口文档，可填入 Key 直接调试。
- [模型目录](https://kerox.ai/docs/models): 查看从配置自动生成的参数表、实时价格与代码示例。
