---
title: "Create transcription"
method: POST
path: "/v2/router/audio/transcriptions"
tags: ["Audio"]
---

# Create transcription

`POST /v2/router/audio/transcriptions`

## Request

- Base URL: `https://my.orq.ai`
- URL: `https://my.orq.ai/v2/router/audio/transcriptions`
- Auth: HTTP bearer

Transcribe audio input into text using the configured transcription model and return the result.

## Request body `multipart/form-data`

- object
  - `model` string, required: ID of the model to use
  - `prompt` string: An optional text to guide the model's style or continue a previous audio segment. The prompt should match the audio language.
  - `enable_logging` boolean: When enable_logging is set to false, zero retention mode is used. This disables history features like request stitching and is only available to enterprise customers.
  - `diarize` boolean: Whether to annotate which speaker is currently talking in the uploaded file.
  - `response_format` 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt': The format of the transcript output, in one of these options: json, text, srt, verbose_json, or vtt.
  - `tag_audio_events` boolean: Whether to tag audio events like (laughter), (footsteps), etc. in the transcription.
  - `num_speakers` number: The maximum amount of speakers talking in the uploaded file. Helps with predicting who speaks when, the maximum is 32.
  - `timestamps_granularity` 'none' | 'word' | 'character': The granularity of the timestamps in the transcription. Word provides word-level timestamps and character provides character-level timestamps per word.
  - `temperature` number: The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit.
  - `language` string: The language of the input audio. Supplying the input language in ISO-639-1 format will improve accuracy and latency.
  - `timestamp_granularities` string[]: The timestamp granularities to populate for this transcription. response_format must be set to verbose_json to use timestamp granularities. Either or both of these options are supported: "word" or "segment". Note: There is no additional latency for segment timestamps, but generating word timestamps incurs additional latency.
  - `name` string: The name to display on the trace. If not specified, the default system name will be used.
  - `fallback_on_codes` integer[]: HTTP status codes that trigger fallback. Enter up to 20 unique integers from 400 to 599. When omitted or empty, defaults to [408, 429, 500, 502, 503, 504, 529].
  - `fallbacks` object[]: Array of fallback models to use if primary model fails
    - `model` string, required: Fallback model identifier
  - `retry` object: Retry configuration for the request
    - `count` number: Number of retry attempts (1-5)
    - `on_codes` number[]: HTTP status codes that trigger retry logic
  - `load_balancer` object: Load balancer configuration for the request.
    - `type` 'weight_based', required
    - `models` object[], required
      - `model` string, required: Model identifier for load balancing
      - `weight` number: Weight assigned to this model for load balancing
  - `timeout` object: Timeout configuration to apply to the request. If the request exceeds the timeout, it will be retried or fallback to the next model if configured.
    - `call_timeout` number, required: Timeout value in milliseconds
  - `orq` object
    - `name` string: The name to display on the trace. If not specified, the default system name will be used.
    - `fallbacks` object[]: Array of fallback models to use if primary model fails
      - `model` string, required: Fallback model identifier
    - `fallback_on_codes` integer[]: HTTP status codes that trigger fallback. Enter up to 20 unique integers from 400 to 599. When omitted or empty, defaults to [408, 429, 500, 502, 503, 504, 529].
    - `retry` object: Retry configuration for the request
      - `count` number: Number of retry attempts (1-5)
      - `on_codes` number[]: HTTP status codes that trigger retry logic
    - `identity` PublicIdentity: Information about the identity making the request. If the identity does not exist, it will be created automatically.
      - `id` string, required: Unique identifier for the contact
      - `display_name` string: Display name of the contact
      - `email` string, email: Email address of the contact
      - `metadata` object[]: A hash of key/value pairs containing any other data about the contact
      - `logo_url` string: URL to the contact's avatar or logo
      - `tags` string[]: A list of tags associated with the contact
    - `contact` PublicContact: @deprecated Use identity instead. Information about the contact making the request.
      - `id` string, required: Unique identifier for the contact
      - `display_name` string: Display name of the contact
      - `email` string, email: Email address of the contact
      - `metadata` object[]: A hash of key/value pairs containing any other data about the contact
      - `logo_url` string: URL to the contact's avatar or logo
      - `tags` string[]: A list of tags associated with the contact
    - `load_balancer` object: Load balancer configuration for the request.
      - `type` 'weight_based', required
      - `models` object[], required
        - `model` string, required: Model identifier for load balancing
        - `weight` number: Weight assigned to this model for load balancing
    - `timeout` object: Timeout configuration to apply to the request. If the request exceeds the timeout, it will be retried or fallback to the next model if configured.
      - `call_timeout` number, required: Timeout value in milliseconds
  - `file` string, binary: The audio file object (not file name) to transcribe, in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.

## Response `200`

Returns the transcription or verbose transcription

- union
  - object
    - `text` string, required
  - object
    - `task` string
    - `language` string
    - `duration` number
    - `text` string, required
    - `words` object[]
      - `word` string
      - `start` number
      - `end` number
    - `segments` object[]
      - `id` number, required
      - `seek` number, required
      - `start` number, required
      - `end` number, required
      - `text` string, required
      - `tokens` number[], required
      - `temperature` number, required
      - `avg_logprob` number, required
      - `compression_ratio` number, required
      - `no_speech_prob` number, required
  - string

## Other responses

- `422`: Returns validation error

## Changes

> 554 revisions in range; 71 not diffed.

- **2026-10-23** `0b4e519a544f`: 2 info
  - added the new optional request property `fallback_on_codes`
  - added the new optional request property `orq/fallback_on_codes`
- **2026-10-23** `732aed62833a`: 2 warning
  - removed the request property `fallback_on_codes`
  - removed the request property `orq/fallback_on_codes`
- **2026-10-22** `4f826b2c3a0e`: 2 info
  - added the new optional request property `fallback_on_codes`
  - added the new optional request property `orq/fallback_on_codes`
- **2026-10-22** `8f0dc569f247`: 2 warning
  - removed the request property `fallback_on_codes`
  - removed the request property `orq/fallback_on_codes`
- **2026-10-21** `08b800d640e6`: 2 info
  - added the new optional request property `fallback_on_codes`
  - added the new optional request property `orq/fallback_on_codes`

[Operation history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v2/router/audio/transcriptions/post.md)

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) - [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/928a71e92252?raw)