API reference

Base URL https://api.tovano.ai/v1. Authenticate with Authorization: Bearer tvn_live_.... Optional headers: Idempotency-Key, X-Tovano-Customer. The machine-readable version is /openapi.json.

Endpoints

Method	Path	What it does
GET	`/v1/models`	List models with type, unit and price
GET	`/v1/models/{id}`	One model, with its input schema
POST	`/v1/chat/completions`	Text models. OpenAI-compatible, with streaming
POST	`/v1/tasks`	Run any other model
GET	`/v1/tasks/{id}`	Task status, output, units and charge
GET	`/v1/tasks`	List tasks. Filter by `status`, `model`, `customer`
GET	`/v1/balance`	Current balance
GET	`/v1/usage`	Usage and spend, `group_by=model`, `customer` or `day`

GET /v1/models

Returns { "data": [Model] }.

Field	Type	Description
`id`	string	`type/name`
`type`	string	`image`, `video`, `audio`, `text` or `agent`
`name`	string	Display name
`unit`	string	`image`, `second`, `minute`, `1k_chars`, `1m_input_tokens`, `1m_output_tokens`
`price_micro`	integer	Price per unit in micro-dollars
`prices`	array	Text models: one price per unit (input and output)

POST /v1/tasks

Body: model, input, optional customer and webhook_url. Returns a task.

GET /v1/tasks/{id}

Returns the task. 404 not_found if it isn't in your organisation.

GET /v1/tasks

Query: status, model, customer, limit (max 100), offset. Returns { "data": [Task], "has_more": boolean }.

POST /v1/chat/completions

The OpenAI chat completions request. See Chat.

GET /v1/balance

{ "balance_micro": 2539815213, "currency": "usd" }

GET /v1/usage

Query: group_by (model, customer or day), from and to as YYYY-MM-DD.

{
  "group_by": "customer",
  "from": "2026-11-01",
  "to": "2026-11-13",
  "data": [
    { "key": "client-0482", "tasks": 4120, "charged_micro": 384370000 },
    { "key": "client-0117", "tasks": 2870, "charged_micro": 267890000 }
  ]
}