{ "swagger": "2.0", "info": { "title": "Azure Speech Transcription API", "version": "2025-10-15", "x-typespec-generated": [ { "emitter": "@azure-tools/typespec-autorest" } ] }, "schemes": [ "https" ], "x-ms-parameterized-host": { "hostTemplate": "{endpoint}/speechtotext", "useSchemePrefix": false, "parameters": [ { "name": "endpoint", "in": "path", "description": "Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).", "required": true, "type": "string", "format": "uri", "x-ms-skip-url-encoding": true } ] }, "produces": [ "application/json" ], "consumes": [ "application/json" ], "security": [ { "ApiKeyAuth": [] }, { "AadOauth2Auth": [ "https://cognitiveservices.azure.com/.default" ] } ], "securityDefinitions": { "AadOauth2Auth": { "type": "oauth2", "description": "The Azure Active Directory OAuth2 Flow", "flow": "accessCode", "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", "scopes": { "https://cognitiveservices.azure.com/.default": "" }, "tokenUrl": "https://login.microsoftonline.com/common/oauth2/token" }, "ApiKeyAuth": { "type": "apiKey", "name": "Ocp-Apim-Subscription-Key", "in": "header" } }, "tags": [], "paths": { "/transcriptions:transcribe": { "post": { "operationId": "Transcribe", "description": "Transcribes the provided audio stream.", "consumes": [ "multipart/form-data" ], "parameters": [ { "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter" }, { "name": "definition", "in": "formData", "description": "Metadata for a transcription request. This field contains a JSON-serialized object of type `TranscriptionOptions`.", "required": true, "type": "string" }, { "name": "audio", "in": "formData", "description": "The content of the audio file to be transcribed. The audio file must be shorter than 2 hours in audio duration and smaller than 250 MB in size. Optional if audioUrl is provided in the definition.", "required": false, "type": "file" } ], "responses": { "200": { "description": "The request has succeeded.", "schema": { "$ref": "#/definitions/TranscriptionResult" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Azure.Core.Foundations.ErrorResponse" }, "headers": { "x-ms-error-code": { "type": "string", "description": "String error code indicating what went wrong." } } } }, "x-ms-examples": { "Transcribe audio file": { "$ref": "./examples/transcribe_transcription.json" }, "Transcribe audio from URL": { "$ref": "./examples/transcribe_audio_url.json" }, "Transcribe with enhanced mode": { "$ref": "./examples/transcribe_enhanced_mode.json" } } } } }, "definitions": { "Azure.Core.Foundations.Error": { "type": "object", "description": "The error object.", "properties": { "code": { "type": "string", "description": "One of a server-defined set of error codes." }, "message": { "type": "string", "description": "A human-readable representation of the error." }, "target": { "type": "string", "description": "The target of the error." }, "details": { "type": "array", "description": "An array of details about specific errors that led to this reported error.", "items": { "$ref": "#/definitions/Azure.Core.Foundations.Error" } }, "innererror": { "$ref": "#/definitions/Azure.Core.Foundations.InnerError", "description": "An object containing more specific information than the current object about the error." } }, "required": [ "code", "message" ] }, "Azure.Core.Foundations.ErrorResponse": { "type": "object", "description": "A response containing error details.", "properties": { "error": { "$ref": "#/definitions/Azure.Core.Foundations.Error", "description": "The error object." } }, "required": [ "error" ] }, "Azure.Core.Foundations.InnerError": { "type": "object", "description": "An object containing more specific information about the error. As per Azure REST API guidelines - https://aka.ms/AzureRestApiGuidelines#handling-errors.", "properties": { "code": { "type": "string", "description": "One of a server-defined set of error codes." }, "innererror": { "$ref": "#/definitions/Azure.Core.Foundations.InnerError", "description": "Inner error." } } }, "ChannelCombinedPhrases": { "type": "object", "description": "The full transcript per channel.", "properties": { "channel": { "type": "integer", "format": "int32", "description": "The 0-based channel index. Only present if channel separation is enabled." }, "text": { "type": "string", "description": "The complete transcribed text for the channel." } }, "required": [ "text" ] }, "EnhancedModeProperties": { "type": "object", "description": "Enhanced mode properties for transcription.", "properties": { "enabled": { "type": "boolean", "description": "Enable enhanced mode for transcription. This is automatically set to true when task, targetLanguage, or prompt are specified.", "readOnly": true }, "task": { "type": "string", "description": "Task type for enhanced mode." }, "targetLanguage": { "type": "string", "description": "Target language for enhanced mode." }, "prompt": { "type": "array", "description": "A list of user prompts.", "items": { "type": "string" } } } }, "PhraseListProperties": { "type": "object", "description": "Phrase list properties for transcription.", "properties": { "phrases": { "type": "array", "description": "List of phrases for recognition.", "items": { "type": "string" } }, "biasingWeight": { "type": "number", "format": "float", "description": "Biasing weight for phrase list (0.0-2.0)." } } }, "ProfanityFilterMode": { "type": "string", "description": "Mode of profanity filtering.", "enum": [ "None", "Removed", "Tags", "Masked" ], "x-ms-enum": { "name": "ProfanityFilterMode", "modelAsString": true, "values": [ { "name": "None", "value": "None", "description": "Disable profanity filtering." }, { "name": "Removed", "value": "Removed", "description": "Remove profanity." }, { "name": "Tags", "value": "Tags", "description": "Add \"profanity\" XML tags " }, { "name": "Masked", "value": "Masked", "description": "Mask the profanity with * except of the first letter, e.g., f***" } ] } }, "TranscribedPhrase": { "type": "object", "description": "A transcribed phrase.", "properties": { "channel": { "type": "integer", "format": "int32", "description": "The 0-based channel index. Only present if channel separation is enabled." }, "speaker": { "type": "integer", "format": "int32", "description": "A unique integer number that is assigned to each speaker detected in the audio without particular order. Only present if speaker diarization is enabled." }, "offsetMilliseconds": { "type": "integer", "format": "int32", "description": "The start offset of the phrase in milliseconds." }, "durationMilliseconds": { "type": "integer", "format": "int32", "description": "The duration of the phrase in milliseconds." }, "text": { "type": "string", "description": "The transcribed text of the phrase." }, "words": { "type": "array", "description": "The words that make up the phrase. Only present if word-level timestamps are enabled.", "items": { "$ref": "#/definitions/TranscribedWord" } }, "locale": { "type": "string", "description": "The locale of the phrase." }, "confidence": { "type": "number", "format": "float", "description": "The confidence value for the phrase." } }, "required": [ "offsetMilliseconds", "durationMilliseconds", "text", "confidence" ] }, "TranscribedWord": { "type": "object", "description": "Time-stamped word in the display form.", "properties": { "text": { "type": "string", "description": "The recognized word, including punctuation." }, "offsetMilliseconds": { "type": "integer", "format": "int32", "description": "The start offset of the word in milliseconds." }, "durationMilliseconds": { "type": "integer", "format": "int32", "description": "The duration of the word in milliseconds." } }, "required": [ "text", "offsetMilliseconds", "durationMilliseconds" ] }, "TranscriptionDiarizationOptions": { "type": "object", "description": "The Speaker Diarization settings. Diarization settings must be specified to enable speaker diarization.", "properties": { "enabled": { "type": "boolean", "description": "Enable speaker diarization. This is automatically set to true when maxSpeakers is specified.", "readOnly": true }, "maxSpeakers": { "type": "integer", "format": "int32", "description": "Gets or sets a hint for the maximum number of speakers for diarization. Must be greater than 1 and less than 36.", "minimum": 2, "maximum": 35 } } }, "TranscriptionResult": { "type": "object", "description": "The result of the transcribe operation.", "properties": { "durationMilliseconds": { "type": "integer", "format": "int32", "description": "The duration of the audio in milliseconds." }, "combinedPhrases": { "type": "array", "description": "The full transcript for each channel.", "items": { "$ref": "#/definitions/ChannelCombinedPhrases" } }, "phrases": { "type": "array", "description": "The transcription results segmented into phrases.", "items": { "$ref": "#/definitions/TranscribedPhrase" } } }, "required": [ "durationMilliseconds", "combinedPhrases", "phrases" ] } }, "parameters": { "Azure.Core.Foundations.ApiVersionParameter": { "name": "api-version", "in": "query", "description": "The API version to use for this operation.", "required": true, "type": "string", "minLength": 1, "x-ms-parameter-location": "method", "x-ms-client-name": "apiVersion" } } }