The tools
About twenty actions. Your assistant picks the right one on its own: you never have to say these names out loud.
They're listed here for people who want to understand, and for the assistants that read this page before connecting.
Free
These cost no cauris, and don't count towards the limits. That's deliberate: we want an assistant to check before it acts.
models_list
The available models, with their starting cost.
| Parameter | |
|---|---|
type | image, video or audio. Optional. |
Call this before any generation. The identifier it returns must be used character for character: the display name ("Seedance 2.0") is not an identifier.
account_balance
Your balance in cauris and the last twenty transactions. No parameters.
account_profile
The account profile: name, avatar and usage statistics. Not the balance: for
cauris, use account_balance. No parameters.
generation_quote
The exact price of a generation, in cauris, without launching or charging anything. The studio runs the same calculation as at launch: duration, resolution, sound, references, quality, count.
| Parameter | |
|---|---|
type | image, video or audio. Required. |
model_id | from models_list. Required. |
prompt | the planned prompt. Required. |
| the others | the same as images_generate, video_generate or audio_generate |
Your assistant states this price, waits for your go-ahead, then passes it as
expected_cost at launch: if the price changed in the meantime, nothing is
launched or charged, and the new price is returned.
References must already be online: the price of a reference video depends on
its duration. It covers neither voice-over (audio_tts) nor sound effects:
their prices are given further down.
voices_list
The voices available for audio_tts: your own voices first, if you have any,
then the standard voices. Returns the identifier to pass as voice_id. No
parameters. Call it when you ask for a specific voice.
mes_medias
The files already uploaded to the account (through televerser_media or from
the website), with their address. Lets you reuse a reference without
uploading it twice.
| Parameter | |
|---|---|
type | filter by image, video or audio |
televerser_media
Uploads a file (image, video or audio) encoded in base64, and returns its public address, to use afterwards as a reference in a generation.
| Parameter | |
|---|---|
content_base64 | the file content, in base64. Required. |
file_name | with its extension, for example photo.jpg. Required. |
mime_type | only if the extension isn't enough to guess the type |
Base64 is a third heavier than the original file and goes through the
conversation. If the file is already online, prefer importer_media_url.
Limits: 10 MB for an image, 50 MB for audio, 100 MB for a video.
importer_media_url
Downloads an image, a video or a sound from a public address, on the server side, and stores it in My media. Returns the final Pelikulart address, to use as a reference. Nothing goes through the conversation: this is the right method whenever the file is already online, or when its address is temporary and may expire.
| Parameter | |
|---|---|
url | public http(s) address of the file. Required. |
file_name | name to give the file in My media. Taken from the address otherwise. |
25 MB at most.
creations_search
Past creations, newest first. Useful for finding an image you already made so you can reuse it as a reference.
| Parameter | |
|---|---|
type | filter by image, video or audio |
projet | only this project's creations (id or exact name) |
cursor | the next page |
projets_liste
The account's open projects, as in My Creations in the studio: id, name, number of creations and cauris spent. A project groups creations together.
projet_creer
Creates a project (50 open projects at most) and returns its id.
| Parameter | |
|---|---|
nom | 24 characters at most. “Personnel” is reserved for the default project. Required. |
description | one sentence about the project, 200 characters at most |
ranger_creation
Files existing creations in a project, or takes them out of their project.
| Parameter | |
|---|---|
ids | the creations to file, 50 at most. Required. |
projet | project id or exact name. Empty string: back to the default project, “Personnel”. Required. |
With the projet parameter, a generation whose project doesn't exist isn't
launched and no cauris are spent: the tool says so and lists the account's
projects.
creation_status
Where a generation stands: queued, running, finished or failed.
| Parameter | |
|---|---|
id | the identifier returned when it started. Required. |
Leave at least ten seconds between two checks. Polling in a tight loop makes nothing faster.
upload_show
Opens a window in the conversation where you drop your own files (images, videos, sounds) from your device. They go to My media in full quality, without passing through the assistant. This is the right choice whenever the file is on your computer or phone, if your assistant can display MCP app windows.
| Parameter | |
|---|---|
type | auto (default), image, video or audio |
multiple | several files at once. Yes by default. |
upload_request and upload_finalize
For a large file (mostly video), when the assistant has a terminal.
upload_request returns a signed upload address (upload_url), valid for
10 minutes. The file is sent straight to it with PUT, using the returned
Content-Type header, without going through the conversation.
upload_finalize then registers it and returns its permanent address.
upload_request parameter | |
|---|---|
file_name | with its extension, for example video.mp4. Required. |
mime_type | only if the extension is not enough |
upload_finalize parameter | |
|---|---|
key | from upload_request. Required. |
id | from upload_request. Required. |
file_name | original name, shown in My media |
mime_type | only if the type sent differs |
Without upload_finalize, the file stays invisible even though it arrived.
upload_start, upload_chunk and upload_complete
Last resort, for a small file (1.5 MB at most) the assistant already holds in
base64 and cannot send any other way. It announces the file with
upload_start, sends it in pieces with upload_chunk, then
upload_complete joins them, checks the size and returns the file address.
| Parameter | |
|---|---|
file_name | upload_start: name with extension. Required. |
total_size | upload_start: exact file size in bytes. Required. |
mime_type | upload_start: only if the extension is not enough |
upload_id | upload_chunk and upload_complete: from upload_start. Required. |
index | upload_chunk: position of the piece, starting at 0. Required. |
content_base64 | upload_chunk: this piece of the base64, 20,000 to 30,000 characters. Required. |
Sending a piece again with the same index replaces it. If one is missing,
upload_complete says which.
File already online: importer_media_url. File on your device:
upload_show. Large file and an assistant with a terminal: upload_request.
Small file the assistant already has: televerser_media.
The ones that cost cauris
images_generate
Starts an image. Returns an identifier: generation is asynchronous, so you
then have to poll creation_status.
| Parameter | |
|---|---|
model_id | from models_list. Required. |
prompt | the description. Required. |
aspect_ratio | 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3. Square by default. |
quality | if the model offers it |
count | number of images. Each one is charged. |
image_urls | reference images |
projet | optional: the project to file the creation in, by id or exact name (projets_liste) |
A two-word prompt often gives you a failure or a forgettable image. Models respond far better to a full sentence: the subject, the light, the framing, the mood.
video_generate
Starts a video. Expect several minutes.
| Parameter | |
|---|---|
model_id | from models_list. Required. |
prompt | the description. Required. |
duration | in seconds. Required: the price depends on it. |
resolution | 720p, 1080p… Required: the price depends on it. |
audio | generate sound. Changes the price on some models. |
image_urls | reference images |
projet | optional: the project to file the creation in, by id or exact name (projets_liste) |
Duration and resolution are required because the price is worked out from them. Without them, a fifteen-second video would be charged like a five-second one.
audio_tts
Turns text into voice. Unlike images and videos, the result comes back immediately.
| Parameter | |
|---|---|
text | 5,000 characters maximum. Required. |
voice_id | a specific voice, from voices_list. A default voice otherwise. |
model_id | eleven_v4 (default), eleven_v4_turbo (fast) or eleven_v3 |
projet | optional: the project to file the creation in, by id or exact name (projets_liste) |
Price: 9 cauris per 500 characters (9 cauris up to 500, 18 up to 1,000, and
so on up to 90 cauris for 5,000). With eleven_v4_turbo, 5 cauris per 500
characters (50 cauris for 5,000).
audio_generate
Music and sound effects. The model chosen decides what it can do; a short
effect and a full song are priced very differently, and models_list gives
the prices.
| Parameter | |
|---|---|
model_id | from models_list. Required. |
prompt | what you want to hear. Required. |
projet | optional: the project to file the creation in, by id or exact name (projets_liste) |
Deletion
These two cost no cauris, but they are irreversible. A good assistant asks for confirmation before calling them.
supprimer_media
Deletes an uploaded file. Not a generation: see supprimer_generation for
that.
| Parameter | |
|---|---|
id | the media identifier, from mes_medias. Required. |
supprimer_generation
Deletes a generation (image, video or audio created on Pelikulart). Not an
uploaded file: see supprimer_media for that. No cauris are refunded: the
generation has already used what it had to use.
| Parameter | |
|---|---|
id | the generation identifier, from creations_search or creation_status. Required. |
How a generation goes
- Your assistant calls
models_listto learn the identifiers - It starts
images_generateorvideo_generateand gets an identifier back - Cauris are charged at the start
- It polls
creation_statusfrom time to time - When it's ready, the address of the image or video is returned
If a generation fails, the cauris are refunded automatically. You don't have to ask.