API

L'API de Media Empire

Lire vos projets et vos statistiques, créer des visuels, rendre des images et des GIF, ranger vos médias de marque, préparer et publier des posts, lancer des vidéos (avec votre voix de marque, après relecture) et du motion design — depuis un programme.

Media Empire est une installation commune : l'adresse de l'API est la même pour tous, https://media.successarchitect.fr/api. Chaque clé n'agit que sur votre compte, et sur lui seul.

Démarrer#

Dans Media Empire : Réglages → API. Écrivez à quoi sert la clé, cochez ses droits, choisissez son expiration et son débit, puis Créer une clé.
Copiez la clé (yft_…) : elle n'est montrée qu'une fois.
Appelez l'API avec l'en-tête Authorization: Bearer yft_….

Les droits#

Droit	Nom technique	Ce qu'il permet
Lecture	`read`	Lire les projets, modèles, médias, la bibliothèque, les posts, les statistiques, les crédits. Toujours compris.
Création	`create`	Créer et modifier dans le compte, sans effet dehors ni dépense : projets, rendus (dont l'export GIF), imports de photos, profil de marque, bibliothèque.
Publication	`publish`	Ce qui sort du compte : publier ou programmer sur les réseaux, modifier ou retirer un post, partager un projet par lien.
Dépense	`spend`	Ce qui coûte : vidéos, motion design, portraits, images générées pour un cadre, musiques, sous-titres, détourage, étiquettes proposées par l'IA, recherche par le sens dans les Connaissances, messages à l'agent IA. Les crédits et budgets du compte s'appliquent.

Par défaut, une nouvelle clé a la lecture et la création. Publication et Dépense sont décochées ; accorder la publication demande de lire et d'accepter un avertissement (la date, votre adresse IP et le texte accepté sont gardés).

Une clé ne peut jamais : créer une autre clé, changer un mot de passe ou une clé Buffer, IA ou vidéo, acheter des crédits, activer une automatisation, ni entrer dans l'administration. Une route qui modifie quelque chose et n'est pas ouverte aux clés répond 403 session_required.

L'agent IA piloté par une clé n'a que les outils des droits de cette clé (depuis 0.94.0) : avec une clé « Dépense » sans « Création », il ne modifie ni le profil de marque ni les projets ; un outil hors droits ne tourne pas, l'agent reçoit insufficient_scope et le droit qui manque. Un message envoyé par une clé est marqué dans la conversation et n'est jamais pris pour votre accord. Sans « Dépense », la recherche dans vos Connaissances se fait par les mots, sans dépense.

Les clés créées avant la version 0.85.0 gardent tous les droits qu'elles avaient ; l'écran les signale « ancienne clé » : remplacez-les par une clé limitée.

Les routes principales#

Adresse de base : https://media.successarchitect.fr/api. Corps et réponses en JSON, sauf mention.

Groupe	Routes	Droit
Projets	`GET` `/v1/projects` · `GET` `/v1/projects/:id`	`read`
	`POST` `/v1/projects` · `PUT` `/v1/projects/:id` · `DELETE` `/v1/projects/:id`	`create` (`publish` si le projet est partagé par lien)
	`POST` `/v1/projects/:id/share`	`publish`
Rendu	`POST` `/v1/render` (images d'un gabarit ou d'un projet) · `POST` `/v1/projects/:id/export-video` (MP4) · `POST` `/v1/projects/:id/export-gif` (GIF animé, sans dépense)	`create`
	`GET` `/v1/exports/:id` (suivre un export MP4, GIF ou motion design)	`read`
Motion design	`GET` `/v1/motion` (styles, préréglages, rôles, transitions, bornes et prix du rendu) · `POST` `/v1/motion/estimate` (le devis, sans rien créer ni dépenser)	`read`
	`POST` `/v1/projects/:id/animate` (une copie animée du projet, rendue sur nos serveurs ; rien n'est publié)	`spend`
Modèles et médias	`GET` `/v1/templates` · `GET` `/v1/templates/:id` · `GET` `/v1/media/search` · `GET` `/v1/assets/:id`	`read`
	`POST` `/v1/media/import`	`create`
Publication (Buffer)	`GET` `/v1/buffer/channels` · `GET` `/v1/buffer/posts` · `GET` `/v1/buffer/analytics`	`read`
	`POST` `/v1/buffer/publish` · `POST` `/v1/buffer/posts` · `PATCH` `/v1/buffer/posts/:id` · `DELETE` `/v1/buffer/posts/:id`	`publish`
Vidéos	`GET` `/v1/video` · `GET` `/v1/video/jobs/:id` · `GET` `/v1/video/prices` (les prix annoncés, en dollars, avec les réglages du moment) · `POST` `/v1/video/estimate` (le devis d'une vidéo, sans rien lancer)	`read`
	`POST` `/v1/videos` · `POST` `/v1/library/avatar` · `POST` `/v1/library/audio-ai` · `POST` `/v1/library/captions` · `POST` `/v1/images/remove-background`	`spend`
	`POST` `/v1/videos/:id/publish`	`publish`
	`DELETE` `/v1/videos/:id`	`create`
Voix de marque	`GET` `/v1/voices` (vos voix : nom, à qui est la voix, langue, durée de l'enregistrement ; jamais l'enregistrement ni l'empreinte ; avec la case d'accord, les bornes et les prix du moment) · `POST` `/v1/voices/estimate` (le coût de la création d'une voix pour `seconds` secondes d'enregistrement, sans rien créer)	`read`
Médiathèque et bibliothèque	`GET` `/v1/library` (`kind` : avatar, demo, clip, audio, image ; avec le rôle et les étiquettes) · `GET` `/v1/library/tags`	`read`
	`POST` `/v1/library/upload` (corps brut ; une image de marque avec `kind=image`, `role`, `tags`) · `PATCH` `/v1/library/:id` (nom, rôle, étiquettes)	`create`
	`POST` `/v1/library/:id/suggest-tags` (gratuit sans corps ; `{"ai": true}` fait regarder l'image par l'IA, un appel payé ; rien n'est appliqué)	`spend`
Cadres	`GET` `/v1/frames/candidates` (les autres choix pour un cadre, sans rien dépenser, et le prix d'une image générée)	`read`
	`POST` `/v1/frames/generate` (une image générée pour un cadre ; rend un suivi)	`spend`
Automatisations	`GET` `/v1/automations` · `GET` `/v1/automations/:id` · `GET` `/v1/automations/autopilot-warning`	`read`
	`POST` `/v1/automations/:id/pause`	`create`
	`POST` `/v1/automations/:id/test` (un post d'essai, qui attend toujours votre validation)	`spend`
Connaissances	`GET` `/v1/knowledge` (bases, lecteurs, documents : noms, tailles, extraits ; jamais le texte des documents)	`read`
Agent IA	`POST` `/v1/agent/conversations/:id/messages` (réponse en flux)	`spend`
Compte	`GET` `/v1/credits` · `GET` `/v1/me/export` (toutes vos données, en JSON)	`read`
IA	`GET` `/v1/mcp/settings` · `GET` `/v1/mcp/calls` (« Ce que votre IA a fait »)	`read`
Clés	`DELETE` `/v1/keys/:id` (une clé se révoque elle-même)	`read`

Seuls les médias de votre compte et ceux du catalogue sont servis au rendu et à l'export : un média d'un autre compte est refusé.

Réservé à l'application (votre session, jamais une clé ; une clé reçoit 403 session_required) : créer, modifier, activer ou supprimer une automatisation (en pilote automatique, une automatisation publie sans clic) ; confirmer une proposition de l'agent IA ; créer une base de Connaissances, y déposer ou supprimer un document, essayer une recherche ; créer ou supprimer une voix de marque, et relire le texte qu'elle dira (la case d'accord et la relecture sont cochées par une personne). Votre IA cherche dans vos Connaissances avec l'outil MCP media_search_knowledge, seulement dans les bases que vous lui avez ouvertes.

Vidéos : le mode avancé#

Une vidéo peut choisir un préréglage (preset : economy, balanced, premium, ou custom avec models), sa durée (seconds : 8 à 30 s pour une vidéo face caméra, 10 à 30 s pour des scènes), sa définition (resolution : 480p ou 720p), les sous-titres, la musique et la voix off (captions, music, voiceOver) et, en option, le modèle de chaque étape (models), dans une liste fermée de modèles hébergés chez fal (filtre de sécurité toujours forcé). Le format scenes fait une vidéo sans personne qui parle : 2 à 6 plans de 5 s avec une voix off. Sans aucun de ces choix, une vidéo face caméra suit les réglages de l'administrateur (le mode simple) ; des scènes prennent le préréglage balanced.

POST /v1/video/estimate rend le devis (dollars, crédits, détail par étape, plafond) sans rien lancer.
POST /v1/videos refuse avant toute dépense un modèle ou un paramètre hors liste (400, par exemple invalid_model, invalid_step, resolution_not_supported), des crédits insuffisants (402 credits_insufficient) ou un coût au-dessus du plafond par vidéo réglé par l'administrateur (409 video_cost_cap, avec cost et cap en dollars ; 15 $ par défaut).
Le devis et le lancement vérifient chez fal chaque modèle de la chaîne (depuis 0.94.1) : un modèle retiré par fal, hors de son accord ou dont les filtres de sécurité ne peuvent pas être vérifiés est refusé tout de suite, avant toute dépense (409 fal_model_retired, 409 fal_model_unverifiable, ou fal_model_not_allowed, avec model et step).
L'avatar parlant d'une vidéo face caméra est LongCat (480p en Économique et Équilibré, 720p en Premium). Ordres de prix d'une vidéo face caméra de 15 s : Économique ≈ 2,38 $, Équilibré ≈ 2,39 $, Premium ≈ 9,52 $ ; de 30 s : ≈ 4,75 $, 4,77 $ et 19,02 $ — la Premium de 30 s dépasse le plafond par défaut de 15 $. Le devis donne toujours le prix exact du moment.
Le coût annoncé par l'écran, le devis, l'agent IA et le MCP vient de la même source. Par le MCP, media_create_video accepte un préréglage (preset : economy, balanced, premium), seconds, music, voice_over, captions, et le format scenes (avec scenes, une description en anglais par plan, et voiceover) ; le choix d'un modèle par étape reste à l'API et à l'écran.

Voix de marque#

Une voix de marque est votre voix, ou celle d'une personne qui vous a donné son accord écrit, reproduite par l'IA pour lire le script d'une vidéo face caméra (ugc) ou la voix off de scènes (scenes). Elle se crée dans l'application (Vidéos → Bibliothèque → Voix de marque), à partir d'un enregistrement de 10 secondes à 5 minutes, avec une case d'accord obligatoire ; l'acceptation est gardée (date, adresse IP, compte, texte exact). Une clé ne crée ni ne supprime une voix.

GET /v1/voices liste vos voix (leur identifiant, à donner en voiceId), la case d'accord en vigueur, les bornes de l'enregistrement et les prix du moment (prices), calculés par le serveur. POST /v1/voices/estimate (seconds) rend le coût de la création d'une voix, sans rien créer.
Relecture humaine, toujours : avec une clé, POST /v1/videos avec voiceId ne lance rien et ne dépense rien, quel que soit le réglage des dépenses. Il rend une demande (202, "status": "awaiting_client_review", avec le texte exact qui sera lu) : vous relisez ce texte dans Media Empire (Réglages → API, demandes de votre IA), cochez « J'ai relu ce texte » et confirmez. Donnez le texte vous-même (written : script, ou voiceover et scenes).
Le texte passe une barrière côté serveur : contenu sexuel, appel à la haine, ou voix qui se fait passer pour une autorité ou une personnalité sont refusés (422 voice_text_refused, avec reason : sexual, hate, impersonation). Le filtre de sécurité du modèle reste toujours actif.
La voix lit à la place de la voix standard (en Premium, à la place de Gemini TTS) ; son coût s'ajoute au devis de la vidéo et passe par les mêmes contrôles (crédits, plafond par vidéo). Une voix beaucoup plus longue que la vidéo prévue est refusée avant l'avatar (voice_too_long_for_video).
La vidéo porte la marque IA dans le fichier et, à la publication, la mention « Vidéo générée par IA · Voix générée par IA ». Aucun paramètre ne les retire.
Effacement : supprimer la voix (dans l'application) efface l'enregistrement et l'empreinte de la voix ; elle part aussi avec le compte. L'export du compte contient l'enregistrement de chaque voix (téléchargeable depuis l'application seulement, pas avec une clé) ; l'empreinte de la voix ne sort jamais.

Par le MCP : media_create_video accepte voice_id ; votre IA obtient la même demande, que vous relisez et confirmez. Les voix du compte sont dans le résultat de media_list_video_library.

Motion design et GIF#

Un projet devient une courte vidéo animée : vous (ou votre IA) choisissez un style et, si besoin, un préréglage par rôle ; Media Empire les pose sur une copie du projet, avec le moteur « Animer » de l'éditeur, et la rend sur ses serveurs. Aucun mouvement n'est dessiné par l'IA, aucun modèle d'IA payant n'est appelé ; votre design et vos textes restent tels quels. Rien n'est publié : pour publier la vidéo, créez ensuite un post.

Style (style) : calm (Sobre : fondus doux), dynamic (Dynamique : glissements, zooms, pops), cinematic (Cinéma : zoom lent sur les images, titre mot à mot, fondus enchaînés) ou kinetic (Typo animée : textes mot à mot, logo qui pulse).
Un préréglage par rôle (presets, par exemple {"logo":"pulse"}) : rôles background, image, video, shape, title, text, logo ; préréglages soft, words (un texte seulement), pulse, slide, rise, zoom, pop, kenBurns, ou none. Les rôles sont trouvés sans IA, d'après la taille et la place des éléments.
Aussi : secondsPerPage (2 à 15), transition (fade, dissolve, slideleft, wipeleft, circleopen, zoomin… ou none), musicId (un son de votre bibliothèque), output (mp4 par défaut, ou gif).
Le prix du rendu est calculé par le serveur, à la seconde de vidéo produite : les prix du moment sont dans GET /v1/motion (prices), et POST /v1/motion/estimate rend le devis d'un projet (dollars, crédits, durée, éléments animés) sans rien créer ni dépenser. Le rendu est refusé avant de partir si vos crédits ne le couvrent pas (402 credits_insufficient).
POST /v1/projects/:id/animate (droit spend) répond 202 : le suivi du rendu (job, avec animatedProjectId, le nouveau projet) et le devis (estimate). Suivez-le avec GET /v1/exports/:id.
POST /v1/projects/:id/export-gif (droit create, sans dépense) exporte le projet tel qu'il est : ses 10 premières secondes, en boucle, width 320, 480 ou 640 (480 par défaut), fps 10, 12 ou 15 (12 par défaut), 8 Mo au plus. Le GIF fini est dans gif, au suivi GET /v1/exports/:id.
Bornes, toujours : 10 pages, 60 secondes en tout, 40 éléments animés par page, un rendu à la fois par compte (409 export_running), une file d'attente bornée pour tout le serveur (503 render_queue_full). Au-delà : 413 (too_many_pages, motion_too_long, gif_too_large…). Une valeur hors des listes est refusée (400, par exemple invalid_motion_style, invalid_motion_preset, invalid_gif_width).
La marque IA et la mention « … générée par IA » s'appliquent comme pour une vidéo quand le projet contient un média généré par l'IA.

Par le MCP : media_animate_project (une dépense : le plafond du jour ou le clic humain de vos réglages s'appliquent) et media_export_gif (une création, sans dépense). Voir la liste des outils.

Les cadres et la médiathèque de marque#

Dans un modèle, chaque cadre d'image a un rôle (logo, product, person, background, illustration, screenshot, ou libre), une consigne et une source : vos médias, la banque d'images, une image générée, ou l'image du modèle. Les images de votre médiathèque portent le même rôle et vos étiquettes : c'est ainsi que le bon logo ou la bonne photo produit va dans le bon cadre.

GET /v1/frames/candidates donne les autres choix pour un cadre (role, source, hint, tag, w, h, kind) : vos médias qui correspondent, des photos de banque d'images, et le prix d'une image générée, calculé par le serveur, avec le refus déjà connu (crédits, clé, rôle). Rien n'est dépensé.
POST /v1/frames/generate (role, hint, width, height) génère l'image, à la forme du cadre : refus avant toute dépense si vos crédits ne la couvrent pas (402 credits_insufficient) ou si le rôle est un logo, une photo produit ou une capture d'écran (400 generation_not_allowed_for_role) ; filtre de sécurité forcé, marque IA sur le fichier. La réponse (202) rend un suivi, à lire avec GET /v1/video/jobs/:id.

Exemples#

Terminal

export MEDIA_CLE="yft_..."   # votre clé, jamais dans un fichier partagé

Lister vos projets :

Terminal

curl -s https://media.successarchitect.fr/api/v1/projects \
  -H "Authorization: Bearer $MEDIA_CLE"

Rendre un projet avec d'autres valeurs pour ses variables (droit create) :

Terminal

curl -s -X POST https://media.successarchitect.fr/api/v1/render \
  -H "Authorization: Bearer $MEDIA_CLE" -H "Content-Type: application/json" \
  -d '{"projectId":"<identifiant du projet>","values":{"Nom":"Ada"},"format":"png"}'

Voir les choix pour un cadre « photo d'équipe », et le prix d'une image générée, sans rien dépenser (droit read) :

Terminal

curl -s "https://media.successarchitect.fr/api/v1/frames/candidates?role=person&hint=equipe&w=1080&h=1350" \
  -H "Authorization: Bearer $MEDIA_CLE"

Animer un projet en motion design (droit spend ; la réponse rend un suivi, à lire avec GET /v1/exports/:id) :

Terminal

curl -s -X POST "https://media.successarchitect.fr/api/v1/projects/<identifiant du projet>/animate" \
  -H "Authorization: Bearer $MEDIA_CLE" -H "Content-Type: application/json" \
  -d '{"style":"kinetic","presets":{"logo":"pulse"},"secondsPerPage":4}'

Lister vos voix de marque, puis proposer une vidéo lue par l'une d'elles (droits read puis spend ; rien n'est lu ni dépensé avant votre relecture dans Media Empire) :

Terminal

curl -s https://media.successarchitect.fr/api/v1/voices \
  -H "Authorization: Bearer $MEDIA_CLE"

curl -s -X POST https://media.successarchitect.fr/api/v1/videos \
  -H "Authorization: Bearer $MEDIA_CLE" -H "Content-Type: application/json" \
  -d '{"format":"ugc","preset":"premium","seconds":15,"voiceId":"<identifiant de la voix>","written":{"title":"Le pain","hook":"Le pain du matin","script":"Notre pain est cuit chaque matin."}}'
# → 202 {"proposal":{"status":"awaiting_client_review","text_to_be_read":"…"}}

Exporter un projet en GIF, sans dépense (droit create) :

Terminal

curl -s -X POST "https://media.successarchitect.fr/api/v1/projects/<identifiant du projet>/export-gif" \
  -H "Authorization: Bearer $MEDIA_CLE" -H "Content-Type: application/json" \
  -d '{"width":480,"fps":12}'

Lancer une vidéo « meme » (droit spend ; la réponse rend un suivi, à lire avec GET /v1/video/jobs/:id) :

Terminal

curl -s -X POST https://media.successarchitect.fr/api/v1/videos \
  -H "Authorization: Bearer $MEDIA_CLE" -H "Content-Type: application/json" \
  -d '{"format":"meme","context":"La rentrée des commerçants"}'

Limites et erreurs propres à Media Empire#

Débit : 60 appels par minute par défaut (de 10 à 600, choisi à la création). Au-delà : 429 rate_limited et Retry-After.
Expiration : 7, 30, 90 ou 365 jours, ou jamais. Une clé expirée répond 401 api_key_expired.
Journal : chaque action (date, méthode, chemin, résultat, adresse IP), et les lectures jusqu'à 20 000 par jour et par clé, sont gardées 90 jours ; une action dont la connexion a été coupée avant la fin est notée 499. Bouton « Journal » de chaque clé.
Plafonds du jour : ceux de « Votre IA dans Media Empire » valent pour le serveur MCP ; l'API à clés est limitée par ses droits, son débit, les crédits et budgets du compte et le plafond par vidéo.
Crédits : les vidéos et autres générations consomment les crédits du compte. Une génération est refusée avant de partir si vos crédits ne couvrent pas son coût estimé.

Statut	Code	Sens
401	`auth_required`	Pas de clé, clé inconnue ou révoquée
401	`api_key_expired`	La clé est arrivée à expiration
403	`insufficient_scope`	La clé n'a pas le droit demandé (`required`) ; l'en-tête `WWW-Authenticate` le redit
403	`session_required`	Réservé à l'application
403	`api_access_stopped`	« Tout arrêter » a été actionné sur ce compte
402	`credits_exhausted`	Le compte n'a plus de crédits
402	`credits_insufficient`	Vos crédits ne couvrent pas le coût estimé de la génération : rien n'est lancé ni débité ; la réponse donne `cost` (coût estimé) et `available` (solde), en crédits
409	`video_cost_cap`	Le coût estimé de la vidéo dépasse le plafond par vidéo réglé par l'administrateur : rien n'est lancé ; la réponse donne `cost` et `cap`, en dollars
409	`fal_model_retired` · `fal_model_unverifiable`	Un modèle de la chaîne a été retiré par fal, ou ses filtres de sécurité ne peuvent pas être vérifiés : rien n'est lancé ni payé ; la réponse nomme `model` et `step`
409	`export_running`	Un rendu (export MP4, GIF ou motion design) est déjà en cours pour ce compte : attendez qu'il finisse
413	`gif_too_large`	Le GIF dépasserait 8 Mo : choisissez une largeur ou une fluidité plus petite
503	`render_queue_full`	La file des rendus du serveur est pleine : réessayez dans un instant
400	`generation_not_allowed_for_role`	Un logo, une photo produit ou une capture d'écran ne se génèrent jamais : ils viennent de votre médiathèque
422	`content_refused`	Le filtre de sécurité du modèle a refusé ce qu'il a produit : rien n'est gardé (le coût de la génération reste compté)
422	`voice_text_refused`	Ce texte ne sera pas lu par une voix de marque (`reason` : `sexual`, `hate`, `impersonation`) : rien n'est créé
404	`voice_not_found`	Cette voix de marque n'existe pas dans votre compte
409	`voice_not_ready`	La voix de marque est encore en création : réessayez dans un instant
403	`account_inactive`	Compte désactivé ou en attente
429	`rate_limited`	Débit dépassé : attendez `Retry-After` secondes

La marque IA, aussi par l'API#

Ce que vous publiez avec une clé et qui contient une image, une vidéo ou une voix générée par l'IA de Media Empire reçoit la mention visible « … générée par IA » et garde sa marque lisible par machine. Aucun paramètre ne les retire.

Coller un design (depuis Media Empire 0.93.0)#

POST /v1/library/paste : les octets d'une image (corps brut, JPEG, PNG ou WebP ; 10 Mo et 40 mégapixels au plus). Une image que vous aviez déjà collée est reprise, pas rangée deux fois (200, "reused": true) ; sinon 201.
POST /v1/library/paste-url ({"url": "https://…"}) : l'adresse d'une image citée par le contenu collé. Le serveur la télécharge sous garde : HTTPS seulement, aucune adresse interne (réseau privé, boucle locale, métadonnées d'hébergeur), redirections revérifiées, 15 secondes au plus. Une adresse refusée répond 400 paste_url_refused, sans qu'aucune requête ne parte.
Erreurs : 415 paste_not_image, 413 paste_too_large ou paste_image_too_big, 409 library_full (300 images), 429 paste_rate_limited (60 images en 5 minutes).

Le texte, le HTML et les données de Canva collés sont lus dans votre navigateur et ne le quittent pas ; rien n'est demandé à Canva. Voir Coller un design depuis Canva.

Le serveur MCP de Media Empire#

https://media.successarchitect.fr/mcp, avec 29 outils et une clé de votre compte. Voir le MCP direct et la liste des outils.