Retranslation SSE

Connection Information

Note: The browser's native EventSource API does not support custom headers. Use the fetch API together with ReadableStream, or use an SSE client library that supports headers.

Endpoint Overview

Common to all three endpoints: when content cannot be translated, llm_content_filtered is reported with severity warning and context translation, unlike the error / sse used for other translation failures. If your client filters events by severity, make sure warning is not filtered out, or these failures disappear entirely.

GET /api/v1/sse/retranslate/{taskId}

Description

Retranslates all sentences of the specified task into the target language. Translation results are streamed one by one over SSE.

Use Cases

• Switching the display language
• Updating translated content

Authentication

Header: X-API-Key (see Authentication)

Request Parameters

Segmented Retranslation

Retranslating a very long transcript in one go can exceed the processing time of a single request. With segmented=1, each request translates one segment, and you continue with the nextSid returned in done.

Continuation flow

1. Send ?targetLang=en-US&segmented=1.
2. When done arrives:
   • No truncated: translation is finished.
   • truncated: true: send the next request with fromSid={nextSid} (you can also send expectedRevision={revision} to make sure the transcript was not changed by anything else in the meantime).
3. Repeat until done no longer carries truncated.

Note: The parameter names are fromSid and expectedRevision. Sending from_sid or expected_revision, or fromSid without segmented=1, is rejected (see "Parameter validation failures" below); nothing is translated or charged.

Request Example

curl -N "https://vas-poc.vurbo.ai/api/v1/sse/retranslate/550e8400-e29b-41d4-a716-446655440000?targetLang=en-US" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

// Use the fetch API (because EventSource does not support headers)
async function retranslateSSE(taskId, targetLang, apiKey) {
  const response = await fetch(
    `https://vas-poc.vurbo.ai/api/v1/sse/retranslate/${taskId}?targetLang=${targetLang}`,
    {
      headers: {
        'X-API-Key': apiKey
      }
    }
  );
  const reader = response.body.getReader();
  // ... handle SSE events
}

Event Sequence

0. connected      → Connection confirmed
1. translation    → sends translation results one by one (successful sentences, repeated N times)
   error          → a sentence failed to translate (per-sid, interleaved with translation)
   error          → failed to save the transcript, another write is in progress, or expectedRevision does not match (storage_upload_failed / transcript_revision_conflict; the flow stops and done is **not** sent)
2. done           → translation complete (in segmented mode, possibly just this segment)

Failed sentences do not emit translation; instead they emit event: error carrying sid + error_code. The failure event format matches real-time translation over WebSocket, so the frontend can share one error handler.

Event Format

translation

{
  "sid": 1,
  "text": "Hello",
  "is_final": true
}

error (per-sid failure)

When a sentence fails to translate, translation is not emitted; error is emitted instead:

{
  "error_code": "sse_translation_failed",
  "severity": "error",
  "message": "SSE translation failed",
  "context": "sse",
  "sid": 5,
  "request_id": "req_abc123",
  "timestamp": "2026-04-26T10:30:45.123Z",
  "details": {
    "translation_language": "ja-JP",
    "original_error": "..."
  }
}

Handle the two failures differently: llm_content_filtered means the sentence content cannot be translated and retrying will not change the result — revise the original text and try again. sse_translation_failed means the translation did not complete this time; retrying later usually succeeds. The two carry different severity and context values (see the table above). If you filter events by severity, make sure warning is not filtered out.

Failed sentences are stored as translation error records (see history-playback), so the failure markers appear the next time the history is loaded. The stored value is the error code above. A failed language is not written with a new translation: if it already had one, the previous translation is kept; if it did not, the language is absent from the translations. So do not decide whether this run succeeded by checking only whether the language key is present — those two cases would read as success and as never-translated respectively. Check the translation error records as well.

done

{
  "totalUpdated": 10,
  "characters_billed": 12700,
  "charged": "6.4",
  "billed": true
}

Example of a done cut short in segmented mode:

{
  "totalUpdated": 640,
  "characters_billed": 25600,
  "charged": "12.8",
  "billed": true,
  "revision": 7,
  "truncated": true,
  "nextSid": 641
}

Billing fields: characters_billed, charged, and billed appear only when the request actually incurred consumption. When nothing was consumed (for example, when generation fails), all three are absent. Always use billed to determine whether a request was billed (billed only when billed is true) — that criterion applies to every endpoint that carries billing fields, with no per-endpoint exceptions. Integrators that call this API on behalf of end users and bill them separately can use charged directly instead of deriving it.

Specific Error Codes

Parameter validation failures carry no error code: when targetLang is missing or is not a supported language, or when segmented, fromSid, or expectedRevision has an invalid value or usage, the response is HTTP 200 with event: error, and data contains only message — no error_code, severity, context, request_id or timestamp. Read message directly, and note that this differs from the other errors on this page.

Frontend Example

