Agent jobs: several models, one task, an itemised charge

Many useful results need more than one model. An ad needs a headline, body copy and an image that matches them. A product page needs a description and a set of photos. Chaining those calls yourself means more code, more failure cases and more requests to keep track of.

An agent job does the chaining on our side. You send one request and get one task back. Inside it, each step is a task of its own, with its own model, units and charge.

The first agent job: Ad Kit

agent/ad-kit-1 takes a short brief and returns a headline, body copy and a matching image.

curl https://api.tovano.ai/v1/tasks \
  -H "Authorization: Bearer $TOVANO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent/ad-kit-1",
    "input": {
      "product": "Insulated steel water bottle, 750 ml",
      "audience": "commuters",
      "tone": "plain"
    }
  }'

It runs two steps:

A typical run costs about $0.022: a fraction of a cent for the copy and $0.020 for the image. You can choose other models for each step with text_model and image_model; the job then charges their prices.

One task, every charge visible

The finished task lists its steps:

{
  "id": "tsk_51ad0c7e93b2",
  "model": "agent/ad-kit-1",
  "status": "completed",
  "output": {
    "headline": "Cold at nine, still cold at five",
    "body": "...",
    "image": { "url": "https://files.tovano.ai/..." }
  },
  "charged_micro": 21588,
  "steps": [
    { "name": "copy", "model": "text/demo-chat-1", "status": "completed", "charged_micro": 1588 },
    { "name": "image", "model": "image/demo-1", "status": "completed", "units": 1, "charged_micro": 20000 }
  ]
}

The job's charged_micro is the sum of its steps. In your usage reports, the steps count under their own models, so the per-model numbers on your invoice stay correct.

When a step fails

If any step fails, the job fails as a whole. Steps that already completed are refunded in full, and the ledger shows each charge with its matching refund. As with every task on Tovano, a failed job costs nothing.

What comes next

We will add more agent jobs where chaining models is the common case, starting with product listings and short video ads. Each will publish its steps and a typical cost on the models page before you run it. If you have a chain you run often, tell us at hello@tovano.ai.

The guide Run an agent job walks through the request, the steps and the result in more detail.