Aller au contenu principal
Référence MCP

Les outils

Une vingtaine d'actions. Ton assistant choisit la bonne tout seul : tu n'as jamais à prononcer ces noms.

Ils sont listés ici pour ceux qui veulent comprendre, et pour les assistants qui lisent cette page avant de se brancher.

Gratuits​

Ceux-ci ne coûtent aucun cauri, et ne comptent pas dans les limites. C'est voulu : on veut qu'un assistant vérifie avant d'agir.

models_list​

Les modèles disponibles, avec leur coût de départ.

Paramètre
typeimage, video ou audio. Facultatif.

À appeler avant toute génération. L'identifiant renvoyé doit être repris au caractère près : le nom affiché (« Seedance 2.0 ») n'est pas un identifiant.

Chaque modèle décrit aussi ce qu'il accepte, dans un champ accepte :

formatsles proportions possibles, 16:9, 2:3…
resolutions1K, 720p, 4k… selon le modèle
dureespour les vidéos, en secondes
referencess'il accepte des fichiers en entrée
max_images, max_videos, max_audioscombien de chacun
sons'il sait produire du son

Lis ce champ plutôt que de deviner. Un modèle qui refuse une référence vidéo ne le dira pas gentiment : il renverra une erreur au milieu de la génération.

account_balance​

Le solde en cauris et les vingt dernières opérations.

Paramètre
cursorle next_cursor d'un appel précédent, pour la page suivante

account_profile​

Le profil du compte : nom, avatar et statistiques d'utilisation. Pas le solde : pour les cauris, c'est account_balance. Sans paramètre.

generation_quote​

Le prix exact d'une génération, en cauris, sans rien lancer ni débiter. Le studio fait le même calcul qu'au lancement : durée, résolution, son, références, qualité, nombre.

Paramètre
typeimage, video ou audio. Obligatoire.
model_idvenu de models_list. Obligatoire.
promptle prompt prévu. Obligatoire.
les autresles mêmes que images_generate, video_generate ou audio_generate

Ton assistant annonce ce prix, attend ton accord, puis le passe en expected_cost au lancement : si le prix a changé entre-temps, rien n'est lancé ni débité, et le nouveau prix est renvoyé.

Les références doivent déjà être en ligne : le prix d'une vidéo de référence dépend de sa durée. Ne couvre ni la voix off (audio_tts) ni les effets sonores : leurs prix sont donnés plus bas.

voices_list​

Les voix disponibles pour audio_tts : tes voix personnelles d'abord, s'il y en a, puis les voix standard. Renvoie l'identifiant à passer en voice_id. Sans paramètre. À appeler quand tu demandes une voix précise.

mes_medias​

Les fichiers déjà téléversés sur le compte (via televerser_media ou depuis le site), avec leur adresse. Sert à réutiliser une référence sans la téléverser deux fois.

Paramètre
typefiltrer par image, video ou audio

Les créations passées, de la plus récente à la plus ancienne. Sert à retrouver une image déjà faite pour la réutiliser comme référence.

Paramètre
typefiltrer par image, video ou audio
projetseulement les créations de ce projet (id ou nom exact)
cursorla page suivante

projets_liste​

Les projets ouverts du compte, comme dans Mes Créations du studio : id, nom, nombre de créations et cauris dépensés. Un projet range des créations ensemble.

projet_creer​

Crée un projet (50 projets ouverts au plus) et renvoie son id.

Paramètre
nom24 caractères au plus. « Personnel » est réservé au projet par défaut. Obligatoire.
descriptionune phrase sur le projet, 200 caractères au plus

ranger_creation​

Range des créations déjà faites dans un projet, ou les sort de leur projet.

Paramètre
idsles créations à ranger, 50 au plus. Obligatoire.
projetid ou nom exact du projet. Chaîne vide : la création revient dans le projet par défaut, « Personnel ». Obligatoire.
Un nom inconnu ne lance rien

Avec le paramètre projet, une génération dont le projet n'existe pas n'est pas lancée et aucun cauri n'est dépensé : l'outil le dit, avec la liste des projets du compte.

creation_status​

Où en est une génération lancée : en attente, en cours, terminée ou échouée.

