Documentation · API v1 et serveur MCP

L'API et le serveur MCP de Media Empire

Faites travailler Media Empire par un programme (n8n, Make, un script) ou par votre assistant d'IA (Claude, ChatGPT, Cursor) : lire vos projets et vos statistiques, créer des designs, préparer et publier des posts, lancer des vidéos. Chaque accès agit au nom de VOTRE compte, et de lui seul.

• Qui répond de quoi
• Les clés d'API
• Les droits
• L'agent IA piloté par une clé
• Les erreurs
• Les routes
• Vidéos : le mode avancé
• Voix de marque
• Motion design et GIF
• Exemples
• Le serveur MCP
• Les outils MCP
• Ce que votre IA peut faire seule
• Par votre espace client
• Les versions

Qui répond de quoi

Qui répond de quoi. Vous choisissez l'outil d'IA ou d'automatisation que vous reliez à Media Empire (Claude, ChatGPT, Cursor, n8n…) : ce qu'il lit lui est remis à votre demande et part chez son fournisseur selon vos propres conditions avec lui (conservation, entraînement, pays de traitement), et ce qu'il fait dans Media Empire est fait au nom de votre société, qui en répond. De notre côté, nous restons responsables de la sécurité de nos accès et appliquons à votre outil les droits que vous lui donnez et les mêmes contrôles qu'à l'écran, avec un journal de chaque action.

Who is responsible for what. You choose the AI or automation tool you connect to Media Empire (Claude, ChatGPT, Cursor, n8n…): what it reads is handed to it at your request and goes to its provider under your own terms with that provider (retention, training, where it is processed), and what it does in Media Empire is done on behalf of your company, which is responsible for it. On our side, we remain responsible for the security of our access points, and we apply to your tool the permissions you give it and the same controls as on screen, with a log of every action.

谁对什么负责。 您选择连接到 Media Empire 的 AI 或自动化工具（Claude、ChatGPT、Cursor、n8n…）：它读取的内容是应您的要求交给它的，并按照您与其提供商之间的条款（保存期限、模型训练、处理地点）发送给该提供商；它在 Media Empire 中所做的一切均以贵公司的名义进行，由贵公司负责。我们这一方仍对我们接入点的安全负责，并对您的工具执行您授予它的权限以及与界面上相同的检查，每一项操作都有记录。

Les clés d'API

Créez une clé dans Media Empire : Réglages → API. Son secret (yft_…) n'est montré qu'une fois ; le serveur n'en garde qu'une empreinte. Envoyez-le dans l'en-tête Authorization: Bearer yft_… — jamais dans l'adresse.

