Translations

Translate a retained, completed transcription into one target language per job. Translation jobs belong to Speech Services; model discovery, execution admission, and monthly translation quotas belong to Text Services.

Base path: /api/v1/speech-services/translations

Resource paths in the table are relative to /api/v1/speech-services.

Create Translation

POST /api/v1/speech-services/translations

Requires Authentication - Scopes: speech:translations:write

Rate Limited - Consumes Text Services execution and Speech Services translation creation limits.

SpeechServiceTranslationRequest

POST /api/v1/speech-services/translations
Content-Type: application/json
Authorization: Bearer <token>

{
  "transcriptionId": "f9c974a4-762f-4f57-bf04-74096b45c748",
  "targetLanguageCode": "en",
  "model": "translation-default"
}

targetLanguageCode is required and uses BCP 47. Omit model to resolve the tenant default alias. Optional sourceLanguageCode explicitly overrides source detection; otherwise each segment's language is used, with a single detected transcript language as fallback. Ambiguous source languages require an override. The source must belong to the current user and retain its transcription result.

If the transcript has no language metadata, preparation fails with AMBIGUOUS_SOURCE_LANGUAGE. Set sourceLanguageCode when creating the translation, or set transcription.language.defaultLanguageCode when uploading. A speech model supporting exactly one language supplies that language automatically for new transcriptions.

Use Text Services model discovery to select a model and supported source/target pairs. Alias resolution pins the concrete model name when the job is created. Changing the alias later does not change an accepted job.

A supported base language covers its regional variants: an he → en pair accepts an he-IL transcript and an en-US target. Specific regional pairs remain restricted to those variants. Inference receives only the language subtag (he and en); API metadata retains the original language codes.

An optional webhook accepts the standard url, secret, and headers fields. Each POST creates a new job. Idempotency keys are not supported; clients should retain returned IDs and avoid automatic POST retries.

SpeechServiceTranslationResponse

Returns the job DTO with its URI in Location. See Get Translation.

Automatic translation jobs are documented with the Transcriptions API.

Lifecycle and results

PENDING / WAITING_FOR_TRANSCRIPTION → PENDING / QUEUED → IN_PROGRESS / TRANSLATING → COMPLETED, FAILED, or CANCELLED. Terminal jobs have no phase. Standalone jobs also start pending source preparation. QUEUED means the source snapshot and quota reservation are ready.

Job metadata includes IDs, status, phase, language choices, model alias, resolved model, creation/start/completion timestamps, deletion state, usage, and structured errors. List responses omit result content. The aligned result contains:

{
  "text": "Hello everyone.",
  "sourceLanguages": ["he"],
  "targetLanguageCode": "en",
  "sourceFingerprint": "<sha256>",
  "usage": { "inputTokens": 11, "tokenizerId": "unicode-codepoint-v1", "tokenizerVersion": "1" },
  "segments": [{
    "sourceSegmentIndex": 0,
    "sourceText": "שלום לכולם.",
    "text": "Hello everyone.",
    "start": 0.5,
    "end": 2.2,
    "speaker": "Speaker 1",
    "channel": 0,
    "sourceLanguageCode": "he",
    "targetLanguageCode": "en"
  }]
}

Source indices, timing, speaker labels, and channels remain aligned. Segments already in the target base language (including different regions) pass through unchanged and consume no translation tokens. If every segment is already in the target language, creation fails with NO_TRANSLATION_REQUIRED. Untimed text remains untimed; SRT/VTT export returns 409 TIMING_UNAVAILABLE rather than inventing timestamps. JSON/TXT remain available.

List Translations

GET /api/v1/speech-services/translations

Requires Authentication - Scopes: speech:translations:read

Query Parameters

Lists accept page (zero-based), size (1–100, default 20), transcriptionId, fileId, status, targetLanguageCode, model, isDeleted, createdAfter, createdBefore, completedAfter, completedBefore, and sort. Allowed sort fields are creationDate, completionDate, and status, followed by asc or desc; default is creationDate,desc. Timestamps are ISO 8601 instants; date bounds are inclusive.

SpeechServiceTranslationListResponse

The response DTO has translations, size (returned count), total, filters, and sort. By default only the current user's jobs are listed. Parent-filtered lists require read access to the file and may show translations created by other users with access. Read access follows the file; mutations remain owner-only. Purged jobs are unavailable through the public API. Callback configuration is visible only to its owner.

