Meta video transcripts

The Media Transcripts API reuses one stored transcript for each Meta video. Your credential can access a transcript only when its account can access an ad account that holds the video. Use a full-access stefan_sk_... key or one scoped to include tools, or any stefan_oat_... OAuth token (OAuth tokens are not scoped).

Identify the Meta video

You can identify a video in either form:

contentSha256: the 64-character lowercase SHA-256 of the stored video bytes.
adAccountId and providerMediaId: the Meta ad account and Meta video id.

The ad account can use the act_... form or its bare id.

Request or reuse a transcript

Send one video reference to POST /api/developers/v1/media/transcripts/request:

curl -X POST https://stefanbrain.com/api/developers/v1/media/transcripts/request \
  -H "Authorization: Bearer stefan_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "adAccountId": "act_1234567890",
    "providerMediaId": "9876543210",
    "requesterSurface": "creative_strategist"
  }'

You can instead request by hash:

{
  "contentSha256": "4f3c2b1a00000000000000000000000000000000000000000000000000000000",
  "requesterSurface": "self_learning"
}

requesterSurface records which workflow requested the transcript. Use one supported value:

self_learning
creative_strategist
launch_video_copy
chat_transcript
create_cuts
cro_funnel_review

The request is rate-limited but does not consume the API wallet or plan pool.

Handle the three outcomes

The endpoint returns 200 with one of three outcomes.

Ready

ready returns the stored transcript immediately:

{
  "status": "ready",
  "transcript": {
    "contentSha256": "4f3c2b1a00000000000000000000000000000000000000000000000000000000",
    "languageCode": "en",
    "durationSeconds": 42.7,
    "transcriptText": "...",
    "words": [
      {
        "text": "Introducing",
        "startMs": 180,
        "endMs": 640,
        "confidence": 0.98
      }
    ],
    "requestedBySurface": "creative_strategist",
    "createdAt": "2026-08-27T15:30:00.000Z",
    "updatedAt": "2026-08-27T15:30:00.000Z"
  }
}

The transcript can also include provider identity, speech model, provider transcript id, audio source, cost minutes, attempt count, and the first visible media and ad-account references.

Queued

queued means one transcription job is producing the stored result:

{
  "status": "queued",
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "contentSha256": "4f3c2b1a00000000000000000000000000000000000000000000000000000000"
}

Repeat the same request to check progress. Concurrent requests for the same stored video converge on the same active job.

Unavailable

unavailable returns the stored reason when the video cannot produce a transcript:

{
  "status": "unavailable",
  "reason": "No audio stream found in the video.",
  "contentSha256": "4f3c2b1a00000000000000000000000000000000000000000000000000000000",
  "retryAfter": null
}

When retryAfter is present, wait until that time before asking the service to retry a stored provider failure.

Read without starting transcription

Use the content hash when you only want the stored result:

curl \
  -H "Authorization: Bearer stefan_sk_your_key_here" \
  "https://stefanbrain.com/api/developers/v1/media/transcripts/4f3c2b1a00000000000000000000000000000000000000000000000000000000"

This GET never starts transcription and does not consume request limits or a billing budget. It returns ready or the stored unavailable verdict. It returns 404 transcript_not_found until a transcript row exists.

Handle transcript errors

400 invalid_transcript_request: correct the hash, reference shape, or requester surface.
403 api_key_scope_forbidden: use a credential with the tools scope.
404 video_not_found: no Meta video visible to this account matches the reference.
404 transcript_not_found: the video is visible, but no stored transcript exists. Use the request endpoint.
429: wait for the returned reset time before making another request.

The service returns video_not_found for both missing and inaccessible videos, so the endpoint does not reveal other accounts’ media.

Get started

Build with StefanBrain

Operate safely

REST API reference

Meta video transcripts

Identify the Meta video

Request or reuse a transcript

Handle the three outcomes

Ready

Queued

Unavailable

Read without starting transcription

Handle transcript errors

​Identify the Meta video

​Request or reuse a transcript

​Handle the three outcomes

​Ready

​Queued

​Unavailable

​Read without starting transcription

​Handle transcript errors

Identify the Meta video

Request or reuse a transcript

Handle the three outcomes

Ready

Queued

Unavailable

Read without starting transcription

Handle transcript errors