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. Chaque appel qui lance un traitement débite des crédits prépayés, réservés immédiatement et remboursés intégralement si le job échoue.

# 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 :

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 estimatedSecondsindicatif : 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": "Crédits insuffisants. Rechargez votre compte sur editcaption.com/api",
    "balance": 12,
    "required": 60
  }
}

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 12 outils ci-dessous 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 Perplexityle 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, section « Installation en 30 secondes ».

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 et passe-la en en-tête statique :

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

Outils disponibles

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. »

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 précédente.

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

OpenAPI / Swagger

Le schéma OpenAPI 3.1 complet (tous les endpoints, 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 autopour laisser l'API détecter la langue automatiquement.