Translations

Translate an existing transcript into another language. Create the work from the Jobs API with serviceType: translation, then read or edit translated segments from the Translation endpoints.

The public create request only needs the transcript id and target language. You do not send transcript segments in the request body. The worker loads the transcript using the existing internal API client and translates the selected transcript layer.

List translations for a transcriptGET/v1/transcriptions/{transcriptionId}/translationschevron_right
Get translated segments for a languageGET/v1/transcriptions/{transcriptionId}/translations/{targetLanguage}chevron_right
Update translated segment textPATCH/v1/transcriptions/{transcriptionId}/translations/{targetLanguage}/segmentschevron_right
Retrieve a full Translation recordGET/v1/translations/{translationId}chevron_right

The Translation object

translationIdstring: Stable translation identifier (trl_…).
jobIdstring: Translation job that generated this record.
workspaceIdstring: Owning workspace.
projectIdstring: Owning project.
transcriptionIdstring: Source transcript used for translation.
transcriptionJobIdstring | null, optional: Original transcription job id for the source transcript when available.
sourceLanguagestring: Source language code used for translation. May be auto when source language was inferred.
targetLanguagestring: Requested target language code, for example ta, es, ja, or en-US.
languageKeystring: Normalized target language key used for lookup and transcript cache storage.
sourceLayerstring: Transcript layer used as translation input: current, glossary, or raw.
textstring: Full translated plain text generated by joining translated segments.
segmentsarray: Full translated segment array stored in the Translation collection. Speaker and voice metadata are copied from the source transcript when available so dubbing can reuse them.
segments[].idstring: Original source segment id. Usually matches the transcription segment id, for example seg_0.
segments[].startnumber: Original source segment start time in seconds. Used for subtitle alignment.
segments[].endnumber: Original source segment end time in seconds. Used for subtitle alignment.
segments[].textstring: Translated segment text shown in the UI. This is the primary translated text field consumers should display.
segments[].sourceTextstring: Original source segment text used as input for this translation segment.
segments[].translatedTextstring: Translated text returned by the translation engine. This currently mirrors text and is retained with quality metadata.
segments[].speakerstring | null, optional: Speaker label copied from the source transcript segment when available, for example SPEAKER_00.
segments[].voiceIdstring | null, optional: Perchat voice ID copied from the source transcript segment when available.
segments[].translationQualitystring: Translation quality label generated by the translation service, for example good or needs_review.
segments[].translationReasonstring: Optional explanation for the translation quality result. Empty string means no issue was reported.
segments[].timingRiskboolean: True when the translated text may be too long for the original segment duration.
segments[].durationSecnumber | null, optional: Segment duration in seconds, normally calculated from end - start.
segments[].maxSpeakableCharsnumber | null, optional: Estimated maximum characters that can be comfortably spoken within the original duration.
segments[].translatedCharCountnumber | null, optional: Character count of the translated segment text.
segments[].wordsarray, optional: Source word-level timing copied from the transcript when available. These are source words and timings, not translated word timings.
segments[].words[].wordstring: Source word text from the transcript word timing array.
segments[].words[].startnumber: Source word start time in seconds.
segments[].words[].endnumber: Source word end time in seconds.
segments[].words[].scorenumber: Source word confidence score when available from transcription.
segments[].words[].speakerstring | null, optional: Speaker label copied from the source word timing when available.
srtstring: Generated SubRip subtitle output for the translated text.
vttstring: Generated WebVTT subtitle output for the translated text.
textPreviewstring: Short preview of the translated text.
segmentCountinteger: Number of translated segments.
durationSecnumber | null, optional: Duration from the final translated segment end time.
translationBackendstring: Translation backend used by the worker. Currently openai.
modelstring | null, optional: Model used by the translation backend, for example gpt-4o.
vendorUsageobject | null, optional: Provider usage metadata captured from the translation provider response.
vendorUsage.providerstring: Provider used for translation, currently openai.
vendorUsage.modelstring: Model reported for provider usage.
vendorUsage.inputTokensinteger: Total input/prompt tokens consumed.
vendorUsage.outputTokensinteger: Total output/completion tokens generated.
vendorUsage.requestCountinteger: Number of provider requests made by the translation service.
vendorUsage.segmentCountinteger: Number of translated segments processed.
vendorUsage.rateUsdPerMInputTokensnumber | null, optional: Input token rate if enriched by platform billing metadata. Currently null from the translation worker.
vendorUsage.rateUsdPerMOutputTokensnumber | null, optional: Output token rate if enriched by platform billing metadata. Currently null from the translation worker.
vendorUsage.estimatedCostUsdnumber | null, optional: Estimated cost if calculated by platform billing metadata. Currently null from the translation worker.
createdAttimestamp: Record creation time.
updatedAttimestamp: Last update time.

