Skip to main content

Broadcaster API

API for creating, reading, updating, and deleting Broadcast Tasks, plus retrieving a WebRTC token for room join.

Authorization​

All endpoints require the following headers:

  • ClientID: Unique client application identifier.
  • ClientSecret: Client application secret key.

Visit Obtaining API Keys to get ClientID and ClientSecret

Create Broadcast Task​

POST /broadcasts

Creates a new Broadcast Task to translate input stream and re-stream it to the defined outputs.

Create Request Example​

Base example (RTMP input, RTMP output):

  curl -X POST 'https://api.palabra.ai/broadcasts' \
  -H "ClientID: $API_CLIENT_ID" \
  -H "ClientSecret: $API_CLIENT_SECRET" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "title": "My Stream",
  "region": "fr",
  "original_delay_seconds": 3,
  "original_base_volume": 1,
  "original_ducked_volume": 0.2,
  "ignore_video": false,
  "input": {
    "protocol": "rtmp_push"
  },
  "outputs": [
    {
      "protocol": "rtmp_push",
      "lang_code": "es",
      "server": "rtmp:://someserver.com:1935",
      "stream_key": "abcdef12345678903"
    },
    {
      "protocol": "hls_pull",
      "lang_codes": ["original", "es"]
    }
  ],
  "translation_pipeline": {
    "transcription": {
      "source_language": "en",
      "detectable_languages": [],
      "segment_confirmation_silence_threshold": 0.7,
      "sentence_splitter": {
        "enabled": true
      },
      "verification": {
        "auto_transcription_correction": false,
        "transcription_correction_style": null
      }
    },
    "translations": [
      {
        "target_language": "es",
        "translate_partial_transcriptions": false,
        "speech_generation": {
          "voice_cloning": false,
          "voice_id": "default_low",
          "voice_timbre_detection": {
            "enabled": false,
            "high_timbre_voices": [
              "default_high"
            ],
            "low_timbre_voices": [
              "default_low"
            ]
          }
        }
      }
    ],
    "translation_queue_configs": {
      "global": {
        "desired_queue_level_ms": 5000,
        "max_queue_level_ms": 20000,
        "auto_tempo": true,
        "min_tempo": 1.15,
        "max_tempo": 1.45
      }
    },
    "allowed_message_types": [
      "translated_transcription",
      "partial_transcription",
      "partial_translated_transcription",
      "validated_transcription"
    ]
  }
}'

Request body fields:

  • title (string): Human‑readable broadcast name shown in dashboards and responses. Example: "My Stream".
  • region (string, enum): Processing region code. Currently, only "fr" is supported.
  • original_delay_seconds (number, seconds): Delay applied to the original media to align with translated speech. Typical 2–5; default is 0.
  • original_base_volume (number, 0..1): Base gain of the original track mixed under the translated track. 1.0 = unchanged loudness.
  • original_ducked_volume (number, 0..1): Gain for the original while the translated voice is speaking. Example: 0.2 lowers original to 20%.
  • ignore_video (boolean): If true, process audio only and omit video in outputs.
  • input (object): Incoming stream configuration (e.g., RTMP, SRT). Details
  • outputs (array): One or more output targets (e.g., RTMP, HLS). Each item specifies protocol, destination, and language(s). Details
  • translation_pipeline (object): Settings for transcription, translation, and speech synthesis; typically mirrors Streaming API settings. Details

Create Response Example​

