Documentation API EditCaption

Vue d'ensemble

L'API EditCaption fonctionne toujours selon le même schéma en 3 étapes : tu uploades un média, tu lances un traitement (un endpoint par outil), puis tu interroges le job jusqu'à ce qu'il soit terminé et tu télécharges le résultat. Les outils coûteux (sous-titres, transcription, son, voix) consomment les crédits de ton espace, au même tarif que dans le logiciel, réservés au lancement et remboursés intégralement si le job échoue ; les autres sont gratuits. L'API REST est incluse dans les formules Pro et Scale ; le serveur MCP, lui, dans toutes les formules, et il pilote aussi ton espace agence (marques, posts, programmation, statistiques).

# 1. Uploader une vidéo (fichier ou URL publique)
curl -X POST https://editcaption.com/api/v1/uploads \
  -H "Authorization: Bearer ecap_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://exemple.com/ma-video.mp4"}'
# → { "uploadId": "…", "durationSeconds": 53, "expiresIn": 10800 }

# 2. Lancer un traitement (ici : sous-titres automatiques)
curl -X POST https://editcaption.com/api/v1/subtitles \
  -H "Authorization: Bearer ecap_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"uploadId": "…"}'
# → { "jobId": "…", "status": "queued", "creditsUsed": 18,
#     "creditsRemaining": 9982, "estimatedSeconds": 80 }

# 3. Interroger le job jusqu'à "completed", puis télécharger
curl https://editcaption.com/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer ecap_live_VOTRE_CLE"
# → { "status": "completed", "result": { "url": "/api/download/…", "filename": "…" } }

Authentification

