---
title: "Creates a new transcription from either a sourceId or a mediaUrl. Either sourceId or mediaUrl must be provided, but not both."
method: POST
path: "/v3/Transcriptions"
tags: ["V3Transcriptions"]
---

# Creates a new transcription from either a sourceId or a mediaUrl. Either sourceId or mediaUrl must be provided, but not both.

`POST /v3/Transcriptions`

## Headers

- `Idempotency-Key` string

## Request body

- union
  - VoiceV3TranscriptionCreateRequestWithSourceId
    - `transcriptionConfigurationId` string, required — The ID of the transcription configuration to use
    - `inputSource` 'SOURCE_ID' — Discriminator indicating the input source type
    - `sourceId` string, required — The SID or TTID of the source audio to transcribe (e.g. a Twilio Recording SID). When provided, audioStartedAt is inferred from the recording's start time and does not need to be supplied by the caller.
    - `participants` VoiceV3TranscriptionParticipant[] — Array of participants in the conversation
      - `type` 'CUSTOMER' | 'HUMAN_AGENT' | 'AI_AGENT' — The role of this participant in the conversation.
      - `address` string — The phone number or identifier for this participant (E.164 format for phone numbers). Used to correlate this participant with their profile and conversation history.
      - `name` string — User-defined name for this participant
      - `audioChannelIndex` integer, required — One-based index of the audio channel in a multi-channel recording
  - VoiceV3TranscriptionCreateRequestWithMediaUrl
    - `transcriptionConfigurationId` string, required — The ID of the transcription configuration to use
    - `inputSource` 'MEDIA_URL' — Discriminator indicating the input source type
    - `mediaUrl` string, uri, required — URL to the media file to transcribe
    - `audioStartedAt` string, date-time — The start time of the audio recording
    - `participants` VoiceV3TranscriptionParticipant[] — Participants in the conversation. If omitted or partially specified, defaults from the transcription configuration will be applied.
      - `type` 'CUSTOMER' | 'HUMAN_AGENT' | 'AI_AGENT' — The role of this participant in the conversation.
      - `address` string — The phone number or identifier for this participant (E.164 format for phone numbers). Used to correlate this participant with their profile and conversation history.
      - `name` string — User-defined name for this participant
      - `audioChannelIndex` integer, required — One-based index of the audio channel in a multi-channel recording

## Response `202`

Transcription request accepted and will be processed asynchronously.
Poll the statusUrl (or Location header) to track progress.

- VoiceV3TranscriptionLongRunningOperation202Response — Response envelope for long-running operations (202 Accepted pattern). Returned immediately on acceptance and on each status poll. Extensible to allow additional fields in future versions.
  - `status` 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED', required — Current status of the long-running operation. PENDING: accepted but not yet started. RUNNING: currently in progress. COMPLETED: successfully completed. FAILED: failed and cannot be completed.
  - `statusUrl` string, uri, required — URI to poll for operation status. Mirrors the Location response header. Provided as a body field for programmatic access by JSON-parsing clients (RFC 9110 Section 15.3.3).
  - `transcription` VoiceV3TranscriptionTranscription, required
    - `id` string, required — Unique identifier for a Transcription. This is also the transcriptionId returned in the LRO 202 response.
    - `accountId` string, required — Twilio Account SID
    - `status` 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED', required — The current status of the transcription operation
    - `transcriptionConfigurationId` string, required — Unique identifier for a Transcription configuration.
    - `mediaUrl` string, uri, nullable — The third party media URL
    - `sourceId` string, nullable — The source ID (recording ID) - used for tracking only
    - `audioStartedAt` string, date-time — The call/recording start time. When the transcription was created using a sourceId, this value is inferred from the recording resource's start time. When created using a mediaUrl, this reflects the value supplied by the caller.
    - `conversationId` string, nullable — Maestro conversation ID, populated once the transcription has been stored in Maestro.
    - `participants` VoiceV3TranscriptionParticipant[] — Array of participants in the conversation
      - `type` 'CUSTOMER' | 'HUMAN_AGENT' | 'AI_AGENT' — The role of this participant in the conversation.
      - `address` string — The phone number or identifier for this participant (E.164 format for phone numbers). Used to correlate this participant with their profile and conversation history.
      - `name` string — User-defined name for this participant
      - `audioChannelIndex` integer, required — One-based index of the audio channel in a multi-channel recording
    - `duration` integer, nullable — Audio duration in seconds
    - `resolvedConfiguration` VoiceV3TranscriptionResolvedConfiguration
      - `transcriptionEngine` string — The engine used for transcription (Deepgram, Google, or auto)
      - `speechModel` string — The speech model used for transcription (e.g., nova-2, nova-3, chirp_2)
      - `language` string — The language code for transcription
      - `transcriptionStatusCallback` VoiceV3TranscriptionTranscriptionStatusCallback
        - `url` string, uri — The URL to call when transcription status changes
        - `method` 'POST' — The HTTP method to use for the callback, currently only POST is supported
        - `events` string[], nullable — The transcription events that will trigger the callback
      - `conversationConfigurationId` string, nullable — Maestro conversation configuration ID
      - `participantDefaults` object[] — Default participant configurations for the transcription
        - `audioChannelIndex` integer, required — One-based index of the audio channel
        - `type` 'CUSTOMER' | 'HUMAN_AGENT' | 'AI_AGENT', required — The participant role type
    - `createdAt` string, date-time, required — When this transcript was created
    - `updatedAt` string, date-time, required — When this transcript was last updated
    - `url` string, uri, required — The URL of this resource

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden - account not eligible
- `422` — Unprocessable Entity
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/twilio/apis/voice-v3.md) · [All operations](https://skmtc.net/twilio/apis/voice-v3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/twilio/voice-v3/revisions/77f2598e78ea/schema)