Generate images · Tovano guides

Image models run as tasks: you create a task, it runs, and it ends as completed or failed. This guide uses image/demo-1 at $0.020 per image.

1. Look at the model's inputs

Every model publishes its input fields and limits:

curl https://api.tovano.ai/v1/models/image/demo-1 \
  -H "Authorization: Bearer $TOVANO_API_KEY"

For image models the fields are:

Field	Type	Default	Notes
`prompt`	string		Required. What to draw, up to 4,000 characters
`size`	string	`1024x1024`	`512x512`, `1024x1024`, `1024x1536` or `1536x1024`
`n`	integer	`1`	Number of images, 1 to 4. This is what you are charged for
`seed`	integer	random	The same seed and prompt give the same image

2. Create the task

curl https://api.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 on a white table, soft daylight",
      "size": "1024x1024",
      "n": 2
    }
  }'

The response comes back at once with "status": "queued" and an id such as tsk_9f2c41ab7d0e. At this point $0.040 is reserved on your balance; nothing is charged yet.

3. Wait for the result

Ask for the task until the status is completed or failed. Start with a short interval and back off; image tasks usually finish in a few seconds.

curl https://api.tovano.ai/v1/tasks/tsk_9f2c41ab7d0e \
  -H "Authorization: Bearer $TOVANO_API_KEY"

{
  "id": "tsk_9f2c41ab7d0e",
  "model": "image/demo-1",
  "status": "completed",
  "output": {
    "images": [
      { "url": "https://files.tovano.ai/...", "content_type": "image/png", "width": 1024, "height": 1024 },
      { "url": "https://files.tovano.ai/...", "content_type": "image/png", "width": 1024, "height": 1024 }
    ]
  },
  "unit": "image",
  "units": 2,
  "charged_micro": 40000
}

charged_micro: 40000 is $0.040: two images at $0.020. For production, use a webhook instead of polling; see Receive results with webhooks.

4. The same in TypeScript

The SDK creates the task and waits for it in one call:

import { Tovano, formatUsd } from "tovano";

const tovano = new Tovano(); // reads TOVANO_API_KEY

const task = await tovano.tasks.run({
  model: "image/demo-1",
  input: { prompt: "Product photo of a blue ceramic mug", size: "1024x1024", n: 2 },
});

if (task.status === "failed") {
  console.error(task.error?.message, "(not charged)");
} else {
  for (const img of task.output.images as { url: string }[]) console.log(img.url);
  console.log(`Charged ${formatUsd(task.charged_micro)}`);
}

5. Save the files

Output URLs are signed and work for 24 hours, and files are deleted after 30 days. Download the images you want to keep to your own storage straight after the task completes.

import { writeFile } from "node:fs/promises";

for (const [i, img] of (task.output.images as { url: string }[]).entries()) {
  const res = await fetch(img.url);
  await writeFile(`mug-${i + 1}.png`, Buffer.from(await res.arrayBuffer()));
}

Tips

Reproducible results. Pass a seed and keep it with the image. The same prompt, size and seed give the same image.
Variations. Ask for n: 4 in one task rather than four tasks with n: 1. The price is the same and you get one result to handle.
Cost control. The estimate for an image task is exact: n times the price. Check it on the models page before you raise n in production.

Stuck? Write to support@tovano.ai with the task ID and the X-Request-Id of the response.