Tools

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`	Start a generation. Spends credits	`model`, `mode`, `input`, `max_credits`, `idempotency_key`
`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 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.

string

required

Model id, for example seedance-2.5.

string

required

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

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.

number

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

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.

integer

default:"40"

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

object

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

boolean

default:"true"

Include small image previews in the result.

{
  "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"
}

{
  "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"
}

{
  "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:

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

string

required

gen_…

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:

string

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

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.

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

Get started

Guides

Reference

generate_media

get_generation

add_asset

Results

​generate_media

​get_generation

​add_asset

​Results

generate_media

get_generation

add_asset

Results