# API Reference

> Kerox public HTTP API (OpenAPI 3.1). One task shape for every image and video model.

- **Base URL**: `https://api.kerox.ai/v1`
- **OpenAPI 3.1 JSON**: https://api.kerox.ai/openapi.json
- **Interactive reference**: https://kerox.ai/docs/api
- **Authentication**: `Authorization: Bearer <api-key>`

## Endpoints

| Method & path | Description |
| --- | --- |
| `POST /v1/tasks` | Create a generation task (optional wait_seconds up to 60 s) |
| `GET /v1/tasks/{id}` | Fetch task status, outputs, cost, and errors |
| `GET /v1/tasks` | List tasks with status/model filters and cursor pagination |
| `POST /v1/tasks/{id}/cancel` | Cancel a queued task and refund its hold |
| `GET /v1/models` | List published models with schemas and live pricing |
| `GET /v1/models/{id}` | Fetch a single model config, schema, and pricing |
| `POST /v1/estimate` | Estimate task cost without creating a task or holding funds |
| `POST /v1/files` | Upload reference files (presigned PUT ≤ 200 MB or multipart ≤ 4 MB) |
| `GET /v1/files/{id}` | Check uploaded file status |
| `GET /v1/account` | Read wallet balance, holds, rate limits, and concurrency |
| `GET /v1/usage` | Query daily and per-model usage and spend |
| `GET /openapi.json` | Machine-readable OpenAPI 3.1 specification |
| `GET /health` | Health check (no auth required) |