Paramètre
idl'identifiant renvoyé au lancement. Obligatoire.

Laisse au moins dix secondes entre deux vérifications. Interroger en boucle serrée ne rend rien plus rapide.

televerser_media​

Envoie un fichier (image, vidéo ou audio) encodé en base64, et renvoie son adresse publique, à utiliser ensuite comme référence dans une génération.

Paramètre
content_base64le contenu du fichier, en base64. Obligatoire.
file_nameavec son extension, par exemple photo.jpg. Obligatoire.
mime_typeseulement si l'extension ne suffit pas à deviner le type
Seulement si le fichier n'a pas déjà d'adresse

Le base64 pèse un tiers de plus que le fichier d'origine, et passe dans la conversation. Si le fichier est déjà en ligne ou vient de creations_search, envoie directement son adresse plutôt que de le retéléverser.

Limites : 10 Mo pour une image, 50 Mo pour un audio, 100 Mo pour une vidéo.

importer_media_url​

Télécharge une image, une vidéo ou un son depuis une adresse publique, côté serveur, et le range dans Mes médias. Renvoie l'adresse Pelikulart définitive, à utiliser comme référence. Rien ne passe par la conversation : c'est la bonne méthode dès que le fichier est déjà en ligne, ou quand son adresse est temporaire et risque d'expirer.

Paramètre
urladresse http(s) publique du fichier. Obligatoire.
file_namenom à donner au fichier dans Mes médias. Déduit de l'adresse sinon.

25 Mo au plus.

upload_show​

Ouvre dans la conversation une fenêtre où tu déposes toi-même tes fichiers (images, vidéos, sons) depuis ton appareil. Ils partent en pleine qualité dans Mes médias, sans passer par l'assistant. C'est le bon choix dès que le fichier est sur ton ordinateur ou ton téléphone, si ton assistant sait afficher les fenêtres d'application MCP.

Paramètre
typeauto (par défaut), image, video ou audio
multipleplusieurs fichiers à la fois. Oui par défaut.

upload_request et upload_finalize​

Pour un gros fichier (une vidéo surtout), quand l'assistant a un terminal. upload_request renvoie une adresse d'envoi signée (upload_url), valable 10 minutes. Le fichier y est envoyé directement en PUT, avec l'en-tête Content-Type renvoyé, sans passer par la conversation. upload_finalize l'enregistre ensuite et renvoie son adresse définitive.

Paramètre de upload_request
file_nameavec son extension, par exemple video.mp4. Obligatoire.
mime_typeseulement si l'extension ne suffit pas
Paramètre de upload_finalize
keyvenu de upload_request. Obligatoire.
idvenu de upload_request. Obligatoire.
file_namenom d'origine, pour l'affichage dans Mes médias
mime_typeseulement si le type envoyé diffère

Sans upload_finalize, le fichier reste invisible, même s'il est bien arrivé.

upload_start, upload_chunk et upload_complete​

Dernier recours, pour un petit fichier (1,5 Mo au plus) que l'assistant possède déjà en base64 et ne peut envoyer autrement. Il l'annonce avec upload_start, l'envoie par morceaux avec upload_chunk, puis upload_complete recolle le tout, vérifie la taille et renvoie l'adresse du fichier.

Paramètre
file_nameupload_start : nom avec extension. Obligatoire.
total_sizeupload_start : taille exacte du fichier en octets. Obligatoire.
mime_typeupload_start : seulement si l'extension ne suffit pas
upload_idupload_chunk et upload_complete : venu de upload_start. Obligatoire.
indexupload_chunk : position du morceau, à partir de 0. Obligatoire.
content_base64upload_chunk : ce morceau du base64, 20 000 à 30 000 caractères. Obligatoire.

Renvoyer un morceau avec le même index le remplace. S'il en manque un, upload_complete dit lequel.

Quel envoi choisir

Fichier déjà en ligne : importer_media_url. Fichier sur ton appareil : upload_show. Gros fichier et assistant avec terminal : upload_request. Petit fichier que l'assistant a déjà : televerser_media.

Qui coûtent des cauris​

images_generate​

Lance une image. Renvoie un identifiant : la génération est asynchrone, il faut ensuite interroger creation_status.