• Droits choisis à la création (voir plus bas). Par défaut : lecture et création. Publier et dépenser sont des cases à part, décochées.
• Expiration au choix : 7 jours, 30 jours, 90 jours, 365 jours, ou jamais. Une clé expirée répond 401 api_key_expired.
• Débit : 60 appels par minute par défaut (de 10 à 600, choisi à la création). Au-delà : 429 rate_limited et l'en-tête Retry-After (secondes).
• Journal : chaque action faite avec la clé (créer, modifier, publier, dépenser, supprimer), et ses lectures jusqu'à 20 000 par jour (au-delà, une ligne le dit) — date, méthode, chemin, résultat, adresse IP —, gardés 90 jours ; bouton « Journal » de chaque clé. Une ligne est écrite même quand la connexion est coupée avant la fin de la réponse : son résultat est alors 499.
• Limites d'une clé : ses droits, son débit par minute, les crédits et les budgets du compte, et le plafond par vidéo. Les plafonds du jour du serveur MCP (publications sans clic, générations payantes par jour, « toujours un clic humain ») ne valent que pour le MCP : ils ne s'appliquent pas aux routes de l'API appelées avec une clé.
• Révocation immédiate (bouton « Révoquer ») ; une clé peut se révoquer elle-même (DELETE /api/v1/keys/:id). « Tout arrêter » coupe d'un coup toutes les clés et tous les accès MCP du compte, jusqu'à ce que vous les rétablissiez ; il retire la publication sans clic, annule les demandes en attente de votre IA et met en pause les automatisations actives (elles se relancent d'un clic, une par une, dans Automatisations). Les fabrications déjà lancées chez fal (vidéos, images, voix) ne s'annulent pas : leur coût est déjà engagé ; une fabrication d'automatisation qui finit après ne publie plus seule, son post attend votre validation.
• Une clé ne crée pas de clé, ne change ni mot de passe ni clé Buffer, IA ou vidéo, n'achète rien, n'active aucune automatisation, et n'entre jamais dans l'administration.
• Les clés créées avant la version 0.85.0 gardent tous les droits qu'elles avaient (rien ne casse) ; l'écran les signale « ancienne clé » : remplacez-les par une clé limitée.

Les droits

Une route qui modifie quelque chose et n'est pas listée ci-dessous est réservée à l'application (session) : une clé y reçoit 403 session_required.

L'agent IA piloté par une clé

Écrire à l'agent (POST /api/v1/agent/conversations/:id/messages) demande le droit Dépense : chaque message fait travailler l'IA. L'agent n'utilise alors que les outils des droits de la clé : un outil hors droits ne tourne pas, l'agent reçoit le refus (insufficient_scope, avec le droit qui manque) et vous le redit. Il s'arrête aussi en cours de route si la clé est révoquée, expire, ou si « Tout arrêter » est actionné. Le message de la clé est marqué dans la conversation ([Programme : clé d'API yft_… — droits : …]) : quand vous reprenez cette conversation dans l'application, où l'agent garde tous ses outils, il ne prend jamais ce message pour votre demande ni pour votre accord. Il ne publie jamais : un post ou une automatisation qu'il prépare attend votre clic dans l'application.

create_from_template ne génère une image de cadre (payante) qu'avec aussi le droit Dépense ; sans lui, les médias du compte puis une photo de banque d'images. Le droit de chaque outil est celui de l'outil MCP qui fait le même travail.

Les erreurs

Les erreurs sont des codes stables, en JSON : { "error": "insufficient_scope", "required": "publish" }.

Les routes

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

Vidéos : le mode avancé

Le mode simple (sans preset) suit les réglages de l'administrateur : c'est le mode par défaut. Le mode avancé choisit un préréglage, ou un modèle par étape dans une liste fermée de modèles hébergés chez fal.ai : un nom absent de la liste est refusé (invalid_model), comme une étape qui n'existe pas pour le format (invalid_step) ou une définition que le modèle n'accepte pas (resolution_not_supported). Aucun autre paramètre de la requête n'atteint le modèle.

Coût estimé par le serveur avec les prix du moment, avant de lancer : POST /api/v1/video/estimate (mêmes champs que POST /api/v1/videos). Le coût réel est compté ensuite sur ce qui a été produit (durée réelle de la voix).

Sans avatar de la bibliothèque (le portrait généré est compté). Un UGC de plus de 25 s est fait en deux segments, coupés entre deux phrases. Une vidéo « scènes » enchaîne un plan de 5 s par tranche de 5 s (2 à 6 plans), avec une voix off ; sous-titres et musique en option.

Toujours, sans réglage pour le retirer : refus avant toute dépense si le coût estimé dépasse le plafond par vidéo fixé par l'administrateur (15,00 $ ; 409 video_cost_cap, avec cost et cap en dollars) ou les crédits du compte (402 credits_insufficient) ; filtres de sécurité des modèles forcés ; marque IA sur le fichier et mention visible « Vidéo générée par IA » à la publication.

curl -X POST https://media.successarchitect.fr/api/v1/video/estimate \
  -H "Authorization: Bearer yft_votre_cle" -H "Content-Type: application/json" \
  -d '{"format":"scenes","preset":"economy","seconds":15}'

Voix de marque

Une voix de marque est la voix du client, ou celle d'une personne qui lui a donné son accord écrit, reproduite par l'IA. Elle se crée dans Media Empire (Vidéos → Bibliothèque → Voix de marque) à partir d'un enregistrement de 10 secondes à 5 minutes (WAV, MP3, M4A, OGG, WEBM, FLAC, 25 Mo au plus), avec une case d'accord obligatoire : « J'ai l'accord écrit de la personne dont c'est la voix. ». L'acceptation est gardée (date, adresse IP, compte, empreinte du texte exact et de l'enregistrement). Le contenu réel du fichier est vérifié (premiers octets, lecture par un démultiplexeur imposé, une seule piste son, durée mesurée sur le son décodé), puis il est réduit à un son propre (WAV mono) avant tout envoi. Modèles : fal-ai/qwen-3-tts/clone-voice/1.7b et fal-ai/qwen-3-tts/text-to-speech/1.7b, hébergés par fal (déjà sous-traitant), filtre de sécurité toujours actif.

Prix, calculés par le serveur : création moins de 0,01 $ la minute d'enregistrement (moins de 0,01 $ pour 5 minutes) ; lecture 0,09 $ les 1 000 caractères, soit environ 0,03 $ pour un script de 20 s, à la place de la voix standard (en Premium, à la place de Gemini TTS). Vérifiés contre les crédits avant (402 credits_insufficient).

Relecture humaine, toujours (règlement IA, art. 5.1 b bis) : une voix de marque ne lit qu'un texte que le client a relu et validé en session. Votre IA (media_create_video avec voice_id) ou une clé (POST /api/v1/videos avec voiceId) obtient une demande (awaiting_client_review) : le client voit le texte exact, la voix et le coût dans Réglages → API, coche « J'ai relu ce texte » et confirme. Rien n'est lu ni dépensé avant, quel que soit le réglage des dépenses. Le texte passe aussi 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). 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 ».

Effacement : supprimer la voix efface l'enregistrement et l'empreinte chez nous ; chez fal, rien n'est gardé dans l'historique et chaque fichier s'efface au bout d'une heure. La voix part aussi avec le compte. L'export du compte n'en donne que les métadonnées : ni l'enregistrement, ni l'empreinte, qui ne sont servis par aucune route.

curl https://media.successarchitect.fr/api/v1/voices -H "Authorization: Bearer yft_votre_cle"

curl -X POST https://media.successarchitect.fr/api/v1/videos \
  -H "Authorization: Bearer yft_votre_cle" -H "Content-Type: application/json" \
  -d '{"format":"ugc","preset":"premium","seconds":15,"voiceId":"<identifiant>","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":"…"}}

Motion design et GIF

Votre IA (l'agent intégré, ou la vôtre par media_animate_project) fait d'un projet une courte vidéo animée : elle choisit un style et des préréglages dans la liste ci-dessous, et Media Empire les pose sur une copie du projet avec le moteur « Animer » de l'éditeur, puis la rend sur ses serveurs. Aucun mouvement n'est dessiné par l'IA, aucun modèle d'IA payant n'est appelé ; le design et les textes restent ceux du client. Les mêmes préréglages sont dans la fenêtre « Animer » de l'éditeur. Rien n'est publié : la vidéo se propose avec media_propose_post, le client clique.

Prix du rendu, calculé par le serveur : moins de 0,01 $ par seconde de vidéo produite, soit 0,03 $ pour 15 s, 0,06 $ pour 30 s, 0,02 $ pour un GIF de 10 s ; vérifié contre les crédits avant (402 credits_insufficient), débité sur la durée réelle. L'export que vous lancez vous-même (MP4 ou GIF d'un projet tel qu'il est) reste gratuit.

Les rôles sont trouvés sans IA : le plus grand texte est le titre ; une image marquée « logo » (rôle du cadre) ou qui couvre moins de 5 % de la page est le logo ; ce qui couvre plus de 60 % de la page est le fond. Les éléments entrent l'un après l'autre, dans la première moitié de la page. « Mot à mot » ne s'applique qu'à un texte.

Bornes de charge, toujours : 10 pages, 60 secondes en tout, 2 à 15 secondes par page, 40 éléments animés par page, un rendu à la fois par compte, une file d'attente bornée pour tout le serveur (503 render_queue_full). GIF : les 10 premières secondes, 320, 480, 640 px de large, 10, 12, 15 images par seconde, boucle sans fin, palette optimisée (palettegen / paletteuse), 8 Mo au plus (413 gif_too_large). Seules les valeurs de ces listes atteignent le rendu (invalid_motion_style, invalid_motion_preset, invalid_transition, 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.

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

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

Exemples

Rendre un projet avec d'autres valeurs pour ses variables :

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

Lister les projets, puis lancer une vidéo meme (droit « Dépense ») :

curl https://media.successarchitect.fr/api/v1/projects -H "Authorization: Bearer yft_votre_cle"

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

Proposer une automatisation par le MCP (droit « Création ») — rien n'est créé avant le clic du client :

curl -X POST https://media.successarchitect.fr/mcp \
  -H "Authorization: Bearer yft_votre_cle" -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"media_propose_automation",
       "arguments":{"name":"Conseil du jour","formats":["photo_carousel"],
       "topic":"Un conseil pratique par post sur le pain au levain","days":[1,2,3,4,5],
       "times":["09:00"],"timezone":"Europe/Paris"}}}'

Réponse : proposal_id, status: "awaiting_client_confirmation", publishing_mode: "approval" et estimate (posts sur 30 jours, coût des vidéos en dollars et en crédits, trois prochaines dates).

Le serveur MCP

Adresse : https://media.successarchitect.fr/mcp. Transport « Streamable HTTP » de la spécification MCP, sans état : une requête JSON-RPC par POST, une réponse JSON. Versions acceptées : 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26 (server/discover et métadonnées par requête en 2026-07-28 ; initialize pour les versions d'avant, sans identifiant de session). GET et DELETE répondent 405.

Connexion : une clé d'API de votre compte dans l'en-tête Authorization ; ses droits sont ceux de vos outils. Claude Code :

claude mcp add --transport http media-empire https://media.successarchitect.fr/mcp --header "Authorization: Bearer yft_votre_cle"

Cursor (mcp.json) :

{
  "mcpServers": {
    "media-empire": {
      "url": "https://media.successarchitect.fr/mcp",
      "headers": { "Authorization": "Bearer ${env:MEDIA_EMPIRE_KEY}" }
    }
  }
}

claude.ai et ChatGPT demandent une connexion OAuth : elle passera par votre espace client (passerelle à venir), qui présentera ici un jeton de service court (voir plus bas).

Ce que les outils rendent est une DONNÉE. Titres, légendes, textes des posts et descriptions viennent de vous ou de tiers : chaque résultat le rappelle à l'IA, et aucun résultat ne déclenche à lui seul une publication ou une dépense.

Erreurs propres au MCP : -32020 (en-tête différent du corps ou manquant, 400), -32022 (version non prise en charge, 400, avec data.supported), -32601 (méthode inconnue), -32602 (paramètres invalides, outil inconnu), -31001 (authentification, 401), -31003 (droit insuffisant ou accès coupé, 403 — WWW-Authenticate: Bearer error="insufficient_scope", scope="media:spend"), -31029 (débit, 429). Une erreur d'un outil (projet introuvable, plafond atteint…) revient dans son résultat avec isError: true et une explication.

Les outils MCP

tools/list ne montre que les outils de vos droits.

Ce que votre IA peut faire seule

Réglé par l'administrateur du compte dans Réglages → API (dans l'application, jamais par l'API) :

• Publier sans votre clic : désactivé par défaut. L'IA prépare alors un post (media_propose_post) que vous confirmez d'un clic dans Media Empire. Pour l'autoriser, il faut lire et accepter un avertissement (date, adresse IP, compte et empreinte du texte sont gardés), et choisir un plafond par jour (1 à 20).
• Dépenses (vidéos, portraits, musiques, sous-titres) : « plafond bas par jour » (recommandé, par défaut : 3 générations, de 1 à 20), « toujours un clic humain » (chaque génération devient une demande à confirmer), ou « sans plafond MCP » (seules les limites existantes : crédits, budgets). Les plafonds repartent à minuit, heure de Paris.
• Toujours, sans réglage pour le retirer : la marque IA lisible par machine sur ce que l'IA de Media Empire génère (règlement IA, art. 50.2) ; la mention visible « Image / Vidéo / Voix générée par IA » ajoutée à la légende d'un post de votre IA qui en contient (art. 50.4) ; les filtres de sécurité des modèles d'image et de vidéo ; les mêmes vérifications qu'à l'écran (réseaux, dates, longueur des textes, crédits). « Texte généré par IA » est ajouté aux posts publiés sans relecture qui ne contiennent ni image, ni vidéo, ni voix de l'IA ; l'administrateur peut retirer cette mention-là.
• Automatisations (depuis la version 0.87.0) : votre IA les lit (media_list_automations) et les propose (media_propose_automation) — création ou modification. Rien n'est créé avant votre clic dans Media Empire (Réglages → API, demandes de votre IA ; l'agent intégré montre la même carte dans sa conversation). La carte donne le résumé, les trois prochaines dates et le coût estimé par mois, calculé par le serveur avec les prix du moment (les mêmes que l'écran Vidéos). Une automatisation proposée est en mode « validation » : chaque post attend votre accord. Le pilote automatique (publier sans relecture) n'est posé que si vous cochez la case d'un avertissement — proposée seulement si vous l'avez demandé vous-même à l'IA, décochée par défaut — et votre acceptation est gardée (date, adresse IP, compte, empreinte du texte). Aucun réglage ne laisse votre IA créer, activer ou passer en pilote automatique une automatisation seule. Chaque post d'automatisation qui contient une image, une vidéo ou une voix de l'IA porte la mention « … générée par IA ».
• Le pilote automatique choisi à la main (depuis la version 0.88.0) : dans l'assistant d'automatisation, passer une automatisation en pilote automatique demande aussi de cocher la case de l'avertissement (envoyée avec autopilot : { accepted, warningVersion, warningLang }) ; l'acceptation est gardée de la même façon. Un post publié en pilote automatique porte « Texte généré par IA » quand il ne contient ni image, ni vidéo, ni voix de l'IA (règlement IA, art. 50.4 al. 2), sauf si l'administrateur a retiré cette mention dans Réglages → API.
• Connaissances (depuis la version 0.88.0) : vos documents (offre, ton de la marque, questions fréquentes…), rangés dans des bases nommées (Réglages → Connaissances). Votre IA les lit avec media_search_knowledge (droit de lecture), seulement dans les bases où vous avez coché « Votre IA (MCP) » — décochée à la création d'une base. Les extraits rendus ont leurs e-mails et numéros masqués, chaque ligne préfixée « | », et le résultat rappelle que ce sont des données, jamais des consignes. La recherche est faite par les mots et, quand c'est possible, par le sens — pour votre IA, seulement si son accès a aussi le droit Dépense : le vecteur de la question est un appel facturé (une fraction de centime), et un droit de lecture ne coûte jamais rien au compte. Les vecteurs sont calculés par OpenRouter région Europe (modèle mistralai/mistral-embed-2312, servi par Mistral) avec les mêmes garde-fous que l'écriture (zdr, data_collection: deny, sans repli, cinq fournisseurs permis) — aucun nouveau sous-traitant ; avec votre propre clé Anthropic, la recherche reste par les mots. Ne déposez pas de données personnelles : un extrait peut finir dans un post public.
• « Ce que votre IA a fait » : chaque action (date, application, outil, résultat, réseaux d'une publication), et les lectures jusqu'à 5 000 par jour et par compte, gardées un an ; un résumé par e-mail chaque jour où votre IA a agi. Ces plafonds du jour et ces réglages valent pour le serveur MCP ; une clé utilisée sur l'API REST est limitée par ses droits, son débit, les crédits et budgets du compte et le plafond par vidéo.

Par votre espace client (jeton de service)

La passerelle MCP de l'espace client ne transmet jamais votre jeton d'IA : Empire Billing fabrique pour elle un jeton de service, valable deux minutes, que ce serveur vérifie.

Authorization: Bearer v1.<contenu en base64url>.<HMAC-SHA256 en base64url>
clé    : HMAC-SHA256(BILLING_WEBHOOK_SECRET, "empire-mcp-v1")
contenu: { "cid": "<client Empire Billing>", "sw": "media_empire", "aud": "https://media.successarchitect.fr/mcp",
           "scp": ["media:read", "media:create"], "exp": <au plus 120 s>, "n": "<nombre unique>",
           "gid": "<autorisation>", "app": "<application d'IA>" }

Refusé : signature fausse, jeton expiré ou valable plus de deux minutes, autre logiciel, autre adresse (aud), compte non relié à ce client, compte administrateur. Le compte relié est celui que vous avez ouvert depuis votre espace client (au moins une fois, avec « Ouvrir Media Empire ») : un compte rattaché seulement d'après son adresse e-mail ne compte pas. Un ticket d'ouverture de l'espace client n'est pas un jeton de service, ni l'inverse. Il n'ouvre que /mcp.

Les versions

• /api/v1 ne change que par ajouts. Un retrait est annoncé (en-têtes Deprecation et Sunset) au moins six mois avant ; un changement incompatible ouvrira /api/v2.
• Un outil MCP retiré reste trois mois, sa description disant par quoi il est remplacé.

Media Empire — documentation servie par l'application. Données personnelles : le journal des clés est gardé 90 jours, celui du MCP un an, puis effacés.