Toutes les routes /api/v1/* et le serveur MCP utilisent la même clé API, envoyée en en-tête HTTP standard :

Crédits & formules

Une seule règle pour le logiciel, le MCP et l'API : chaque outil a un coût fixe en crédits (grille ci-dessous et dans chaque endpoint), débité sur le portefeuille de l'espace (titulaire), partagé par l'équipe. Les crédits du mois de la formule partent en premier (remis à niveau chaque mois, sans report), puis les crédits rechargés (sans expiration). Un traitement en échec est remboursé intégralement, chaque pot de sa part.

Recharges (formules payantes) depuis Réglages → Espace : 3 000 crédits pour 9 €, 7 000 crédits pour 19 €, 15 000 crédits pour 39 €. Solde à tout moment : GET /api/v1/account ou l'outil MCP whoami.

Limites & formats de fichiers

Statuts des jobs & polling

Chaque traitement passe par 4 statuts possibles, renvoyés par GET /api/v1/jobs/:id :

Pas de webhooks : fais du polling

L'API n'envoie pas de callback HTTP à la complétion d'un job : il faut interroger GET /api/v1/jobs/:id périodiquement. Chaque réponse de lancement (status: "queued") renvoie un estimatedSeconds indicatif : c'est une bonne base pour ton premier délai d'attente. Recommandation pratique : poll toutes les 2 à 5 secondes, sans backoff agressif nécessaire (pas de limite de débit à ce jour), jusqu'à completed ou failed.

Gestion des erreurs

Toute erreur renvoie un corps JSON de la forme { error: { code, message } } avec le status HTTP correspondant. Les codes possibles, tous endpoints confondus :

{
  "error": {
    "code": "insufficient_credits",
    "message": "Il te reste 12 crédits, cette action en demande 60. Recharge ici : https://editcaption.com/espace/reglages#credits, ou passe à une formule supérieure : https://editcaption.com/prix",
    "balance": 12,
    "required": 60,
    "topupUrl": "https://editcaption.com/espace/reglages#credits",
    "upgradeUrl": "https://editcaption.com/prix"
  }
}

Exemples de code complets

Un flux complet upload → traitement → attente → résultat, en JavaScript et en Python. Remplace l'URL d'exemple et la clé API par les tiennes.

// Node.js 18+ (fetch natif) ou navigateur. npm install non nécessaire.
const API_KEY = "ecap_live_VOTRE_CLE";
const BASE = "https://editcaption.com";

async function call(path, body) {
  const res = await fetch(BASE + path, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.error?.message ?? res.statusText);
  return data;
}

async function waitForJob(jobId) {
  while (true) {
    const res = await fetch(`${BASE}/api/v1/jobs/${jobId}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    const data = await res.json();
    if (data.status === "completed") return data.result;
    if (data.status === "failed") throw new Error(data.error);
    await new Promise((r) => setTimeout(r, 3000)); // pas de webhook : on poll toutes les 3s
  }
}

async function main() {
  const upload = await call("/api/v1/uploads", { url: "https://exemple.com/ma-video.mp4" });
  const job = await call("/api/v1/subtitles", { uploadId: upload.uploadId, style: "impact" });
  const result = await waitForJob(job.jobId);
  console.log("Vidéo prête :", BASE + result.url);
}

main();

Agents IA

Serveur MCP

EditCaption expose un serveur MCP distant (Streamable HTTP) à https://editcaption.com/api/mcp. Une fois branché, les outils vidéo ci-dessous et les outils de l'espace agence apparaissent directement dans ton agent, sans rien installer.

Connexion en un clic (recommandé)

EditCaption implémente un vrai serveur d'autorisation OAuth 2.1 (RFC 8414 + RFC 9728, Dynamic Client Registration RFC 7591) au-dessus du serveur MCP. Les connecteurs personnalisés natifs de Claude, ChatGPT et Perplexity le détectent automatiquement : colle l'URL ci-dessous dans leur écran « Ajouter un connecteur personnalisé », connecte-toi à ton compte EditCaption, clique « Autoriser ». Aucune clé à copier-coller : une clé API est créée et gérée automatiquement en coulisses (visible et révocable dans Mon compte → Développeur, sous le libellé « Connecteur MCP »). Le détail des clics exacts par plateforme est sur la page API.

https://editcaption.com/api/mcp

Alternative manuelle (sans OAuth)

Pour un client MCP qui ne fait pas de découverte OAuth (script, environnement headless, ancienne config…), crée une clé depuis Mon compte → Développeur (formules Pro et Scale) et passe-la en en-tête statique :

{
  "mcpServers": {
    "editcaption": {
      "url": "https://editcaption.com/api/mcp",
      "headers": { "Authorization": "Bearer ecap_live_VOTRE_CLE" }
    }
  }
}

Outils vidéo

Exemples de prompts

• « Uploade cette vidéo https://exemple.com/interview.mp4 et ajoute-lui des sous-titres style impact, texte blanc. »
• « Prends cette vidéo, découpe les 30 premières secondes, puis convertis le résultat en webm. »
• « Extrais l'audio de cette vidéo en mp3, puis transcris-le en anglais. »
• « Fusionne ces trois vidéos dans cet ordre, puis ajoute un filigrane texte "@moncompte" en position flottante. »

Toutes les formules

Piloter ton espace agence avec Claude

Le même serveur MCP donne accès à ton espace agence : ton assistant lit la stratégie de chaque marque, crée les posts de ton planning, y ajoute les médias, les programme et te fait le point sur les statistiques, avec exactement les mêmes règles que dans le logiciel (accès par marque, validation client, délai de 30 minutes, options TikTok).

Outils de l'espace agence

Référence

Exemples de demandes

• « Regarde la stratégie de Maison Fleur et prépare 5 posts pour la semaine prochaine, un par jour à 18 h, sur Instagram et TikTok. »
• « Sous-titre cette vidéo aux couleurs de la marque, ajoute-la au post de jeudi et programme-la sur TikTok. »
• « Envoie tous les posts prêts de la semaine en validation à mon client. »
• « Fais-moi le point sur les statistiques TikTok du mois et dis-moi quels formats marchent le mieux. »

Claude Code & agents IA

Pour utiliser EditCaption comme outil dans Claude Code (ou tout autre client MCP : Claude Desktop, Cursor, Codex…), ajoute un serveur MCP distant en HTTP. Le CLI gère l'autorisation OAuth automatiquement (ouvre ton navigateur, même flux que Claude.ai) :

# Le CLI ouvre ton navigateur pour te connecter et autoriser l'accès —
# aucune clé à saisir, même flux que Claude.ai / Claude Desktop.
claude mcp add --transport http editcaption https://editcaption.com/api/mcp

Sans navigateur disponible (headless, CI…), passe une clé statique en en-tête à la place :

# Si le navigateur n'est pas disponible (environnement headless/CI), utilise
# une clé statique créée depuis Mon compte → Développeur :
claude mcp add --transport http editcaption \
  https://editcaption.com/api/mcp \
  --header "Authorization: Bearer ecap_live_VOTRE_CLE"

La syntaxe exacte des options peut varier selon ta version (claude mcp add --help). Pour Claude Desktop ou tout autre client à fichier de config, colle plutôt le bloc mcpServers vu dans la section Serveur MCP.

Une fois connecté, demande directement à l'agent ce que tu veux faire en langage naturel (voir les exemples ci-dessus) : il choisit lui-même les bons outils MCP, uploade le média, lance le traitement, attend le résultat et l'ajoute à ton planning.

OpenAPI / Swagger

Le schéma OpenAPI 3.1 complet (tous les endpoints REST, schémas de requête/réponse, erreurs) est disponible en téléchargement. Importe-le directement dans Postman, Insomnia, ou l'éditeur Swagger pour générer une collection de requêtes ou un client dans le langage de ton choix.

Annexe : codes de langue

Codes ISO 639-1 acceptés par les paramètres language (transcription, changement de voix). Utilise auto pour laisser l'API détecter la langue automatiquement.