Ingesting Transcript Files

Setup

The setup for Dynamic Ingest requests is the same, whether you are ingesting a video, images, a Transcript file, or all of these. For full details of the request body fields, see the API Reference.

Request URL

        https://ingest.api.brightcove.com/v1/accounts/account_id/videos/video_id/ingest-requests

Authentication

Authentication requires an access token passed as a Bearer token in an Authorization header:

        Authorization: Bearer {access_token}

Note on S3

If your Transcript will be pulled from a protected S3 bucket, you will need to set a bucket policy to allow Video Cloud to access the files. See Using Dynamic Ingest with S3 for details.

Ingest Transcript files

You can also add Transcript files to your video or upload them for an existing video using Dynamic Ingest:

Add transcripts during video ingestion

Request URL

https://ingest.api.brightcove.com/v1/accounts/account_id/videos/video_id/ingest-requests

Method

POST

Sample request body

{
  "master": {
    "url": "https://support.brightcove.com/test-assets/videos/Great_Blue_Heron.mp4"
  },
  "transcriptions": [
    {
      "url": "https://support.brightcove.com/test-assets/transcript/herons-transcript.txt",
      "srclang": "en-US",
      "kind": "transcripts",
      "label": "English",
      "default": true,
      "status" : "published"
    }
  ]
}

Add transcripts existing videos

Adding transcripts to existing videos is exactly the same, except that you do not need any of the video information or the profile in the request body. unless you are requesting closed transcript to be added to MP4 renditions - in that case, you will need to replace the video

Request URL

        https://ingest.api.brightcove.com/v1/accounts/account_id/videos/video_id/ingest-requests

Method

POST

Sample request body

{
  "transcriptions": [
    {
      "url": "https://support.brightcove.com/test-assets/transcripts/herons.txt",
      "srclang": "en-US",
      "kind": "transcripts",
      "label": "English",
      "default": true,
      "status" : "published"
    }
  ]
}

Ingest fields

The following table details the fields used for ingesting transcripts or requesting auto captions.

Caption translation and dubbing

Within each object in the transcriptions array, you can add translation_languages to translate auto-generated captions into additional languages. Each translation entry is an object with:

• srclang (required) — BCP-47 target language code
• label (optional) — display label
• status (optional) — draft or published
• dubbing (optional, boolean) — when true, generates dubbed audio for that language after translated captions exist
• disable_voice_cloning (optional, boolean) — when true, uses a synthetic voice instead of voice cloning for dubbing
• ai_transparency_label (optional, string) — AI transparency label for translated captions (text tracks) for this target language when supported
• ai_transparency_label_dubbing (optional, string) — AI transparency label for dubbed audio generated for this target language when supported (typically used when dubbing is true)

Dubbing depends on translated captions, and translated captions depend on auto captions for the source language. If prerequisites are missing, downstream steps may not run.

Sample transcriptions with translations

{
  "transcriptions": [{
    "srclang": "en-US",
    "label": "English",
    "status": "published",
    "kind": "captions",
    "translation_languages": [
      { "srclang": "es-ES", "label": "Spanish", "status": "draft", "dubbing": true, "disable_voice_cloning": true, "ai_transparency_label": "AI-generated captions", "ai_transparency_label_dubbing": "AI-generated audio" },
      { "srclang": "fr-FR", "label": "French", "status": "draft" }
    ]
  }]
}

For account-level defaults that prefill Studio upload fields (API clients may still send any values), see GET/PUT https://ingest.api.brightcove.com/v1/accounts/{account_id}/ingestion-configurations in the Universal Translator documentation.

To start translation jobs outside an ingest request, use POST https://ingest.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/ai/translation with a target_languages array (same per-language shape as above). See AI translation endpoints for request and response details.

AI metadata enhancement at ingest

You can queue AI Metadata Optimizer jobs together with auto captions by including metadata_optimizer on a transcriptions object. The object uses the same fields as POST .../videos/{video_id}/ai/metadata-enhancement/{language} and must include language (BCP-47). On ingest, include translation_request (with only languages) only when skip_review and auto_translate are both true so metadata can be applied and then translated in one job; omit translation_request for review workflows (skip_review false). Use explicit caption fields such as srclang on the transcriptions entry when combining with metadata or translation—do not use autodetect: true in those cases. Other typical optional fields include fields_to_generate, use_tag_architecture, references, and character_limits. Full behavior is described in AI Metadata Optimizer — API access.

Sample ingest body (review workflow)

{
  "transcriptions": [
    {
      "srclang": "en-US",
      "label": "English",
      "kind": "captions",
      "status": "published",
      "metadata_optimizer": {
        "language": "en-US",
        "fields_to_generate": ["names", "short_descriptions", "tags", "long_descriptions"],
        "skip_review": false
      }
    }
  ]
}

Sample ingest body (generate, apply, and translate in one job)

Requires explicit srclang on the transcriptions entry (not autodetect), and both skip_review and auto_translate set to true with translation_request.languages:

{
  "transcriptions": [
    {
      "srclang": "en-US",
      "label": "English",
      "kind": "captions",
      "status": "published",
      "metadata_optimizer": {
        "language": "en-US",
        "fields_to_generate": ["names", "short_descriptions", "tags", "long_descriptions"],
        "skip_review": true,
        "auto_translate": true,
        "translation_request": {
          "languages": ["es-ES", "fr-FR"]
        }
      }
    }
  ]
}

Creating a job via ingest uses the same job lifecycle as direct API calls: poll or delete with GET/DELETE on .../videos/{video_id}/ai/metadata-enhancement/{language}, and list jobs with GET .../ai/metadata-enhancement/jobs. Full field reference and behavior notes are in AI Metadata Optimizer — API access.

Audio description at ingest

On each object in the transcriptions array, optional audio_descriptions queues AI Audio Description in the same ingest workflow (typically with auto captions so a text track exists). Use the same body as POST .../videos/{video_id}/ai/audio-descriptions: required languages, an array of BCP-47 language codes with at least one entry (e.g. ["en-US", "es-ES"]), and optional ai_transparency_label (string) for AI transparency on generated descriptive audio when supported. One descriptive audio track per language.

Sample transcriptions with audio_descriptions

{
  "transcriptions": [
    {
      "srclang": "en-US",
      "label": "English",
      "kind": "captions",
      "status": "published",
      "audio_descriptions": {
        "languages": ["en-US"],
        "ai_transparency_label": "AI-generated audio"
      }
    }
  ]
}

Standalone audio description endpoints

You can also create or list jobs without an ingest request:

• POST | GET https://ingest.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/ai/audio-descriptions — create a job (body: required languages array as above; optional ai_transparency_label when supported) or list jobs for the video (GET)
• GET https://ingest.api.brightcove.com/v1/accounts/{account_id}/ai/audio-descriptions/jobs — list audio description jobs for the account

For supported languages and job response fields, see Audio Description — API access.

Supported languages

Currently, the supported languages for transcripts are limited to the following languages