# Tovano

> One API key, one prepaid balance and one invoice for image, video, audio and text models. Every call is charged per unit at a public price. Failed tasks are never charged.

Base URL: https://tovano.ai
Auth: `Authorization: Bearer tvn_live_...` (create a key at https://tovano.ai/app/keys)
Money: integer micro-dollars in fields ending in `_micro` (1 USD = 1000000).
OpenAPI: https://tovano.ai/openapi.json

## Models

- `image/demo-1` (image): Demo Image 1. $0.02 per image.
- `video/demo-1` (video): Demo Video 1. $0.10 per second.
- `audio/demo-tts-1` (audio): Demo Voice 1. $0.03 per 1K characters.
- `text/demo-chat-1` (text): Demo Chat 1. $1.00 per 1M input tokens, $4.00 per 1M output tokens.
- `agent/ad-kit-1` (agent): Ad Kit 1. charged per step at each step model's price.

## Run a model (any type)

```bash
curl https://tovano.ai/v1/tasks \
  -H "Authorization: Bearer $TOVANO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"image/demo-1","input":{"prompt":"Product photo of a blue ceramic mug","n":2},"customer":"client-0482"}'
```

Returns a task (`status: "queued"`). Poll `GET /v1/tasks/{id}` until `status` is `completed` or `failed`, or pass `webhook_url`.
Completed tasks have `output` (files as signed `url`s), `unit`, `units` and `charged_micro`.
Get each model's input fields from `GET /v1/models/{id}` (`input_schema`).

## Chat (OpenAI-compatible)

```ts
import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://tovano.ai/v1", apiKey: process.env.TOVANO_API_KEY });
const r = await client.chat.completions.create({ model: "text/demo-chat-1", messages: [{ role: "user", content: "Hi" }], stream: true });
```

## TypeScript SDK (no dependencies)

```ts
import { Tovano } from "tovano";
const tovano = new Tovano({ apiKey: process.env.TOVANO_API_KEY });
const task = await tovano.tasks.create({ model: "image/demo-1", input: { prompt: "A blue mug" } });
const done = await tovano.tasks.wait(task.id);
```

## Errors

Shape: `{"error":{"type":"...","code":"...","message":"...","param":"..."}}`
- 401 `invalid_api_key`
- 402 `insufficient_credits` (add credits at https://tovano.ai/app/billing) or `spend_limit_reached`
- 404 `not_found`
- 409 `conflict` (Idempotency-Key reused with a different body)
- 422 `invalid_request` (`param` names the field)
- 429 `rate_limited` (respect `Retry-After`)
- 500 `internal_error`, 502 `provider_error` (not charged)

## Headers

- `Idempotency-Key`: safe retries for 24 hours.
- `X-Tovano-Customer`: tag a call with your end-customer id; see spend per customer in `GET /v1/usage?group_by=customer`.

## Webhooks

POST of the task object to `webhook_url` when it finishes. Verify `Tovano-Signature: t=<unix>,v1=<hex>`: HMAC-SHA256 of `${t}.${rawBody}` with the project's webhook secret (App → Settings). Retried 3 times.

## Testing

Put `[fail]` in a demo model prompt to make the task fail on purpose (it is not charged).