curl --request PUT \
  --url https://api.studio.us.phrase.com/v1/projects/{projectId}/recordings/{recordingId}/subtitles \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "language": "en",
  "source": true,
  "dubbing": false,
  "enqueueTtsUpdate": false,
  "subtitles": [
    {
      "id": "seg-1",
      "key": "seg-1_en_true_false",
      "time_begin": 0,
      "time_end": 1.8,
      "speaker": "speaker_1",
      "language": "en",
      "text": "Hello and welcome.",
      "words": [
        {
          "word": "Hello",
          "time_begin": 0,
          "time_end": 0.5
        },
        {
          "word": "and",
          "time_begin": 0.5,
          "time_end": 0.8
        },
        {
          "word": "welcome.",
          "time_begin": 0.8,
          "time_end": 1.8,
          "is_eos": true
        }
      ]
    }
  ]
}
'

Subtitles

Update Subtitle

Replace the subtitle segments of a recording’s language track. The request body must contain every segment in the final state — the endpoint performs a bulk replace, not a partial patch. Any segment you omit is removed from the track. Use this to push subtitle edits made externally (for example, by AI editing tools) back into Studio.

`words` is the source of truth — never send empty `words`

Each segment’s words array (word-level text and timings) is authoritative. Subtitle rendering and dubbing text-to-speech are generated from words; the segment-level text field is only a human-readable mirror and is ignored when rendering subtitles or synthesizing speech.

A segment whose words array is empty is treated as having no content: it is silently dropped the next time the track is read, and for dubbing nothing is synthesized for it. This is the most common cause of a track that “comes back empty” after an update. Never submit "words": [] unless you intend to remove that segment’s content.

To change what a segment says — for example, shortening a dubbing line — rewrite its words array, not just text. Mirror the change in text for readability, but the words entries are what actually change the rendered subtitle and the generated audio.

Recommended workflow

GET the track to fetch the current segments with their word-level timings.
Edit the words array of the segment(s) you want to change (and mirror the new text in text). Leave every other segment untouched.
PUT the full segment array back. For a dubbing redub, list the changed segment ids in segmentsToRedub and keep enqueueTtsUpdate=true so their audio is regenerated from the new words.

To edit text without triggering re-synthesis, set enqueueTtsUpdate to false — but still send the full words array for every segment.

Language scoping

The language value must match the requested task type for the recording:

When source=true and dubbing=false (transcription), language must equal the recording source language.
When source=false and dubbing=false (translation), language must be one of the recording translation languages.
When source=false and dubbing=true (dubbing), language must be one of the recording translation languages.
source=true and dubbing=true together is invalid.

Mismatched combinations return 400 with a descriptive message rather than reaching the underlying file lookup.

PUT

projects

{projectId}

recordings

{recordingId}

subtitles

curl --request PUT \
  --url https://api.studio.us.phrase.com/v1/projects/{projectId}/recordings/{recordingId}/subtitles \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "language": "en",
  "source": true,
  "dubbing": false,
  "enqueueTtsUpdate": false,
  "subtitles": [
    {
      "id": "seg-1",
      "key": "seg-1_en_true_false",
      "time_begin": 0,
      "time_end": 1.8,
      "speaker": "speaker_1",
      "language": "en",
      "text": "Hello and welcome.",
      "words": [
        {
          "word": "Hello",
          "time_begin": 0,
          "time_end": 0.5
        },
        {
          "word": "and",
          "time_begin": 0.5,
          "time_end": 0.8
        },
        {
          "word": "welcome.",
          "time_begin": 0.8,
          "time_end": 1.8,
          "is_eos": true
        }
      ]
    }
  ]
}
'

Authorizations

X-API-Key

string

header

required

Path Parameters

projectId

string<uuid>

required

Project ID

recordingId

string<uuid>

required

Recording ID

Body

application/json

language

string

required

BCP-47 language code of the track to write

subtitles

object[]

required

Full segment list for the target language track. The endpoint performs a bulk replace, so the array must contain every segment in the final state, not just the edited ones. Every segment must include a non-empty words array; omitting a segment deletes it, and an empty words array drops the segment on the next read.

Show child attributes

source

boolean

default:false

True when writing the source (transcript) track

dubbing

boolean

default:false

True when writing a dubbing track

bgVolume

number

Dubbing background-audio volume (only honored for dubbing tracks)

speakerVolumes

object

Per-speaker volume overrides (dubbing only)

Show child attributes

speakerVoiceSettings

object

Per-speaker TTS voice settings (dubbing only)

Show child attributes

segmentsToRedub

string[]

Segment ids that should be re-synthesized after this update

enqueueTtsUpdate

boolean

default:true

When true (default), the dubbing segments listed in segmentsToRedub are queued for TTS regeneration from their words. Set to false to save edits without re-synthesis (for example, text-only fixes) — you must still send the full words array for every segment.

Response

Subtitles updated successfully

Get Subtitle

⌘I

Guides

API Documentation

Update Subtitle

`words` is the source of truth — never send empty `words`

Recommended workflow

Language scoping

Authorizations

Path Parameters

Body

Response