> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stefanbrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Follow the content contract in AGENTS.md.
> Treat text as the canonical explanation; video and screenshots enhance it.
> Do not publish unverified product behavior or duplicate an existing canonical article.

# Meta video transcripts

> Read a stored Meta video transcript or request one for a video in an accessible ad account.

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`:

```bash theme={"system"}
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:

```json theme={"system"}
{
  "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:

```json theme={"system"}
{
  "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:

```json theme={"system"}
{
  "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:

```json theme={"system"}
{
  "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:

```bash theme={"system"}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.