---
title: "Create Voice File Job"
method: POST
path: "/v1/external/voice-file/jobs"
tags: ["Voice File"]
---

# Create Voice File Job

`POST /v1/external/voice-file/jobs`

## Request

- Base URL: `https://api.tiro.ooo`
- URL: `https://api.tiro.ooo/v1/external/voice-file/jobs`
- Auth: HTTP bearer

Create a new Voice File Job for audio transcription and optional translation.

- Returns a presigned upload URI for your audio file
- Optionally specify source language hints and target translation locales
- Job starts in `CREATED` status — upload your file to begin processing
- Targets a workspace where Voice File Jobs are enabled
- Workspace-unbound user and organization keys must provide `workspaceGuid`
- Uses word memories from the key's user, workspace, and organization scopes

Documentation: [Complete workflow guide with code examples](/voice-file/tutorial)

## Request body

- object
  - `workspaceGuid` string: Workspace to use for this job and its workspace word memory. Required for workspace-unbound user and organization keys. A user key must belong to the workspace, and an organization key can only select a workspace in its organization. A workspace-bound key sends its own workspace GUID; any other workspace returns `403000`.
  - `transcriptLocaleHints` string[]: Locale hints for transcription. - Maximum 1 locale - If omitted, language is auto-detected from audio content
  - `translationLocales` string[]: Optional locales for translation (max 5)

## Response `201`

Job created successfully

- VoiceFileJobCreated: Response returned when a new Voice File Job is created. Contains the job ID and a presigned URL for uploading the audio file. **Next Steps:** 1. Upload your audio file to `uploadUri` using HTTP PUT 2. Call `PUT /v1/external/voice-file/jobs/{id}/upload-complete` to start processing
  - `id` string, required: Unique job identifier (UUID format). Use this ID in subsequent API calls.
  - `uploadUri` string, uri, required: Presigned URL for uploading the audio file. - Use HTTP PUT method to upload - URL expires in 1 hour - Set appropriate Content-Type header (e.g., audio/mpeg, audio/wav)

## Other responses

- `400`: `400000 bad request` when a workspace-unbound user or organization key omits `workspaceGuid`. Provide an accessible workspace GUID.
- `401`: Unauthorized
- `403`: `403000 forbidden` when the selected workspace is outside the key's scope or its Voice File Job policy is disabled. Select an accessible workspace or ask a Tiro administrator to enable Voice File Jobs. `403013 forbidden` when the key lacks `voice_file_job:write`. Reissue the key with the required scope.

---

[API](https://skmtc.dev/tiro/apis/tiro-api-2.md) · [All operations](https://skmtc.dev/tiro/apis/tiro-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/tiro/apis/tiro-api-2/revisions/dc1a260c6771?raw)