Auto Captions API
POST /captions/auto
About this tool
Accessibility, SEO, and international distribution all lean on timed text, so `/captions/auto` runs speech-aware models plus FFmpeg packaging to emit subtitles directly from your `video_url`. One JSON field is enough to start: we fetch the media, decode audio, infer transcripts, and return caption files through the standard async task channel. Multipart uploads never appear; your subscription key authorizes every hop, and public HTTPS remains mandatory for source media. Mention audience reading speed in ancillary docs because karaoke-style pacing still requires human tweaking even when timestamps are mechanically sound.
Caption quality tracks audio clarity more than video resolution. Noisy stadium footage needs upstream denoise or manual translation; otherwise word error rates climb despite strong models. Legal teams should treat auto captions as drafts for high-stakes content, then human-review before publication. FFmpeg muxing modes (sidecar versus embedded) are spelled out alongside this anchor in `/api-docs`.
Downstream pipelines often chain `/captions/auto` immediately after `/cut` or `/redub` so timings reference final audio. Observability dashboards track queue depth separately from mux-only jobs since speech models consume GPU batches. Burst responsibly: batch overnight when launching entire course catalogs.
Compared to SaaS editors with manual timelines, API automation trades UI polish for repeatable JSON contracts engineers love. Embed correlation IDs inside your logging wrappers so CX can trace learner complaints back to singular task IDs, and annotate player manifests with FFmpeg export tags so CDN edge rules pick the subtitle variant that matched the caption job UTC timestamp.
Security posture mirrors other tools: never embed API keys inside browser extensions without tight scope, rotate secrets quarterly, and redact captions before sharing diagnostics externally since they may contain PII. Higher-education LMS integrators routinely split hour-long seminars into queued `/cut` chunks before captions run, shrinking per-task clocks and enabling cheap partial retries when one segment fails. Mention locale and jargon vocabularies in onboarding docs; even strong acoustic models stumble on densely acronymic engineering lectures.
Try it now
How it works
Verify the `video_url`
Confirm hosting allows TLS fetches without cookies and that audio tracks exist; silent videos return fast validation errors.
POST `/captions/auto`
Submit JSON with your API key. The response includes `status_url` even though the body is tiny; no binary uploads occur.
Poll models + mux stages
Track asynchronous states until FFmpeg finishes packaging captions in the promised format from documentation.
Deliver captions to players
Download sidecars or embedded outputs, register them in your CMS, and optionally translate before publication.
Frequently asked questions
Which subtitle formats can I download?
WebVTT and SRT are common exports. Check the API reference for format flags when multiple outputs are supported.
Which subscription tier includes auto captions?
Auto captions require Boost or Elite. Basic includes cut, crop, merge, redub, and related core tools but not speech-to-text captions.
How accurate are the transcripts?
Accuracy depends on language, accent, and background noise. Treat output as a draft and human-review anything compliance-critical.
Can I caption audio-only files?
This route expects a video URL with an audio track. Wrap audio in a video container or use a file that already muxes picture and sound.
Should I run captions before or after other edits?
Run captions last on the final cut so timings match the audio viewers hear. Re-cut or redub means regenerating subtitles.
Is there a limit on video length?
Long files take more processing time and may count against usage meters. Split very long recordings into chunks if jobs timeout.
How do I use the Auto Captions API?
POST to /captions/auto with a JSON body containing video_url and your X-API-Key header. The API returns a task_id; poll GET /task/{task_id} until status is "completed" to retrieve the download_url.
Via the REST API
curl -X POST https://droidapps.one/captions/auto \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
"video_url": "https://cdn.example.com/lesson.mp4"
}'Via the MCP server (droidapps-ffmpeg)
const job = await mcp.callTool("submit_job", {
path: "/captions/auto",
body: {
video_url: "https://cdn.example.com/lesson.mp4"
}
})
// Returns: { task_id: "abc123", status: "queued" }
const result = await mcp.callTool("wait_for_task", {
task_id: job.task_id
})
// Returns: { status: "completed", download_url: "https://..." }