> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argil.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How it works

> Generations that take minutes, using your files, and what you pay.

## A generation, step by step

1. **Pick a model.** The assistant calls `search_models` to compare models, modes and prices, then `get_model` for the exact fields and allowed values of the mode it picks.
2. **Generate.** It calls `generate_media` with the model, the mode and its `input`. Argil checks the input against that model's rules first: a wrong value comes back named, with what is allowed, and nothing is spent.
3. **Wait.** A call answers within about 40 seconds.
   * **Images** are usually done by then: the answer has the result.
   * **Videos** take minutes. The answer says `processing` and how long that model usually takes; the assistant checks again with `get_generation`, which waits up to 40 seconds per call, until the video is ready.
4. **Get the result.** A finished generation gives the file's URL, which never expires, a small preview the assistant can look at, its asset id, and what was charged. Every output is also in your [Argil library](https://www.argil.ai) and playground.

> [!NOTE]
>
> A generation keeps running even if the conversation stops. Ask "check on my last video" later instead of asking again: a new request starts, and bills, a new generation.

To iterate, reuse a result: "now make it move" passes the image as the first frame of a video; "same character, new scene" passes the character as a reference.

## Your files

Anything a model takes as an image, a video or an audio (a first frame, a reference, an audio to lip-sync) can be:

| You give | The assistant passes | Comes from |
| - | - | - |
| A file of your library | `"asset_7ab7bff2…"` | Your uploads and every past output |
| A public link | `{"type": "url", "url": "https://…"}` | Any https file; Argil downloads it into your library |
| A local file (coding agents) | Uploaded first with `add_asset`, then its asset id | Your computer |
| One of your elements | `{"type": "element", "id": "elm_…", "plate": "front"}` | Characters, styles, locations and props built in Argil |

You never write these yourself: say "use my latest upload", "this photo" or "my character Mia", and the assistant finds the id.

* **Elements** carry labelled reference images called plates (`front`, `profile`, `hero`…). Without `plate`, an element brings all of them.
* **Voices and avatars** come from `list_voices` and `list_avatars`: a speech model or Argil Atom takes a voice as `{"id": "…"}`, and an avatar is passed as its image.
* **Naming references in the prompt.** References are numbered in the order given. To say which is which, use the wording the model expects, given in its `prompt` field (`get_model` shows it).
* **Limits:** a URL must be public; an upload can be up to 2 GB. A file still processing when a generation starts is waited for, up to 60 seconds.

## Credits

Generations spend your workspace's credits, at the same prices as in the app. Everything else (models, library, estimates) is free.

* **Prices** are on each [model page](https://docs.argil.ai/v2/models/overview.md), and in `search_models` and `get_model`. Ask "how much would it cost?" and the assistant calls `estimate_generation`, which prices the exact request and says whether your balance covers it.
* **A ceiling per generation.** "At most 30 credits" becomes `max_credits`: a generation above it is refused before anything is spent, with its price.
* **Retries never pay twice.** With an `idempotency_key`, a retried call returns the generation already started.
* **Failures are refunded.** Credits are reserved when a generation starts and come back if it fails. Some modes are priced on what the model actually produced: the reserve is adjusted at the end and the difference refunded.
* **Short balance.** The assistant says how many credits are needed. Credits are bought in the [Argil app](https://www.argil.ai), not through the assistant.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.