EditCaption API documentation

Overview

The EditCaption API always follows the same 3 steps: upload a media file, start a job (one endpoint per tool), then poll the job until it's done and download the result. Costly tools (captions, transcription, audio, voices) use your workspace's credits, at the same rate as in the app, reserved at launch and fully refunded if the job fails; the others are free. The REST API is included in the Pro and Scale plans; the MCP server is included in every plan, and it also runs your agency workspace (brands, posts, scheduling, analytics).

# 1. Upload a video (file or public URL)
curl -X POST https://editcaption.com/api/v1/uploads \
  -H "Authorization: Bearer ecap_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/my-video.mp4"}'
# → { "uploadId": "…", "durationSeconds": 53, "expiresIn": 10800 }

# 2. Start a job (here: automatic captions)
curl -X POST https://editcaption.com/api/v1/subtitles \
  -H "Authorization: Bearer ecap_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"uploadId": "…"}'
# → { "jobId": "…", "status": "queued", "creditsUsed": 18,
#     "creditsRemaining": 9982, "estimatedSeconds": 80 }

# 3. Poll the job until "completed", then download
curl https://editcaption.com/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer ecap_live_YOUR_KEY"
# → { "status": "completed", "result": { "url": "/api/download/…", "filename": "…" } }

Authentication

All /api/v1/* routes and the MCP server use the same API key, sent as a standard HTTP header:

Credits & plans

One rule for the app, the MCP and the API: each tool has a fixed credit cost (grid below and in each endpoint), taken from the workspace's wallet (owner), shared by the team. The plan's monthly credits go first (reset every month, no rollover), then topped-up credits (no expiry). A failed job is refunded in full, each pot getting its share back.

Top-ups (paid plans) from Settings → Workspace: 3,000 credits for €9, 7,000 credits for €19, 15,000 credits for €39. Balance anytime: GET /api/v1/account or the MCP whoami tool.

Limits & file formats

Job statuses & polling

Each job goes through 4 possible statuses, returned by GET /api/v1/jobs/:id:

No webhooks: poll

The API doesn't send an HTTP callback when a job completes: poll GET /api/v1/jobs/:id periodically. Every launch response (status: "queued") includes an indicative estimatedSeconds: a good basis for your first wait. In practice, poll every 2 to 5 seconds, no aggressive backoff needed (no rate limit for now), until completed or failed.

Error handling

Every error returns a JSON body shaped like { error: { code, message } } with the matching HTTP status. Possible codes, across all endpoints:

{
  "error": {
    "code": "insufficient_credits",
    "message": "You have 12 credits left and this action needs 60. Top up here: https://editcaption.com/espace/reglages#credits, or switch to a bigger plan: https://editcaption.com/prix",
    "balance": 12,
    "required": 60,
    "topupUrl": "https://editcaption.com/espace/reglages#credits",
    "upgradeUrl": "https://editcaption.com/prix"
  }
}

Complete code examples

A complete upload → job → wait → result flow, in JavaScript and Python. Replace the example URL and API key with yours.

// Node.js 18+ (native fetch) or browser. No npm install needed.
const API_KEY = "ecap_live_YOUR_KEY";
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)); // no webhook: poll every 3s
  }
}

async function main() {
  const upload = await call("/api/v1/uploads", { url: "https://example.com/my-video.mp4" });
  const job = await call("/api/v1/subtitles", { uploadId: upload.uploadId, style: "impact" });
  const result = await waitForJob(job.jobId);
  console.log("Video ready:", BASE + result.url);
}

main();

AI agents

MCP server

EditCaption runs a remote MCP server (Streamable HTTP) at https://editcaption.com/api/mcp. Once connected, the video tools below and the agency workspace tools show up right inside your agent, nothing to install.

One-click connection (recommended)

EditCaption implements a full OAuth 2.1 authorization server (RFC 8414 + RFC 9728, Dynamic Client Registration RFC 7591) on top of the MCP server. Claude, ChatGPT and Perplexity's native custom connectors detect it automatically: paste the URL below into their "Add custom connector" screen, sign in to your EditCaption account, click "Authorize". No key to copy: an API key is created and managed for you behind the scenes (visible and revocable in My account → Developer, labeled "MCP connector"). The exact clicks per platform are on the API page.

https://editcaption.com/api/mcp

Manual alternative (without OAuth)

For an MCP client that doesn't do OAuth discovery (script, headless environment, older config…), create a key from My account → Developer (Pro and Scale plans) and pass it as a static header:

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

Video tools

Example prompts

• "Upload this video https://example.com/interview.mp4 and add impact-style captions with white text."
• "Take this video, trim the first 30 seconds, then convert the result to webm."
• "Extract this video's audio as mp3, then transcribe it in English."
• "Merge these three videos in this order, then add a floating "@myaccount" text watermark."

Every plan

Run your agency workspace with Claude

The same MCP server gives access to your agency workspace: your assistant reads each brand's strategy, creates posts in your calendar, adds media, schedules them and reports on analytics, with exactly the same rules as in the app (per-brand access, client approval, 30-minute lead time, TikTok options).

Agency workspace tools

Reference

Example requests

• "Look at Maison Fleur's strategy and draft 5 posts for next week, one a day at 6 pm, on Instagram and TikTok."
• "Caption this video in the brand's colors, add it to Thursday's post and schedule it on TikTok."
• "Send all of this week's ready posts to my client for approval."
• "Give me a summary of this month's TikTok analytics and tell me which formats work best."

Claude Code & AI agents

To use EditCaption as a tool in Claude Code (or any other MCP client: Claude Desktop, Cursor, Codex…), add a remote HTTP MCP server. The CLI handles OAuth for you (opens your browser, same flow as Claude.ai):

# The CLI opens your browser so you can sign in and authorize access:
# no key to type, same flow as Claude.ai / Claude Desktop.
claude mcp add --transport http editcaption https://editcaption.com/api/mcp

Without a browser (headless, CI…), pass a static key as a header instead:

# Without a browser (headless/CI environment), use a static key
# created from My account → Developer:
claude mcp add --transport http editcaption \
  https://editcaption.com/api/mcp \
  --header "Authorization: Bearer ecap_live_YOUR_KEY"

Exact option syntax may vary with your version (claude mcp add --help). For Claude Desktop or any config-file client, paste the mcpServers block from the MCP server section instead.

Once connected, just ask the agent what you want in plain language (see the examples above): it picks the right MCP tools, uploads the media, starts the job, waits for the result and adds it to your calendar.

OpenAPI / Swagger

The complete OpenAPI 3.1 schema (all REST endpoints, request/response schemas, errors) is available for download. Import it into Postman, Insomnia or the Swagger editor to generate a request collection or a client in the language of your choice.

Appendix: language codes

ISO 639-1 codes accepted by the language parameters (transcription, voice change). Use auto to let the API detect the language automatically.