{
  "ok": true,
  "data": {
    "id": "be91d203-b7ac-4b7f-85e7-083ec9b98391",
    "user": "f0a20c26-9557-47ea-9365-ab9503f6b392",
    "title": "My Stream",
    "description": "",
    "region": "fr",
    "status": "pending",
    "ignore_video": false,
    "original_delay_seconds": 3,
    "original_base_volume": 1,
    "original_ducked_volume": 0.2,
    "input": {
      "protocol": "rtmp_push",
      "url": "rtmp://rtmp.eu.palabra.ai:1935/live/da05cb241d7f5013b7b14608a1e8f812",
      "server": "rtmp://rtmp.eu.palabra.ai:1935/live",
      "stream_key": "da05cb241d7f5013b7b14608a1e8f812"
    },
    "inactive_push_inputs": [
      {
        "protocol": "srt_push",
        "url": "srt://srt.eu.palabra.ai:1337?streamid=publish/da05cb241d7f5013b7b14608a1e8f812",
        "host": "srt://srt.eu.palabra.ai",
        "port": "1337",
        "stream_id": "publish/da05cb241d7f5013b7b14608a1e8f812"
      }
    ],
    "outputs": [
      {
        "protocol": "rtmp_push",
        "server": "rtmp:://someserver.com:1935",
        "stream_key": "abcdef12345678903",
        "lang_code": "es"
      },
      {
        "protocol": "hls_pull",
        "lang_codes": [
          "original",
          "es"
        ]
      }
    ],
    "translation_pipeline": {
      // Same as in the request
    }
  }
}

Response fields:

  • id (string): Unique identifier of the broadcast. Use it to fetch, update, or delete the task.
  • status (string, enum): Current processing state. Possible values:
    • pending: Waiting for the input stream or initializing internal processing.
    • running: Input is received; translation is in progress and re‑streamed to the outputs.
    • errored: Processing failed. Inspect error_desc or errors for details.
  • input (object): Incoming stream configuration (e.g., RTMP, SRT). Details
  • inactive_push_inputs (array): Pre‑provisioned push inputs (e.g., SRT) shown for UX; not used (ignored) until that protocol is selected in input.
  • outputs (array): One or more output targets (e.g., RTMP, HLS). Each item includes protocol, destination, and language(s). Details
  • translation_pipeline (object): Transcription, translation, and speech synthesis settings; typically mirrors Streaming API options. Details

Update Broadcast Task​

PATCH /broadcasts/{id}

Updates existed Broadcast Task by its ID.

Update Request Example​

  curl -X PATCH 'https://api.palabra.ai/broadcasts/<id>' \
  -H "ClientID: $API_CLIENT_ID" \
  -H "ClientSecret: $API_CLIENT_SECRET" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    // The same as data for the Create Request
  }
}'

Update Response Example​

The same as for the Create Response

Delete Broadcast Task​

DELETE /broadcasts/{id}

Deletes existed Broadcast Task by its ID.

Delete Request Example​

  curl -X DELETE 'https://api.palabra.ai/broadcasts/<id>' \
  -H "ClientID: $API_CLIENT_ID" \
  -H "ClientSecret: $API_CLIENT_SECRET" \
  -H 'Accept: application/json'

DeleteResponse Example​

The same as for the Create Response

List Broadcast Tasks​

GET /broadcasts

Returns broadcasts owned by the authenticated user.

List Request Example​

curl -X GET "https://api.palabra.ai/broadcasts" \
  -H "ClientID: $API_CLIENT_ID" \
  -H "ClientSecret: $API_CLIENT_SECRET" \
  -H 'Accept: application/json'

List Response Example​

{
  "ok": true,
  "data": [
    {
      // ...
    },  
    {
      // ...
    }, 
  ]
}

Each Broadcast Task's structure is the same as for the Create Response

Get WebRTC room data​

GET /broadcasts/<id>/webrtc-token?room=<id>

Returns WebRTC room credentials for the broadcast listeners. In case of WebRTC output, use the credentials to subscribe to translated tracks. Learn more

WebRTC room data Request Example​

curl -X GET "https://api.palabra.ai/broadcasts/<id>/webrtc-token?room=<id>" \
  -H 'Accept: application/json'

Use the broadcast's id in both the URL path and as the room parameter value.

WebRTC room data Response Example​

{
  "ok": true,
  "data": {
    "url": "<WEBRTC_SERVER>",
    "token": "<ACCESS_TOKEN>"
  }
}