Get Translation

GET /api/v1/speech-services/translations/{id}

Requires Authentication - Scopes: speech:translations:read

SpeechServiceTranslationResponse

Get Translation Result

GET /api/v1/speech-services/translations/{id}/result

Requires Authentication - Scopes: speech:translations:read

Query Parameters

SpeechServiceTranslationResult

See the aligned result example. JSON returns a DTO. TXT, SRT and VTT return an attachment with the matching media type and extension.

Cancel Translation

POST /api/v1/speech-services/translations/{id}/cancel

Requires Authentication - Scopes: speech:translations:write

Cancel a pending or running job. Repeated cancellation returns the cancelled DTO. Completion that wins the terminal transition returns 409. Cancellation waits for execution to stop and releases reserved quota. If cancellation is still pending after the request timeout, the API returns 503 TRANSLATION_CANCELLATION_PENDING; retry cancellation using the same job ID.

SpeechServiceTranslationResponse

Delete Translation

DELETE /api/v1/speech-services/translations/{id}

Requires Authentication - Scopes: speech:translations:delete

Soft-delete a terminal job. Optional purge=true removes content immediately. Active jobs return 409 and must be cancelled first. Completed usage is not refunded.

Purge Translation

POST /api/v1/speech-services/translations/{id}/purge

Requires Authentication - Scopes: speech:translations:delete

Remove content from an already deleted job. An undeleted job returns 409. The content-free accounting ledger remains.

Update Translation Webhook

PUT /api/v1/speech-services/translations/{id}/webhook

Requires Authentication - Scopes: speech:translations:write

Accepts CommonWebhook: required url, optional secret and headers. Configuration cannot change after terminal settlement (409).

SpeechServiceTranslationResponse

Delete Translation Webhook

DELETE /api/v1/speech-services/translations/{id}/webhook

Requires Authentication - Scopes: speech:translations:write

Remove the callback before terminal settlement. Terminal jobs return 409.

Quotas and rate limits

Text Services owns Translation requests (textTranslations, default 10,000/month) and Translation tokens (textTranslationTokens, default 5,000,000/month). Quota responses expose used, reserved, and available; availability deducts both used and reserved capacity. Successful publication commits usage exactly once; failure or cancellation releases reservations. Deletion and purge do not refund completed usage. Usage belongs to the UTC month in which the source was admitted, including jobs that finish in a later month.

The current unicode-codepoint-v1 tokenizer counts input Unicode code points. The API unit remains translation tokens so a future tokenizer can change implementation. Output, pass-through segments, artificial separators, and repeated inference context are not billed.

Each target consumes one Text Services translation execution admission (default 60/minute) and one Speech Services translation job creation admission (default 30/minute). Automatic arrays consume one unit per target at submission. Workflow retries, source readiness, and inference batches do not consume another rate-limit unit. Existing API request limits and user/subscription overrides also apply.

Webhooks and retention

Terminal callbacks contain metadata and a result URL, never transcript or translation text. The terminal event ID remains stable across retries. Delivery uses the platform's URL restrictions, signatures, and retry policy. Consumers should deduplicate by event ID. Callback secrets and text artifacts are fetched inside activities and do not enter workflow history.

Speech retention policies govern completed results (default 90 days), failed/cancelled jobs before deletion (30 days), and deleted data before purge (30 days). Zero means immediate eligibility. Explicit file/transcription deletion cascades to translations. Automatic source expiry leaves already accepted translations independently retained. Source snapshots and attempt artifacts are removed after terminal settlement; purge removes result/error/callback content while preserving a content-free accounting ledger.

Request failures include 400 for invalid language, target, filter, or pagination; 403 for missing scope; 404 for inaccessible resources; 409 for unavailable source/result or invalid lifecycle transition; 429 for rate limits; and 503 TRANSLATION_DISABLED or TRANSLATION_START_FAILED.

Source preparation and quota admission run after job creation. Unsupported source/target pairs, ambiguous source languages, TRANSLATION_INPUT_TOO_LARGE, TRANSLATION_COUNT_QUOTA_EXCEEDED, and TRANSLATION_TOKEN_QUOTA_EXCEEDED produce FAILED jobs with a structured errors array. Read the returned job ID or use its webhook to observe the outcome. These failed jobs consume no translation quota.