> ## 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.

# Tools

> Every tool of the Argil MCP server, its arguments and what it returns.

Your assistant reads these tools, and their exact arguments, from the server: you never call them yourself. This page is for checking what an assistant can do, and for building agents.

| Tool | Does | Main arguments |
| - | - | - |
| `search_models` | Models your workspace can use, with modes and prices | `query`, `type` (`image`, `video`, `audio`), `mode` |
| `get_model` | One model; with a mode, its exact fields, limits and price | `model`, `mode` |
| `estimate_generation` | The price of a request, and whether the balance covers it | `model`, `mode`, `input` |
| [`generate_media`](#generate_media) | Start a generation. **Spends credits** | `model`, `mode`, `input`, `max_credits`, `idempotency_key` |
| [`get_generation`](#get_generation) | Status, cost and outputs; can wait | `id`, `wait_seconds` |
| `list_generations` | Past generations, newest first | `model`, `mode`, `created_after`, `metadata` |
| `delete_generation` | Remove a finished generation (outputs stay in the library) | `id` |
| [`add_asset`](#add_asset) | Add a file to the library | `url`, `file` or `upload` |
| `get_asset` | One file; can wait until it is ready | `id`, `wait_seconds` |
| `list_assets` | Files of the library: uploads, imports and outputs | `type` |
| `delete_asset` | Remove a file | `id` |
| `list_elements` | Characters, styles, locations, props and lore, with their plates | `kind`, `ids` |
| `list_voices` | Voices to speak with: yours and Argil's | `visibility`, `language`, `gender` |
| `list_avatars` | Avatars to animate, with their image: yours and Argil's | `visibility`, `orientation` |
| `get_balance` | Credits available and reserved | |
| `list_webhook_endpoints`, `create_webhook_endpoint`, `update_webhook_endpoint`, `delete_webhook_endpoint` | URLs Argil calls, with a signed `POST`, when a generation succeeds or fails | `url`, `enabled_events` |

Lists take `limit` (1 to 50) and `starting_after` to page. Only `generate_media` spends credits; `delete_generation`, `delete_asset` and `delete_webhook_endpoint` are marked destructive, so clients ask before running them.

## generate\_media

Generates images, videos or audio with any model of your workspace.

**model** `string` *required*

Model id, for example `seedance-2.5`.

**mode** `string` *required*

One of the model's modes: `text-to-image`, `image-to-video`, `reference-to-video`…

**input** `object`

The mode's fields, as `get_model` lists them. A file field (`first_frame`, `references`, `image`…) takes an asset id, a URL or an element: see [Your files](https://docs.argil.ai/v2/mcp/how-it-works.md#your-files).

**max\_credits** `number`

Refuse the generation, before spending, if it would cost more.

**idempotency\_key** `string`

A new UUID per generation, the same one on a retry: the retry returns the generation already started. Reusing a key for a different request is refused.

**wait\_seconds** `integer` (default: 40)

How long the call waits for the result, 0 to 40.

**metadata** `object`

Up to 20 string pairs, to find the generation later with `list_generations`.

**include\_previews** `boolean` (default: true)

Include small image previews in the result.

```json Image from a reference theme={null}
{
  "model": "nano-banana-2.1",
  "mode": "image-to-image",
  "input": {
    "prompt": "Put the bottle on wet black stone with a rim light, same angle",
    "references": ["asset_7ab7bff259cb4b7e825f64ebff4595d7"]
  },
  "idempotency_key": "9d0c4e1a-2b7f-4c3e-8a5d-6f1b0e2c7a93"
}
```

```json Video from a first frame theme={null}
{
  "model": "seedance-2.5",
  "mode": "image-to-video",
  "input": {
    "prompt": "Steam rises slowly, the camera pushes in",
    "first_frame": "asset_e8b14d2c6a9f4b7e8c3d1a0f5b2e9c46",
    "duration": 5
  },
  "max_credits": 60,
  "idempotency_key": "4b2f8c1e-9a7d-4e3b-8c6f-1d0e5a2b7c94"
}
```

```json Talking avatar theme={null}
{
  "model": "argil-atom",
  "mode": "script-to-video",
  "input": {
    "image": { "type": "url", "url": "https://…/avatar.png" },
    "text": "Welcome to the spring collection.",
    "voice": { "id": "6f1c2a9e-4b7d-4c1e-9a3f-0b5d8e2c7a14" }
  },
  "idempotency_key": "9d3e1b7a-2c4f-4a8e-b6d0-5f1a3c7e9b28"
}
```

The answer is the finished generation, or, past `wait_seconds`, its status and the next call:

```text theme={null}
Generation gen_6f1c2a9e4b7d4c1e9a3f0b5d8e2c7a14 (seedance-2.5 image-to-video) is processing.
Reserved 56 credits.
seedance-2.5 usually takes 1 min 30 s to 4 min once started.
Next: get_generation {"id":"gen_6f1c2a9e4b7d4c1e9a3f0b5d8e2c7a14","wait_seconds":40} until it is final.
```

## get\_generation

**id** `string` *required*

`gen_…`

**wait\_seconds** `integer` (default: 0)

Wait up to this many seconds (0 to 40) for the generation to finish.

A finished generation lists each output with its permanent URL and asset id, and what was charged and refunded.

## add\_asset

Exactly one source:

**url** `string`

A public https file, downloaded by Argil. The same URL twice is the same asset.

**upload** `object`

`{ "filename", "content_type", "size_bytes", "md5" }`: returns a signed URL to `PUT` the file to, valid 10 minutes, for files up to 2 GB. Then `get_asset` with `wait_seconds` until it is ready.

**file** `object`

`{ "data_base64", "filename", "content_type" }`: a file up to 2 MB, inline. For programs; never copy a file through a conversation.

## Results

Every tool answers with a short text for the conversation, ending with `Next:` and the call to make when there is one, and the same data as `structuredContent` for programs. A refused call has `isError: true` and an `error` with a stable `code`: see [Troubleshooting](https://docs.argil.ai/v2/mcp/troubleshooting.md#error-codes).

Tools keep their names and required arguments. New models, modes and optional arguments appear without breaking existing calls; a breaking change ships as a new tool, and the old one stays at least 12 months.


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