Paramètre
model_idvenu de models_list. Obligatoire.
promptla description. Obligatoire.
aspect_ratio1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3. Carré par défaut.
qualitysi le modèle en propose
countnombre d'images. Chacune est facturée.
image_urlsimages de référence
expected_costfacultatif : le prix annoncé par generation_quote. S'il a changé, rien n'est lancé ni débité.
projetfacultatif : le projet où ranger la création, par son id ou son nom exact (projets_liste)
Décris vraiment ce que tu veux

Un prompt de deux mots donne souvent un échec ou une image quelconque. Les modèles répondent beaucoup mieux à une phrase complète : le sujet, la lumière, le cadrage, l'ambiance.

video_generate​

Lance une vidéo. Compte plusieurs minutes.

Paramètre
model_idvenu de models_list. Obligatoire.
promptla description. Obligatoire.
durationen secondes. Obligatoire : le prix en dépend.
resolution720p, 1080p… Obligatoire : le prix en dépend.
audiogénérer le son. Change le prix sur certains modèles.
image_urlsimages de référence
audio_urlspistes sonores de référence, série Seedance 2 seulement
video_urlsvidéos de référence, série Seedance 2 seulement
expected_costfacultatif : le prix annoncé par generation_quote. S'il a changé, rien n'est lancé ni débité.
projetfacultatif : le projet où ranger la création, par son id ou son nom exact (projets_liste)

La durée et la résolution sont obligatoires parce que le prix se calcule dessus. Sans elles, une vidéo de quinze secondes serait facturée comme une de cinq.

Tous les modèles n'acceptent pas les mêmes références. models_list le dit pour chacun dans son champ accepte : demande-le avant d'envoyer un son à un modèle qui n'en veut pas.

audio_tts​

Transforme un texte en voix. Contrairement aux images et aux vidéos, le résultat arrive tout de suite.

Paramètre
text5 000 caractères maximum. Obligatoire.
voice_idune voix précise, venue de voices_list. Une voix par défaut sinon.
model_ideleven_v4 (par défaut), eleven_v4_turbo (rapide) ou eleven_v3
projetfacultatif : le projet où ranger la création, par son id ou son nom exact (projets_liste)

Prix : 9 cauris par tranche de 500 caractères (9 cauris jusqu'à 500, 18 jusqu'à 1 000, et ainsi de suite jusqu'à 90 cauris pour 5 000). Avec eleven_v4_turbo, 5 cauris par tranche (50 cauris pour 5 000).

audio_generate​

Musique et effets sonores. Le résultat arrive tout de suite, comme pour la voix.

Paramètre
model_idvenu de models_list. Obligatoire.
promptce qu'on veut entendre. Obligatoire.
projetfacultatif : le projet où ranger la création, par son id ou son nom exact (projets_liste)

Une chanson, une nappe d'ambiance, un bruit de porte : c'est le modèle choisi qui décide de quoi il est capable. Les prix diffèrent nettement entre un effet court et un morceau complet, models_list les donne.

Suppression​

Ces deux-là ne coûtent aucun cauri, mais sont irréversibles. Un bon assistant demande confirmation avant de les appeler.

supprimer_media​

Supprime un fichier téléversé. Pas une génération : voir supprimer_generation pour ça.

Paramètre
idl'identifiant du média, venu de mes_medias. Obligatoire.

supprimer_generation​

Supprime une génération, image, vidéo ou audio créée sur Pelikulart. Pas un fichier téléversé, voir supprimer_media pour ça. Ne rembourse aucun cauri : la génération a déjà consommé ce qu'elle devait consommer.

Paramètre
idl'identifiant de la génération, venu de creations_search ou creation_status. Obligatoire.

Comment se passe une génération​

  1. Ton assistant appelle models_list pour connaître les identifiants, et generation_quote pour le prix exact
  2. Il lance images_generate ou video_generate et reçoit un identifiant
  3. Les cauris sont débités au lancement
  4. Il interroge creation_status de temps en temps
  5. Quand c'est prêt, l'adresse de l'image ou de la vidéo est renvoyée

Si la génération échoue, les cauris sont remboursés automatiquement. Tu n'as rien à demander.