Translation management WebSocket API

The WebSocket API is used for controlling translation in real-time and receiving text transcriptions.

Prerequisites

Obtain the publisher's access_token and control_url by creating a streaming session.

Connection

Connect to the Palabra WebSocket Server by control_url endpoint using your access_token value as a token GET parameter:

// Palabra WebSocket endpoint
endpoint = "{control_url}?token={access_token}"

WebSocket configuration messages

Send WebSocket task messages to configure your translation pipeline, specifying the source and target languages, along with any other necessary settings.

Request/Response Structure

All request and response messages have the same structure. They include two fields, message_type and data. The error message has the text "error" in its message_type field.

{
  "message_type": string,
  "data": dict
}

General use

Send a set_task message to create a processing task. You can edit the task by sending additional set_task messages after the first one.
Send an end_task message to gracefully stop the task.
Send a pause_task to stop audio processing without deleting the task.

Settings description

For detailed settings description, refer to our translation settings breakdown section For optimal settings values, refer to our recommended settings section.

Examples

Request chain example:

Send a set_task message to create a task. Please, do not copy the settings below, refer to our recommended settings section.

{
  "message_type": "set_task",
  "data": {
    "input_stream": {
      "content_type": "string",
      "source": {
        "type": "string",
      }
    },
    "output_stream": {
      "content_type": "string",
      "target": {
        "type": "string",
      }
    },
    "pipeline": {
      "preprocessing": {
        "enable_vad": "bool",
        "vad_threshold": "float",
        "pre_vad_denoise": "bool",
        "pre_vad_dsp": "bool"
      },
      "transcription": {
        "source_language": "string",
        "detectable_languages": ["string"],
        "asr_model": "string",
        "denoise": "string",
        "allow_hotwords_glossaries": "bool",
        "suppress_numeral_tokens": "bool",
        "diarize_speakers": "bool",
        "priority": "string",
        "min_alignment_score": "float",
        "max_alignment_cer": "float",
        "segment_confirmation_silence_threshold": "float",
        "only_confirm_by_silence": "bool",
        "sentence_splitter": {
          "enabled": "bool",
          "splitter_model": "string",
          "min_sentence_characters": "int",
          "min_sentence_seconds": "int",
          "min_split_interval": "float",
        },
        "verification": {
          "verification_model": "string",
          "allow_verification_glossaries": "bool",
          "auto_transcription_correction": "bool",
          "transcription_correction_style": "null or string"
        }
      },
      "translations": [
        {
          "target_language": "string",
          "allowed_source_languages": ["string"],
          is in the list
          "translation_model": "string",
          "allow_translation_glossaries": "bool",
          "style": "null or string",
          "speech_generation": {
            "tts_model": "string",
            "voice_cloning": "bool",
            "denoise_voice_samples": "bool",
            "voice_id": "null or string",
            "voice_timbre_detection": {
              "enabled": "bool",
              "high_timbre_voices": ["string"],
              "low_timbre_voices": ["string"]
            },
            "speech_tempo_auto": "bool",
            "speech_tempo_timings_factor": "float",
            "speech_tempo_adjustment_factor": "float",
          }
        },
        {
          "target_language": "string",
          "allowed_source_languages": ["string"],
          "translation_model": "string",
          "allow_translation_glossaries": "bool",
          "style": null,
          "speech_generation": {
            "tts_model": "string",
            "voice_cloning": "bool",
            "denoise_voice_samples": "bool",
            "voice_id": "null or string",
            "voice_timbre_detection": {
              "enabled": "bool",
              "high_timbre_voices": ["string"],
              "low_timbre_voices": ["string"]
            },
            "speech_tempo_auto": "bool",
            "speech_tempo_timings_factor": "float",
            "speech_tempo_adjustment_factor": "float",
          }
        }
      ],
      "translation_queue_configs": {
        "global": { // global setting
          "desired_queue_level_ms": "int",
          "max_queue_level_ms": "int"
        },
        "es": {
          "desired_queue_level_ms": "int",
          "max_queue_level_ms": "int"
        }
      },
      "allowed_message_types": [
        "partial_transcription",
        "validated_transcription",
        "translated_transcription"
      ]
    }
  }
}

To change the translation language, send the same set_task message with a different target_language field.

Note: If you want only ASR (Automatic Speech Recognition) without speech generation, you have two options:

Set output_stream to null. In this case, you will still receive translations, but there will be no text-to-speech (TTS).
Provide an empty list for translations. This will result in neither translations nor TTS being sent.

Send end_task to finish the task:

{
  "message_type": "end_task",
  "data": {
    "force": false // Do not wait for the last segments
  }
}

Response message examples:

partial_transcription uncompleted segment transcription:

{
  "message_type": "partial_transcription",
  "data": {
    "transcription": {
      "transcription_id": "190983855fe3404e",
      "text": "one two"
    }
  }
}

validated_transcription full segment transcription:

{
  "message_type": "validated_transcription",
  "data": {
    "transcription": {
      "transcription_id": "190983855fe3404e",
      "text": "One, two, three, four, five."
    }
  }
}

translated_transcription full segment translation:

{
  "message_type": "translated_transcription",
  "data": {
    "transcription": {
      "transcription_id": "190983855fe3404e",
      "text": "Um, dois, três, quatro, cinco."
    }
  }
}

Error message examples:

validation error:

{
  "message_type": "error",
  "data": {
    "code": "VALIDATION_ERROR",
    "desc": "ValidationError(model='SetTaskMessage', errors=[{'loc': ('input_stream', 'content_type'),
     'msg': \"value is not a valid enumeration member; permitted: 'audio'\", 'type': 'type_error.enum',
      'ctx': {'enum_values': [<StreamContentType.audio: 'audio'>]}}])",
    "param": null
  }
}

Query Parameters
`_token` Token — REQUIRED Possible values: length ≤ 100 Authentication token Authentication token

Request Body — REQUIRED
`message_type` RequestMessageType — REQUIRED Possible values: [`get_task`, `set_task`, `pause_task`, `end_task`] Ws-message type
`data` Data — REQUIRED Ws-message data

Responses

200

Successful Response

Schema — OPTIONAL
`message_type` ResponseMessageType Possible values: [`current_task`, `error`, `partial_transcription`, `partial_translated_transcription`, `validated_transcription`, `translated_transcription`, `pipeline_timings`] Ws-message type
`data` Data Ws-message data

422

Validation Error

Schema — OPTIONAL

detail object[] — OPTIONAL

loc undefined[]

msg Message

type Error Type

Translation management WebSocket API

Prerequisites​

Connection​

WebSocket configuration messages​

Request/Response Structure​

General use​

Settings description​