Integration guides

Build around the API's asynchronous workflow: create a job, retain its identity, and retrieve the result. These patterns help turn a working example into a reliable application without adding unnecessary API calls.

Keep one record per operation

Store a record containing your source URL, a unique operation key, the transcript ID, and the latest processing state. The operation key is generated before submission and sent as Idempotency-Key. The transcript ID is filled in after the API accepts the request.

If your worker loses the response, retry with the same operation key and source URL. If it already has a transcript ID, request that job. This distinction prevents a temporary connection problem from becoming duplicate processing.

Keep the original source URL even after the transcript is saved. It helps your interface display a source link and gives reviewers context for quotes. Do not use a video title as the database key, because titles are display information and may not be unique.

Build a bounded queue

An account can process up to five jobs concurrently. Keep pending source records in your own queue, submit a small number, and check the accepted jobs until they finish. When one reaches completed or failed, release that local queue slot.

The request rate also applies to status reads. Use delays between polls and consider the whole account's traffic when several services share it. Separate API keys help identify integrations, but they do not create separate rate allowances.

If your interactive page stops waiting, retain the job ID and show a return path. A browser timeout does not mean the transcription was canceled. Your server can continue checking the result and make it available when the person returns.

Turn a transcript into notes

Use the completed text as source material for a notes or summarization step. Ask your model for a clear output format, such as a short summary, key claims, and timestamped quotes. Keep the transcript separate from the instruction describing what to produce.

Validate that extracted quotes appear in the source text. A model can paraphrase while presenting the result as a quote, so preserve a distinction between direct quotation and interpretation. Where the wording matters, compare it with the original video.

Store the summary and transcript separately. This lets you revise a generated summary later without losing the original result or creating another transcription request. It also makes it easier to explain which parts of the output came from the source and which came from your application.

Build a searchable collection

Index completed transcript text in your application's search system and retain segment timestamps alongside the source record. Text search can locate useful passages without requiring a person to replay every clip.

Keep access control tied to the owner of the source collection. An API account is not automatically a multi-tenant permission system for your application. If your service has several customers, enforce customer boundaries before returning any stored text or source link.

The transcript API accepts individual links; it does not enumerate a creator's account or discover videos for you. Only submit URLs gathered through a workflow you are authorized to operate.

Prepare subtitle drafts

Convert segment start and end times into the timestamp format required by your editor. The API reference includes an SRT helper. Preserve Unicode text and use UTF-8 when saving files.

Review subtitle length, timing, and punctuation before publishing. A segment boundary reflects speech processing rather than an editorial decision about the ideal line break. Adjust the subtitle draft to match the pace and layout of the final video.

If your application does not need its own export logic, the public web tool provides a ready-made transcript view with copy, TXT download, and SRT download controls. The developer endpoint remains JSON so your application can choose its own storage and presentation.

Monitor the right signals

Track accepted jobs, terminal outcomes, HTTP errors, queue depth, and the time from submission to completion. A fast create response only means the job was prepared; it is not the duration of the transcription itself.

Use job IDs in operational logs rather than copying entire transcripts into logging services. Record stable error codes so you can distinguish invalid inputs, exhausted credits, rate limits, and temporary service failures.

Review failures before enabling automated resubmission. A private or removed video will not become available because the same request is repeated more often. Show the source-access problem to the caller and let them choose the next action.