How to Transcribe Segments of a Video with API Calls

The question comes up whenever someone wires a transcription API into a real workflow: the recording is two hours long, and the part that matters is between 1:12:30 and 1:24:05. Transcribing the whole file to get twelve minutes of text feels wasteful, and most transcription endpoints take a file and return a transcript, with no concept of a time range at all.

The clean answer is that "transcribe a segment" is two operations, cutting and transcribing, and the only decision is which order to run them in. Know the timestamps already? Cut first and transcribe the cut. Will the timestamps come from the words? Transcribe the master once and slice the transcript. Both shapes run as one API call against a published Treza pipeline. Here is each one, the JSON that comes back, and the timing trap that catches people who caption the result.

Two shapes, and how to pick

Shape A: cut, then transcribe. You pass a source URL, a start, and an end. The pipeline pulls just that range out of the master, transcribes it, and returns the clip plus its transcript. You pay to transcribe twelve minutes, not two hours. Use this when a human, a chapter list, or an earlier run already told you where the segment is.

Shape B: transcribe, then slice. You pass the source URL and nothing else. The pipeline transcribes the whole master once and returns a timestamped transcript. Finding the segment is then a filter over that JSON, which is free, and cutting it is a second call with the timestamps you found. Use this when the segment is defined by what was said: every time the guest mentions the product, the strongest thirty seconds, the section between two phrases.

Getting this backwards is how a workflow ends up transcribing the same master once per segment.

Shape A: cut the segment in place, then transcribe it

A File node holds the source video, and because File is an entry node, a run started over the API can pass a URL for it instead of the dropped file. Two Text Input nodes, labelled Start and End, are entry nodes too. All three wire into an Extract Clip node, which wires into a Transcribe node, with an Output node for the transcript and one for the clip URL.

Extract Clip takes its start and end as seconds or as timecodes, so "4350" and "1:12:30" mean the same thing. It reads long masters in place and seeks directly into the source, so only the requested segment is ever rendered. The clipping step takes roughly as long as the segment is, not as long as the master is.

Two settings on that node matter. When you only need the words, set Output to Audio and the node pulls an MP3 soundtrack out of the video instead of re-encoding picture you will not use. And Max clip length is a guard: set it to the longest segment you expect and a bad pair of timestamps fails the run instead of quietly rendering the last ninety minutes of the file.

The Transcribe node then runs on the clip. Whisper Large v3 is the default and returns word-level timestamps; the GPT-4o Transcribe models return clean text faster when timing is not needed. Every timestamp in the result is relative to the clip's own start, so the first word lands near zero, not at 1:12:30. If you want master time, add the start you passed in; the clip's Result output carries it.

Shape B: transcribe the master once, then slice by timestamp

Here the graph is a File node into a Transcribe node into an Output. Long recordings are transcribed in chunks automatically and stitched back into one continuous transcript, so a multi-hour master comes back with every timestamp on the master's own timeline. The node has four outputs: the plain text, an SRT, a small result object with the language, duration, and segment count, and the one you want for slicing, the transcript JSON. It carries segments and words, each with a start and end in seconds:

{
  "language": "en",
  "segments": [
    { "start": 4350.2, "end": 4354.9, "text": "So the thing nobody tells you about pricing is" },
    { "start": 4354.9, "end": 4359.1, "text": "that the first number you say is the one that sticks." }
  ],
  "words": [
    { "start": 4350.2, "end": 4350.5, "word": "So" },
    { "start": 4350.5, "end": 4350.7, "word": "the" }
  ]
}

Slicing a segment out of that is a filter in your own code: keep every segment inside your range and join the text. No second API call, no second charge. Search works the same way: find the word, read its start, and you have a timestamp to cut at.

If you would rather the pipeline find the segments, the transcript JSON also feeds a Text Generation node directly. Ask it to answer in JSON with start and end fields and wire that answer into Extract Clip's Range input, which accepts exactly that object. When the model wraps its answer in something larger, a JSON Parse node with an extract path pulls the range out first. That is the same transcribe, pick, cut chain the podcast clip generator runs, where the picker is told to land on sentence boundaries and skip intros, outros, and sponsor reads.

The API calls

Every published pipeline is a versioned endpoint. The request keys are derived from the entry nodes' labels, lowercased with punctuation turned into underscores, so a File node labelled Source video becomes source_video. For shape A the call is:

POST /api/pipelines/<pipeline-id>/invoke
Authorization: Bearer treza_live_...
Content-Type: application/json