{
  "translationId": "trl_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "jobId": "job_01HZ2K9V3JEK4WYZN6F0XQ2W9N",
  "workspaceId": "wsp_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "projectId": "prj_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "textSourceId": "txt_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "textSourceJobId": "job_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "sourceLanguage": "en",
  "targetLanguage": "ta",
  "languageKey": "ta",
  "sourceLayer": "current",
  "text": "என்ன விஷயம், FitFam?...",
  "segments": [
    {
  "id": "seg_0",
  "start": 3.06,
  "end": 4.1,
  "text": "¿Qué tal, FitFam?",
  "sourceText": "What's up, FitFam?",
  "speaker": "SPEAKER_00",
  "voiceId": "vce_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "translatedText": "¿Qué tal, FitFam?",
  "translationQuality": "good",
  "translationReason": "",
  "timingRisk": true,
  "durationSec": 1.04,
  "maxSpeakableChars": 12,
  "translatedCharCount": 17,
  "words": [
    { "word": "What's", "start": 3.06, "end": 3.5, "score": 1, "speaker": "SPEAKER_00" },
    { "word": "up,", "start": 3.5, "end": 3.74, "score": 1, "speaker": "SPEAKER_00" },
    { "word": "FitFam?", "start": 3.94, "end": 4.1, "score": 1, "speaker": "SPEAKER_00" }
  ]
}
  ],
  "srt": "1\n00:00:03,060 --> 00:00:04,100\n...",
  "vtt": "WEBVTT\n\n00:00:03.060 --> 00:00:04.100\n...",
  "textPreview": "என்ன விஷயம், FitFam?...",
  "segmentCount": 152,
  "durationSec": 318.08,
  "translationBackend": "openai",
  "model": "gpt-4o",
  "vendorUsage": {
    "provider": "openai",
    "model": "gpt-4o",
    "inputTokens": 1250,
    "outputTokens": 430,
    "requestCount": 1,
    "segmentCount": 152,
    "rateUsdPerMInputTokens": null,
    "rateUsdPerMOutputTokens": null,
    "estimatedCostUsd": null
  },
  "createdAt": "2026-05-18T12:34:56Z",
  "updatedAt": "2026-05-18T12:36:22Z"
}

List translations for a transcript

GET/v1/transcriptions/{transcriptionId}/translations

Returns available Translation records for one transcript.

Requires permission

transcript:read

Parameters

transcriptionIdstring: Transcript id.

Returns

Array of Translation records.

See the the translation object for attribute details.

curl "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/transcriptions/txt_01HX2K9V3JEK4WYZN6F0XQ2W8M/translations" \
  -H "Authorization: Bearer sk_prj_..."

