Skip to main content
A Voice File Job goes through create, upload, upload-complete, status check, and result retrieval. The upload-complete call is made by the client; no S3 event is used.

​
What you need

  • An account or workspace API key: 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 with GET /v1/external/voice-file/jobs/{jobId}/transcript. 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. An account API key can access only the jobs it created; a workspace API key can access every job in the same workspace. Deleting a job also removes its audio, transcript, and translations, and the job can no longer be retrieved.
  • 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
The final status for successful processing is COMPLETED. This means all processing is complete including transcript, translation (if requested), and paragraph summaries for both.

​
File Limits & Requirements

​
Supported Audio Formats

The supported file formats are as follows. Audio Formats: Video Formats (audio extraction):

​
File Size & Duration Limits

​
Processing Time Estimates

Estimated processing times by file duration are as follows.

​
Paragraph Summary Feature

Paragraph Summary summarizes the transcript or translation paragraph by paragraph.

​
How it works

The transcript text is split into paragraphs and each paragraph is summarized. If you requested translations, the same process runs on the translated content. Summaries are generated asynchronously after transcription and translation finish.

​
Sequence

For a full example, see the Step-by-Step Tutorial.