An agent job chains several models on our side and returns one task. agent/ad-kit-1 writes ad copy with a text model, then makes a matching image with an image model. A typical run costs about $0.022.
1. The inputs
| Field | Type | Default | Notes |
|---|---|---|---|
product | string | Required. What the ad is for, up to 500 characters | |
audience | string | Who the ad speaks to, up to 200 characters | |
tone | string | plain | plain, playful or premium |
text_model | string | text/demo-chat-1 | Any text model in the catalogue |
image_model | string | image/demo-1 | Any image model in the catalogue |
2. Start the job
curl https://api.tovano.ai/v1/tasks \
-H "Authorization: Bearer $TOVANO_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Tovano-Customer: client-0482" \
-d '{
"model": "agent/ad-kit-1",
"input": {
"product": "Insulated steel water bottle, 750 ml",
"audience": "commuters",
"tone": "plain"
}
}'
Before the job starts, we reserve the estimate for both steps: about 400 input and 300 output tokens for the copy, plus one image.
3. Read the steps
Poll GET /v1/tasks/{id} or wait for a webhook. While the job runs, steps fills in:
{
"id": "tsk_51ad0c7e93b2",
"model": "agent/ad-kit-1",
"status": "completed",
"unit": "run",
"output": {
"headline": "Cold at nine, still cold at five",
"body": "...",
"image_prompt": "...",
"image": { "url": "https://files.tovano.ai/...", "content_type": "image/png" }
},
"charged_micro": 21588,
"steps": [
{
"id": "tsk_51ad0c7e93b3",
"name": "copy",
"model": "text/demo-chat-1",
"status": "completed",
"charged_micro": 1588
},
{
"id": "tsk_51ad0c7e93b4",
"name": "image",
"model": "image/demo-1",
"status": "completed",
"unit": "image",
"units": 1,
"charged_micro": 20000
}
]
}
The job's charged_micro is the sum of its steps. Each step is also a task you can open on its own.
4. In TypeScript
import { Tovano, formatUsd } from "tovano";
const tovano = new Tovano();
type AdKit = { headline: string; body: string; image: { url: string } };
const job = await tovano.tasks.run<AdKit>({
model: "agent/ad-kit-1",
input: { product: "Insulated steel water bottle, 750 ml", audience: "commuters" },
customer: "client-0482",
});
if (job.status === "completed") {
console.log(job.output.headline);
console.log(job.output.body);
console.log(job.output.image.url);
}
console.log("Charged", formatUsd(job.charged_micro));
5. When a step fails
If a step fails, the whole job fails. Steps that already completed are refunded, and the job ends with charged_micro: 0. Your ledger shows each step's charge and its refund. Retry with the same input when the cause was temporary (provider_error); fix the input when it was invalid_request.
Tips
- Choose cheaper or better models per step. Set
text_modelandimage_model. The job charges the prices of the models you pick. - See it in the dashboard. The Playground runs agent jobs and shows each step as it completes.
- Usage reports stay per model. The copy step counts under the text model and the image step under the image model.