{
  "data": [
  {
    "translationId": "trl_01HX2K9V3JEK4WYZN6F0XQ2W8M",
    "jobId": "job_01HZ2K9V3JEK4WYZN6F0XQ2W9N",
    "textSourceId": "txt_01HX2K9V3JEK4WYZN6F0XQ2W8M",
    "sourceLanguage": "en",
    "targetLanguage": "ta",
    "languageKey": "ta",
    "sourceLayer": "current",
    "textPreview": "என்ன விஷயம், FitFam?...",
    "segmentCount": 152,
    "durationSec": 318.08,
    "translationBackend": "openai",
    "model": "gpt-4o"
  }
],
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

Get translated segments for a language

GET/v1/transcriptions/{transcriptionId}/translations/{targetLanguage}

Returns the selected language translated segments.

Requires permission

transcript:read

Parameters

transcriptionIdstring: Transcript id.
targetLanguagestring: Target language or locale, for example ta or ta-IN.

Returns

Selected language segments with segment count.

See the the translation object for attribute details.

curl "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/transcriptions/txt_01HX2K9V3JEK4WYZN6F0XQ2W8M/translations/ta" \
  -H "Authorization: Bearer sk_prj_..."

{
  "data": {
  "textSourceId": "txt_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "targetLanguage": "ta",
  "languageKey": "ta",
  "segments": [
    {
  "id": "seg_0",
  "start": 3.06,
  "end": 4.1,
  "text": "¿Qué tal, FitFam?",
  "sourceText": "What's up, FitFam?",
  "speaker": "SPEAKER_00",
  "voiceId": "vce_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "translatedText": "¿Qué tal, FitFam?",
  "translationQuality": "good",
  "translationReason": "",
  "timingRisk": true,
  "durationSec": 1.04,
  "maxSpeakableChars": 12,
  "translatedCharCount": 17,
  "words": [
    { "word": "What's", "start": 3.06, "end": 3.5, "score": 1, "speaker": "SPEAKER_00" },
    { "word": "up,", "start": 3.5, "end": 3.74, "score": 1, "speaker": "SPEAKER_00" },
    { "word": "FitFam?", "start": 3.94, "end": 4.1, "score": 1, "speaker": "SPEAKER_00" }
  ]
}
  ],
  "segmentCount": 1
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

Update translated segment text

PATCH/v1/transcriptions/{transcriptionId}/translations/{targetLanguage}/segments

Saves manual edits to translated segment text. The API updates the transcript language array and the full Translation record.

Requires permission

transcript:edit

Parameters

transcriptionIdstring: Transcript id.
targetLanguagestring: Target language to edit.
updates[].segmentIdstring: Translated segment id.
updates[].textstring: New translated text. Cannot be empty.

Returns

Updated selected language segment payload.

See the the translation object for attribute details.

curl -X PATCH "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/transcriptions/txt_01HX2K9V3JEK4WYZN6F0XQ2W8M/translations/ta/segments" \
  -H "Authorization: Bearer sk_prj_..." \
  -H "Content-Type: application/json" \
-d '{
  "updates": [
    {
      "segmentId": "seg_0",
      "text": "எப்படி இருக்கீங்க, FitFam?"
    }
  ]
}'

{
  "data": {
  "textSourceId": "txt_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "targetLanguage": "ta",
  "languageKey": "ta",
  "segments": [
    {
  "id": "seg_0",
  "start": 3.06,
  "end": 4.1,
  "text": "¿Qué tal, FitFam?",
  "sourceText": "What's up, FitFam?",
  "speaker": "SPEAKER_00",
  "voiceId": "vce_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "translatedText": "¿Qué tal, FitFam?",
  "translationQuality": "good",
  "translationReason": "",
  "timingRisk": true,
  "durationSec": 1.04,
  "maxSpeakableChars": 12,
  "translatedCharCount": 17,
  "words": [
    { "word": "What's", "start": 3.06, "end": 3.5, "score": 1, "speaker": "SPEAKER_00" },
    { "word": "up,", "start": 3.5, "end": 3.74, "score": 1, "speaker": "SPEAKER_00" },
    { "word": "FitFam?", "start": 3.94, "end": 4.1, "score": 1, "speaker": "SPEAKER_00" }
  ]
}
  ],
  "segmentCount": 1
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

Retrieve a full Translation record

GET/v1/translations/{translationId}

Returns the full stored Translation record, including SRT/VTT and vendor metadata.

Requires permission

transcript:read

Parameters

translationIdstring: Translation id.

Returns

Full Translation record.

See the the translation object for attribute details.

curl "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/translations/trl_01HX2K9V3JEK4WYZN6F0XQ2W8M" \
  -H "Authorization: Bearer sk_prj_..."

{
  "data": {
  "translationId": "trl_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "jobId": "job_01HZ2K9V3JEK4WYZN6F0XQ2W9N",
  "workspaceId": "wsp_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "projectId": "prj_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "textSourceId": "txt_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "textSourceJobId": "job_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "sourceLanguage": "en",
  "targetLanguage": "ta",
  "languageKey": "ta",
  "sourceLayer": "current",
  "text": "என்ன விஷயம், FitFam?...",
  "segments": [
    {
  "id": "seg_0",
  "start": 3.06,
  "end": 4.1,
  "text": "¿Qué tal, FitFam?",
  "sourceText": "What's up, FitFam?",
  "speaker": "SPEAKER_00",
  "voiceId": "vce_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "translatedText": "¿Qué tal, FitFam?",
  "translationQuality": "good",
  "translationReason": "",
  "timingRisk": true,
  "durationSec": 1.04,
  "maxSpeakableChars": 12,
  "translatedCharCount": 17,
  "words": [
    { "word": "What's", "start": 3.06, "end": 3.5, "score": 1, "speaker": "SPEAKER_00" },
    { "word": "up,", "start": 3.5, "end": 3.74, "score": 1, "speaker": "SPEAKER_00" },
    { "word": "FitFam?", "start": 3.94, "end": 4.1, "score": 1, "speaker": "SPEAKER_00" }
  ]
}
  ],
  "srt": "1\n00:00:03,060 --> 00:00:04,100\n...",
  "vtt": "WEBVTT\n\n00:00:03.060 --> 00:00:04.100\n...",
  "textPreview": "என்ன விஷயம், FitFam?...",
  "segmentCount": 152,
  "durationSec": 318.08,
  "translationBackend": "openai",
  "model": "gpt-4o",
  "vendorUsage": {
    "provider": "openai",
    "model": "gpt-4o",
    "inputTokens": 1250,
    "outputTokens": 430,
    "requestCount": 1,
    "segmentCount": 152,
    "rateUsdPerMInputTokens": null,
    "rateUsdPerMOutputTokens": null,
    "estimatedCostUsd": null
  },
  "createdAt": "2026-05-18T12:34:56Z",
  "updatedAt": "2026-05-18T12:36:22Z"
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}