{
  "inputs": {
    "source_video": "https://example.com/episode-142.mp4",
    "start": "1:12:30",
    "end": "1:24:05"
  }
}

The response is HTTP 202 with a runId. The work is queued on the background worker and your connection is free, which matters because transcribing twelve minutes of audio is not a request you want to hold open. You then poll:

GET /api/pipelines/<pipeline-id>/invoke?runId=<run-id>
Authorization: Bearer treza_live_...

The status is running until the run finishes, and the outputs appear once it does, keyed by the names of your Output nodes:

{
  "runId": "run_...",
  "status": "success",
  "outputs": {
    "clip": "https://.../episode-142-segment.mp3",
    "transcript": { "language": "en", "segments": [ ... ], "words": [ ... ] }
  }
}

Polling costs nothing. Shape B is the same pair of calls with only source_video in the inputs, and the transcript output is the full master's JSON.

Two limits apply to the loop you will write around this. Invocations are rate limited to 60 requests per minute for an account, and one pipeline holds at most 10 runs in flight at once; the eleventh gets a 429 with the code TOO_MANY_CONCURRENT_RUNS. A small worker pool with a retry on 429 handles both.

Many segments from one master

When the segment list is long, there are two ways to avoid one call per segment. Inside the graph, a Run Pipeline node with For each turned on takes a JSON array of start and end pairs and runs the cut-and-transcribe sub-pipeline once per item, up to 50 items per node with 4 sub-runs at a time, collecting per-item status and cost. From your own code, fan out one POST per segment against the 10-in-flight ceiling and poll them as a batch. The batch video generation API post weighs the two and it applies unchanged here.

What each shape costs

Transcription is the paid step and it costs cents; cutting is render time. Shape A pays for the minutes you asked for and nothing else. Shape B pays for the whole master once, then every slice, search, and picker pass over the JSON is free. Take one segment and shape A is cheaper and faster; take more than a handful from the same recording and shape B wins by the second one. Failed runs cost nothing in either shape.

If you are going to caption the segment, transcribe the cut

This is the trap. Suppose you took shape B, found a segment in the master transcript, and cut it. It is tempting to caption the cut with the transcript you already have, because the words are right. The timings are not: every timestamp is still on the master's clock, so a caption meant for 1:12:34 fires seventy-two minutes after the clip ends. Burned-in captions need the cut's own timeline, which means one more Transcribe node on the extracted clip. The burned-in captions versus SRT post covers the same trap from the captions side.

That second pass is short, because the clip is short. It also gives you speaker labels: turn on Label speakers and every word is tagged with the voice that said it, so a two-host segment reads correctly when the caption generator colours by speaker. The AI video transcriber page lists every output and model, the older post on transcribing video automatically covers the whole-file case, and if the segment was generated rather than recorded, the same graph sits downstream of the AI video generator unchanged.

Frequently Asked Questions

Can I pass a start and end time to a transcription API?

Not to a bare transcription endpoint, which takes a file and returns a transcript for all of it. In a pipeline the range is a separate step: an Extract Clip node cuts the segment in place using a start and end given as seconds or timecodes, and the Transcribe node runs on the cut. Published as an API, the start and end are two input keys in the request body.

Do I have to download or re-upload the whole video to transcribe part of it?

No. The source is a URL, and Extract Clip reads long masters in place and seeks directly into the file, so only the requested range is rendered. If the master lives with you rather than at a URL, uploads support files up to 30GB with resumable multipart upload.

Are the timestamps in a segment transcript relative to the clip or to the original video?

To the clip, when you cut first and then transcribe: the first word lands near zero, and master time is the start you cut at plus each timestamp. When you transcribe the master first, timestamps are already on the master's timeline and slicing does not change them.

How do I transcribe several segments from the same recording?

Either transcribe the master once and slice the transcript JSON by timestamp in your own code, which costs one transcription however many segments you take, or run a Run Pipeline node with For each over a JSON array of start and end pairs, up to 50 per node, which cuts and transcribes each one.

Can the pipeline find the segments for me instead of taking timestamps?

Yes. Wire the master's transcript JSON into a Text Generation node, ask it to answer with start and end fields in JSON, and wire that answer into Extract Clip's Range input, through a JSON Parse node if the model nests it. That is the picker the podcast clip pipeline uses to find the strongest thirty to sixty seconds.

Why are my captions out of sync after I cut a segment?

Because they were burned in from the master's transcript, whose timestamps are on the master's clock. Add a Transcribe node after the Extract Clip node and caption from that transcript instead. The cut is short, so the second pass is quick.