Tasks

Every model except text chat runs as a task. You create it, it runs, and it ends as completed or failed.

Create a task

POST /v1/tasks

Field	Type	Description
`model`	string	Required. A model ID, such as `image/demo-1`
`input`	object	Required. The model's input fields, see its `input_schema`
`customer`	string	Optional. Your own ID for the end customer
`webhook_url`	string	Optional. We POST the task here when it finishes

curl https://api.tovano.ai/v1/tasks \
  -H "Authorization: Bearer $TOVANO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1182-hero" \
  -d '{
    "model": "video/demo-1",
    "input": { "prompt": "Slow push-in on a cup of coffee", "duration": 5 },
    "customer": "client-0482",
    "webhook_url": "https://example.com/hooks/tovano"
  }'

The task object

{
  "id": "tsk_9f2c41ab7d0e",
  "model": "video/demo-1",
  "status": "completed",
  "customer": "client-0482",
  "input": { "prompt": "Slow push-in on a cup of coffee", "duration": 5 },
  "output": { "video": { "url": "https://files.tovano.ai/..." } },
  "unit": "second",
  "units": 5,
  "charged_micro": 500000,
  "error": null,
  "created_at": "2026-11-13T09:30:00Z",
  "completed_at": "2026-11-13T09:30:41Z"
}

Status

Status	Meaning
`queued`	Accepted, waiting to start. The estimate is reserved.
`running`	A provider is working on it
`completed`	Done. `output` is set and `charged_micro` is final
`failed`	It did not finish. `error` says why. Not charged.

List tasks

curl "https://api.tovano.ai/v1/tasks?status=failed&customer=client-0482" \
  -H "Authorization: Bearer $TOVANO_API_KEY"

Filter by status, model and customer.

Output files

Output URLs are signed and work for 24 hours. Files are deleted after 30 days. Download what you want to keep.

Agent jobs

An agent job such as agent/ad-kit-1 runs several models in a row. The task lists each step in steps, with its own model, units and charge. The task's charged_micro is the sum of its steps.