Dashboard

Media Caption API v1

Transcriptions

Create AI transcriptions from YouTube, Instagram, TikTok, or cloud media URLs, then poll the result.

Create an AI transcription

POST/v1/transcriptions

Social video sources

Send a YouTube, Instagram, or TikTok video link in sourceUrl. Instagram and TikTok platform share links are also supported. The video must be accessible without signing in and have a finite duration. This endpoint generates an AI transcription even when existing captions are available.

curl -X POST https://api.mediacaption.io/v1/transcriptions \
  -H "Authorization: Bearer mc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"sourceUrl":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

The same request accepts Instagram links such as https://www.instagram.com/reel/ABC123/ and TikTok links such as https://www.tiktok.com/@creator/video/1234567890123456789. Local audio and video files use the multipart upload flow.

Acceptance and billing

  • A successful request returns HTTP 202 with transcriptionId, status, sourceUrl, durationSec, sizeBytes, requiredCredits, and statusUrl. Social sources have sizeBytes: null.
  • Poll statusUrl (GET /v1/transcriptions/{id}) until status is completed or failed. Existing results may already be completed when accepted.
  • Credits are calculated from the video duration and charged before queueing. Pipeline failures are refunded. Completed cached results still incur the normal request charge.
  • A paid active request for the same account and video is reused with requiredCredits: 0. If the original request is still being started, HTTP 409 asks you to retry shortly.
  • HTTP 422 means the social video or its duration could not be inspected; no credits are charged. Invalid links return HTTP 400 and insufficient credits return HTTP 402.

Cloud source behavior

Provide a public or presigned HTTPS URL. Media Caption probes its size and duration without retaining the file, charges the exact credits, and transcribes the media directly from the URL. The maximum source size is 3 GB. Signed URLs must remain valid while the source is fetched.

Cloud source example

curl -X POST https://api.mediacaption.io/v1/transcriptions \
  -H "Authorization: Bearer mc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"sourceUrl":"https://storage.example.com/meeting.mp4?signature=..."}'

Poll a transcription

GET/v1/transcriptions/{id}

Retention

API transcriptions are retained for 3 days after completion. After expiration, the endpoint returns 410 transcription_expired.

Poll example

curl https://api.mediacaption.io/v1/transcriptions/tr_3f6e5c6a-0d31-4f8c-9b1d-7f3b9e6a2c11 \
  -H "Authorization: Bearer mc_live_xxx"

Example response

{
  "transcriptionId": "tr_3f6e5c6a-0d31-4f8c-9b1d-7f3b9e6a2c11",
  "source": "public",
  "status": "completed",
  "language": "en",
  "sourceUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "durationSec": 184,
  "expiresAt": "2026-05-14T10:00:01.000Z",
  "transcript": [{ "startSec": 0, "durationSec": 2.4, "text": "Example transcript text" }]
}
Next: Local File Uploads