Create a Stream
Create a live stream that ingests a source feed, processes it with AI in real time, and publishes dubbed, translated, or transcribed outputs.
Overview
This endpoint is the entry point of the streaming lifecycle. It takes a source feed, one or more processing pipelines, and one or more output destinations, and returns astream_id you use for every other lifecycle operation.
How a stream fits together
The request body is built from four blocks that reference each other byid:
Source
source_stream - the live feed to ingest, e.g. srt://ingest.example.com:9000.
You can also use the play URL of a stream flow here, or
push the feed to Camb.ai with
deferred_source_stream instead.Audio selections
audio_selections - name the audio track(s) of the source you want to
process and declare their spoken language. Use
Probe a Source Stream to discover tracks, or start with
$first_audio.Profiles and pipelines
processing_profiles define how audio is processed (demixing,
transcription, translation, revoicing, each none, best_model, or
fast_model). pipelines connect an audio selection to a profile and
declare the output assets to produce, each with a language.Targets
target_streams - where the processed output goes. At least one is
required. Push to your own endpoint (SRT/RTMP), or let Camb.ai host the
output for you (SRT listener or HLS recording).Before you start
Collect the IDs the payload references:- Language IDs -
GET /source-languagesandGET /target-languages. Languages are numeric IDs; for example1is English (US) and54is Spanish (Spain).
- Voice IDs (optional) -
GET /list-voices. If you pass voice IDs, dubbed speech uses those fixed voices. If you leave them out, voices are cloned from the speakers in the source audio. - Dictionary IDs (optional) -
GET /dictionariesfor custom terminology, up to 5.
audio output must also declare a subtitle
output in the same pipeline; the transcript drives the dubbing. You do not
have to route the subtitle asset to a target.Example: dub a football match into Spanish
The example ingests the SRT feed of a football match, dubs the English commentary (1) into Spanish (54), and pushes the dubbed program (original
video plus Spanish commentary) to an SRT destination of your own.
Scheduling
Every stream needs anend_time (with its timezone); the stream stops
automatically at that moment. start_time is optional: omit it to start
right away, or set it to schedule the stream for later.
- Times are ISO 8601 with a UTC offset, and the
timezone(IANA name) must match their offset. start_timecannot be in the past and at most 7 days in the future.end_timemust be at least 15 minutes after the start.
end_time, delete it. To extend
or shorten a running stream, update its end_time.
Hosted ingest
If your encoder cannot be reached from the internet, or you would rather push than be pulled, replacesource_stream with deferred_source_stream. Camb.ai
hosts an SRT endpoint for the stream’s ingest and returns its URL as
source_publish_url; point your encoder at it (as an SRT caller) once the
stream is created.
source_stream and deferred_source_stream.
Choosing targets
inputs: pipeline outputs by asset_id, and untouched
source tracks by passthrough_selector (e.g. v:0 for the video). Source
tracks that are not replaced by a pipeline output are forwarded automatically
unless you set passthrough_policy to none.
Regions
Camb.ai-hosted SRT endpoints live in one region each. The hosted ingest (deferred_source_stream.region) and each SRT listener target
(target_streams[].region with "type": 6) take a region from
List Flow Regions; without one they are hosted in
us-central1. One stream can mix regions, for example an ingest and a Spanish
output in us-central1 and a French output in europe-west2:
- HLS recording targets (
"type": 3) are always served fromus-central1. Omitregion, or set it tous-central1. - Other target types (SRT caller, RTMP, YouTube, sidecar subtitles) do not
take a
region. - A region is fixed once the stream is created: the returned URLs carry that region’s address.
Errors
402- Insufficient credits for the requested configuration.422- Validation error: missing required blocks, anidreference that doesn’t resolve (e.g. a pipeline referencing an unknown profile), invalid language IDs, or malformed URLs. Also returned for aregionthat is not in List Flow Regions (the error names the available regions), aregionother thanus-central1on an HLS recording target, and aregionon a target type that does not take one.
Related endpoints
- Probe a Source Stream - inspect the source before creating
- Get Stream Status - monitor state and output URLs
- Update a Stream - reschedule, reconfigure, or toggle dubbing live
- Delete a Stream - terminate a running or scheduled stream
- Create an SRT Flow - standing SRT endpoints usable as source or target
Authorizations
Body
Configuration for a live stream. Exactly one of source_stream or deferred_source_stream is required.
Optional voice IDs from GET /list-voices to use for dubbed speech. If provided, these fixed voices are used; if omitted or empty, voices are cloned from the speakers in the source audio. When providing voices, include different genders and tones so each speaker can be matched to the most suitable voice.
Optional dictionary IDs for custom terminology (up to 5), from GET /dictionaries.
5Response
Successful Response