Overview

This page outlines the end-to-end flow for creating a Voice File Job, uploading audio, and retrieving results. The current implementation uses a client-triggered upload-complete call (no S3 event).

​

What you need

• A user or system API key bound to a workspace: Authorization: Bearer {id}.{secret}
• Voice File Jobs enabled for that workspace by a Tiro administrator
• transcriptLocaleHints: up to 1 (optional)
  • If not provided, language will be automatically detected
• translationLocales: up to 5 (optional)

​

End-to-end checklist

1. Create job → receive { id, uploadUri }
2. Upload audio to uploadUri
3. Call PUT /v1/external/voice-file/jobs/{jobId}/upload-complete
4. Poll job status until completion
5. Fetch transcript and (optionally) translations
6. Get paragraph summaries for better content understanding

​

How do you receive updates and delete a job?

Subscribe to voice_file_job.created, voice_file_job.completed, voice_file_job.failed, or voice_file_job.deleted to receive lifecycle updates without polling. Webhook payloads contain job metadata, not transcript text. Fetch transcript content through the transcript endpoint. Call DELETE /v1/external/voice-file/jobs/{jobId} to remove a job in any status. Tiro removes the audio and generated results, and ignores processing callbacks that arrive after deletion.

​

How does Tiro store and protect voice file data?

Tiro stores uploaded audio in Tiro-managed object storage and stores transcripts and translations in the Tiro service database. The API does not provide a configurable automatic retention period. Call DELETE /v1/external/voice-file/jobs/{jobId} when your application no longer needs the data. A workspace user key can access jobs created by that user in the same workspace. A workspace system key can access jobs in its workspace. Deleting a job removes its uploaded audio, transcript, and translations. The deleted job is no longer available through the API.

​

Polling strategy (recommended)

• Poll GET /v1/external/voice-file/jobs/{jobId} with exponential backoff
  • Start at 1–2s interval, then 4s, 8s, up to 30s cap
  • Stop conditions:
    • Success: status = COMPLETED
    • Failure: status = FAILED
  • After success:
    • Always fetch transcript: GET /v1/external/voice-file/jobs/{jobId}/transcript
    • If you requested translations: GET /v1/external/voice-file/jobs/{jobId}/translations or per-locale endpoint
    • Get paragraph summaries:
      • For transcript: GET /v1/external/voice-file/jobs/{jobId}/transcript/paragraph-summary
      • For translations: GET /v1/external/voice-file/jobs/{jobId}/translations/{locale}/paragraph-summary

​

File Limits & Requirements

​

Supported Audio Formats

Based on industry-standard STT capabilities, Tiro supports the following formats: Audio Formats: Video Formats (audio extraction):

​

File Size & Duration Limits

​

Processing Time Estimates

Processing times are optimized with parallel processing for longer files:

​

Paragraph Summary Feature

The Paragraph Summary feature provides intelligent summarization of audio content, breaking down the transcript or translation into digestible paragraph-level summaries.

​

How it works

1. Transcript Processing: After transcription is complete, the text is automatically split into logical paragraphs using the CompositeTextSplitter
2. Summary Generation: Each paragraph is processed through the ParagraphSummarizer to create concise summaries
3. Translation Integration: When translations are requested, summaries are regenerated based on the translated content for each locale
4. Asynchronous Processing: Summary generation happens asynchronously after transcript/translation completion

​

Sequence

Ready to try it? Walk through the full flow in the Step-by-Step Tutorial — upload, poll, and fetch your first transcript end to end.