async function retranslate(taskId, targetLang, apiKey) {
  const response = await fetch(
    `https://vas-poc.vurbo.ai/api/v1/sse/retranslate/${taskId}?targetLang=${targetLang}`,
    {
      headers: {
        'X-API-Key': apiKey
      }
    }
  );

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const events = parseSSE(decoder.decode(value));
    for (const event of events) {
      if (event.type === 'translation') {
        console.log(`Sentence ${event.data.sid}: ${event.data.text}`);
      } else if (event.type === 'done') {
        console.log(`Done, ${event.data.totalUpdated} sentences updated`);
      }
    }
  }
}

GET /api/v1/sse/retranslate/summary/{taskId}

Description

Retranslates the summary of the specified task into the target language. Translation results are streamed segment by segment over SSE.

The retranslated result is not saved: the saved summary and its language are unchanged, and reloading the history still returns the original summary. To switch the summary to another language and keep it, use the save endpoint of Regenerate Summary (POST, billed).

• The source language is the language of the summary itself. For example, a summary that has been regenerated in English is translated as English.
• For a long summary, the stream often delivers a large block at once, with a pause of a few seconds between events, but each event is still the cumulative full text.
• Processing time and timeouts follow the same rules as Summary Translation: a request has a limit of about 230 seconds, and an error is sent if translation pauses for more than 60 seconds.
• To translate summary content the server does not have (for example a merged or edited summary), use Summary Translation.

Use Cases

• Switching the summary display language
• Obtaining the summary in a different language

Authentication

Header: X-API-Key (see Authentication)

Request Parameters

Request Example

curl -N "https://vas-poc.vurbo.ai/api/v1/sse/retranslate/summary/550e8400-e29b-41d4-a716-446655440000?targetLang=en-US" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

// Use the fetch API (because EventSource does not support headers)
async function retranslateSummarySSE(taskId, targetLang, apiKey) {
  const response = await fetch(
    `https://vas-poc.vurbo.ai/api/v1/sse/retranslate/summary/${taskId}?targetLang=${targetLang}`,
    {
      headers: {
        'X-API-Key': apiKey
      }
    }
  );
  const reader = response.body.getReader();
  // ... handle SSE events
}

Event Sequence

0. connected              → Connection confirmed
1. summary_translation    → sends summary translation segment by segment (repeated N times)
   error                  → translation failed (the flow stops; done is **not** sent)
2. done                   → translation complete

Event Format

summary_translation

{
  "text": "Accumulated translation result...",
  "is_final": false
}

done

{
  "totalUpdated": 1
}

This endpoint is not billed. Its done event does not include the characters_billed / charged / billed fields. Re-translating an existing summary incurs no additional charge; only full-text retranslation (previous section) is billed.

Specific Error Codes

GET /api/v1/sse/recordings/{taskId}/entries/{sid}/retranslate

Description

Retranslates a single sentence. The most common scenario: after a user edits the original text via PATCH /api/v1/tasks/{id}/entries/{sid}, this endpoint is called to redo all translations of that sentence.

Differences from full-transcript retranslation (/retranslate/{taskId}):

• Full-transcript retranslation: translates all sentences into a specified language (a single target language)
• Single-sentence retranslation: translates only one sentence, but can retry every language it has been translated into or failed to translate into at once

Use Cases

• Automatically triggered after a user edits the STT original text
• Recovery for individual sentences that failed to translate

Authentication

Header X-API-Key or query api_key — both work. The browser's native EventSource cannot send custom headers, so use the query parameter in that case. See Authentication.

Request Parameters

Request Example

# Retranslate all existing languages
curl -N "https://vas-poc.vurbo.ai/api/v1/sse/recordings/{taskId}/entries/5/retranslate?api_key=vas_xxx"

# Retranslate only en-US, and require the revision to be 3
curl -N "https://vas-poc.vurbo.ai/api/v1/sse/recordings/{taskId}/entries/5/retranslate?targetLang=en-US&expectedRevision=3&api_key=vas_xxx"

Event Sequence

1. connected   → connection confirmed
2. progress    → started translating a language (once per language)
3. translated  → that language's translation completed (once per language)
   or error    → that language's translation failed
4. done        → all complete

Event Format

progress

{ "sid": 5, "lang": "en-US", "status": "translating" }

translated

{
  "sid": 5,
  "lang": "en-US",
  "text": "Hello world",
  "tokens_used": 25
}

error (single-language failure)

The error codes are the same set as full-text retranslation: llm_content_filtered when the content cannot be translated, and sse_translation_failed otherwise. The example below shows only the key fields; the actual event carries the same fields as the error event of full-text retranslation (see the field table in that section).

{
  "error_code": "sse_translation_failed",
  "sid": 5,
  "details": { "translation_language": "ja-JP", "original_error": "..." }
}

done

{
  "sid": 5,
  "revision": 6,
  "original_text_edited_at": "2026-05-06T10:30:00.000000Z",
  "languages_translated": ["en-US"],
  "languages_failed": ["ja-JP"]
}

Specific Error Codes

Version: V1.24.1 Last Updated: 2026-09-28