# Just Captions

> Styled video captions for people and agents. Native iPhone app, open-source local MCP/CLI, and API-key-authenticated caption API.

## Start here
- [Agent setup and copy-ready tasks](https://justcaptions.com/agents/): Copy-ready setup for Codex and Claude Code, connecting both video tools and the caption API together; 15 animated presets.
- [Open-source MCP, CLI and renderer](https://github.com/SpaceSheepBoy/justcaptions-skill): MIT licensed. Install with uvx --from git+https://github.com/SpaceSheepBoy/justcaptions-skill@v1.4.0 justcaptions-mcp. Python 3.10+ and ffmpeg required. uv required for this install command.
- [API reference](https://justcaptions.com/api/docs/)
- [OpenAPI](https://justcaptions.com/openapi.json)
- [Style catalog](https://justcaptions.com/styles.json): style IDs, versions, overrides, legacy aliases, normalized platform safe areas.

## Local MCP
Tools: check_environment, list_styles, preview_style, caption_video, get_job, get_usage.
caption_video starts a job and returns its ID. Poll get_job until completed or failed.
Accepts a local video or folder (up to 100 files), existing SRT/VTT/JSON, style_id, overrides, size, position, safe_area, language, translate_to, correct and glossary.
Returns verified local MP4 plus SRT/VTT/JSON output paths. Output files are protected by default. Folder jobs use separate output directories per source file. Jobs persist locally; list_jobs/get_job inspect progress and resume_job recovers interrupted work.
Rendering is local. Recognition uses the API when a key is configured, otherwise faster-whisper (optional dependency and first-use model download).
Video is not uploaded. API recognition sends extracted audio; AI edits and emoji picks send caption text.
Portable fonts and animation sampling can differ from the native iOS app. Safe areas are conservative presets, not guarantees. Edited, translated or subtitle-only words have estimated timing.

## Remote MCP and HTTP API
MCP endpoint: https://api.justcaptions.com/mcp (Streamable HTTP).
Tools: list_styles, get_pricing, get_usage, transcribe_audio, correct_captions, translate_captions, pick_emojis.
Base API URL: https://api.justcaptions.com/v1
Send Authorization: Bearer with your own jc_live_ API key. Never include keys in prompts or repositories.
Remote MCP does not read local files, preview styles or render videos. Use the local MCP for those operations.
Public GET: /health, /pricing, /styles, /openapi.json.
Authenticated: POST /transcribe, /correct, /translate, /emoji; GET /usage.
Transcription takes audio only, max 12 MB decoded; returns word timestamps and segments in seconds, or SRT/VTT.
Correction/translation preserve caption count and order, not word alignment. Max 400 captions / 80,000 characters per request; emoji max 1,000 captions / 200 characters each.
For paid-operation retries supply the same Idempotency-Key (HTTP), or request_id (MCP), with identical input. Completed replies replay for 24h. Different input gives 409 idempotency_conflict; running/uncertain work gives 409 request_in_progress. Retry a running request with the same ID rather than creating new paid work. The replay store retains request hashes and completed caption replies for a 24h replay window, removed on the next request or daily cleanup (within 48h); not audio.
Keys: The human signs in at https://justcaptions.com/api/account/ using an email verification code, then creates a named, scoped, expiring key. Secrets are shown once. Key management and billing require the verified web account; an agent key cannot administer the account. Legacy keys can be linked after email verification by proving possession of the original key.
Current free allowance: 30 audio minutes and 50,000 input caption characters/month. Past it, with prepaid credits: $0.01/audio minute and $0.01/1,000 input caption characters. Query /pricing for current numbers. Check /usage before a batch. Start at $0 with no card; one-time top-ups minimum $5 ($5/$10/$20), no automatic recharge. Credits carry over without a scheduled expiry. /usage reports credit_balance_cents, credit_available_cents and credits_used_this_month_cents. Default spend cap $100/month; requests atomically reserve the shared account allowance and budget before processing.
Errors are JSON {error, code}. Handle quota_exceeded, free_tier_busy, spend_cap_reached and payment_required explicitly; do not blindly retry them. Retry transient provider errors with backoff and the same request ID.

## People
- [iPhone app](https://apps.apple.com/app/id6770354079)
- [API key and account](https://justcaptions.com/api/account/)
- [Support](https://justcaptions.com/api/support/)

Agent recovery: list_jobs, get_job, cancel_job, resume_job. Local jobs persist in ~/.local/share/justcaptions; completed files and successful cloud responses are reused. In-flight cloud requests may finish after cancellation.
First export: run_demo(output_dir="./justcaptions-demo",style_id="word-highlight") uses a bundled narrated clip and word timestamps, no key or cloud request. Demo assets and credits: https://justcaptions.com/assets/agent-demo/CREDITS.md
Budget: estimate_video locally or estimate_cost remotely before paid work; estimates are not holds. Scoped keys share account quota and atomic concurrent budget holds.
Account limits, scoped expiring keys and revocation: https://justcaptions.com/api/account/
Wheel installation: https://github.com/SpaceSheepBoy/justcaptions-skill/releases/download/v1.4.0/justcaptions_agent-1.4.0-py3-none-any.whl
Optional consent-based setup/export statistics. No media, caption text or keys in events. Remove JUSTCAPTIONS_METRICS_ID from installed MCP configuration to disable.

Free allowances use calendar months in UTC. Successful incremental excess deducts prepaid credits with exact fractional-cent accounting; free pre-top-up usage is not charged retroactively. Failed calls and identical completed retries do not debit twice. Requests stop before provider work when credits or the spend cap are insufficient (402 insufficient_credits). Stripe confirms one-time top-ups server-side; the verified account console shows credit activity, recharge invoices and PDF downloads. Older subscriptions retain monthly billing and cancellation status. API terms: https://justcaptions.com/api/terms/

Named fonts: GET https://api.justcaptions.com/v1/fonts or MCP list_fonts. Thirteen bundled Latin fonts support local rendering overrides such as {"font_id":"anton"}. font_id overrides generic font_family; null restores it. Font licenses and script coverage are in the catalog. SRT/VTT do not embed fonts.