Skip to main content
The Voice File Job API is available on the Enterprise plan. It cannot be enabled on personal or Team plans. 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}
  • A key with scopes needs voice_file_job:write to create a job, notify upload completion, and delete, and voice_file_job:read to read. write includes read, and a key without scopes can do everything.
  • A workspace with an Enterprise plan contract and the Voice File Job policy enabled
  • An account or organization API key that is not bound to a workspace must send workspaceGuid when it creates a job
  • 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. Receive the voice_file_job.completed or voice_file_job.failed webhook (recommended). Poll job status if you cannot receive webhooks
  5. Fetch transcript and (optionally) translations
  6. Get paragraph summaries for better content understanding
Use webhooks to learn when a job finishes. Processing typically takes 45 seconds to 18 minutes depending on file duration, and can take longer when the queue is busy. With a webhook subscription, Tiro sends a voice_file_job.completed or voice_file_job.failed event when processing ends, so you do not query the job status repeatedly while you wait.
  • Subscribe to voice_file_job.completed and voice_file_job.failed. A workspace webhook receives events for every job created in that workspace, and an organization webhook receives events for every job created in any workspace of the organization. Unlike note events, folder sharing does not limit these events. An account webhook receives events only for jobs the user created with an account API key in the workspace where the webhook is registered. See Webhooks overview to register an endpoint.
  • data.resourceId is the job ID, and data.resource.status is COMPLETED or FAILED. See Event Structure for every field.
  • Webhook payloads contain job metadata, not transcript text. Fetch transcript content with GET /v1/external/voice-file/jobs/{jobId}/transcript.
  • If every delivery retry fails, Tiro does not send that event again. When a job passes its expected processing time without an event, check its status with GET /v1/external/voice-file/jobs/{jobId}.
You can also subscribe to voice_file_job.created and voice_file_job.deleted to track job creation and deletion.

​
Polling strategy (fallback)

Poll the job status when you cannot run a webhook endpoint or a webhook event does not arrive.
  • 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.

​
Can you get the transcript when a job is FAILED?

Sometimes. A job also becomes FAILED when only summary generation fails. In that case, when transcriptAvailable in the GET /v1/external/voice-file/jobs/{jobId} response is true, you can fetch the transcript with GET /v1/external/voice-file/jobs/{jobId}/transcript. The failure reason is in errorMessage. The voice_file_job.failed webhook carries the same value in data.resource.errorMessage.

​
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. 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. 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.

​
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.