Stream Progress

Set can_stream_output to true when you create a job, and the API streams progress and transcribed segments of the prerecorded file while the job runs, instead of returning a 202. Use a stream to show progress or to read segments before the job ends. The stream uses Server-Sent Events (SSE).

Request

Create the job with Create a Job from a URL or Upload a File, and set can_stream_output to true. A stream has no endpoint of its own.

Example Requests

curl --request POST \
     --url https://api.speechischeap.com/v2/jobs/ \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
       "input_url": "https://example.com/audio-file.mp3",
       "can_stream_output": true
     }' \
     --no-buffer

The --no-buffer option prints each event as it arrives.

Response

The response is 200 OK with Content-Type: text/event-stream. Each event is a line that starts with data: and holds one JSON object, followed by a blank line. The examples below are formatted for reading, but each event is a single line. The type field names the event:

Type	Sent
initial	Once, first
progress	Periodically
segment	Once for each segment, in chronological order
final	Once, last

The API can hold segments back before it sends them, so use progress events to track a long job.

Initial

{
  "duration": 4321.5,
  "id": "00000000-1111-7222-b333-444444444444-sic",
  "request": {
    "can_label_audio": false,
    "can_parse_speakers": false,
    "can_parse_words": false,
    "can_stream_output": true,
    "input_url": "https://example.com/audio-file.mp3",
    "is_split_channel": false,
    "language": null,
    "minimum_confidence": 0.5,
    "segment_duration": 30
  },
  "type": "initial"
}

duration is the length of the audio in seconds. request repeats the options the job runs with.

Progress

{
  "id": "00000000-1111-7222-b333-444444444444-sic",
  "message": "Transcribing...",
  "processed_segments": 120,
  "total_segments": 360,
  "type": "progress"
}

total_segments can be -1 until the API knows the workload. These values count units of work, and they can differ from the number of segment events. message is a status text for people, so don't parse it. The last progress event has equal processed_segments and total_segments.

Segment

{
  "confidence": 0.987,
  "end": 12.345,
  "id": 1,
  "language": "en (99.95%)",
  "processing_duration_in_s": 0.321,
  "start": 1.234,
  "text": "This is an example of some transcribed text output.",
  "type": "segment",
  "words": []
}

A segment event has the same fields as a segment in the JSON output, plus type. See Segment Fields. Add-ons add their fields to it.

Final

{
  "type": "final"
}

When a Job Fails

If the job fails while it streams, the stream ends without a final event and without an error message. Get the job to confirm its FAILED status. The reason arrives only in your webhook, so set a webhook_url if you need it.

SRT and VTT Streams

With output_format set to srt or vtt, each event is one subtitle cue instead of JSON. These streams have no initial, progress, or final events. A VTT stream starts with a WEBVTT event. If the job fails, the stream ends without a message. Each line of a cue is prefixed with data: .

An SRT stream:

data: 1
data: 00:00:00,000 --> 00:00:06,960
data: Hello and welcome to the Speech is Cheap docs
data:

data: 2
data: 00:00:06,960 --> 00:00:07,680
data: [music]
data:

A VTT stream:

data: WEBVTT

data: 1
data: 00:00:00.000 --> 00:00:02.880
data: Hello world

data: 2
data: 00:00:03.360 --> 00:05:07.440
data: [thunder]

Errors

Errors before the stream starts are the same as for Create a Job from a URL, and the Jobs API errors explain each one. A job that fails after the stream starts sends its reason only to your webhook. Failures After a Job Is Accepted lists the reasons.

Notes

• Closing the connection doesn't cancel the job. It keeps running, and you pay when it completes. To stop it, cancel it.
• A streamed job still sends its result to webhook_url and appears in Get a Job when it completes.
• An upload with can_stream_output sends upload events before these events. See Upload a File.