Create transcription
Creates a new transcription.
Headers
AuthorizationRequiredBearer <SONIOX_API_KEY>Request
application/jsonRequiredmodelRequiredstringSpeech-to-text model to use for the transcription.
32audio_urlstringURL of the audio file to transcribe. Cannot be specified if file_id is specified.
4096Pattern: "^https?://[^\\s]+$"file_idstringID of the uploaded file to transcribe. Cannot be specified if audio_url is specified.
"uuid"language_hintsarray<string>Expected languages in the audio. If not specified, languages are automatically detected.
enable_speaker_diarizationbooleanWhen true, speakers are identified and separated in the transcription output.
enable_language_identificationbooleanWhen true, language is detected for each part of the transcription.
translationobjectTranslation configuration.
contextAny properties in object,stringAdditional context to improve transcription accuracy and formatting of specialized terms.
webhook_urlstringURL to receive webhook notifications when transcription is completed or fails.
256Pattern: "^https?://[^\\s]+$"webhook_auth_header_namestringName of the authentication header sent with webhook notifications.
256webhook_auth_header_valuestringAuthentication header value sent with webhook notifications.
256client_reference_idstringOptional tracking identifier string. Does not need to be unique.
256Response
201
Created transcription.
idRequiredstringUnique identifier for the transcription request.
"uuid"statusRequiredstringTranscription status.
"queued" | "processing" | "completed" | "error"created_atRequiredstringUTC timestamp indicating when the transcription was created.
"date-time"modelRequiredstringSpeech-to-text model used for the transcription.
audio_urlstringURL of the file being transcribed.
file_idstringID of the file being transcribed.
"uuid"filenameRequiredstringName of the file being transcribed.
language_hintsarray<string>Expected languages in the audio. If not specified, languages are automatically detected.
enable_speaker_diarizationRequiredbooleanWhen true, speakers are identified and separated in the transcription output.
enable_language_identificationRequiredbooleanWhen true, language is detected for each part of the transcription.
audio_duration_msintegerDuration of the audio in milliseconds. Only available after processing begins.
error_typestringError type if transcription failed. null for successful or in-progress transcriptions.
error_messagestringError message if transcription failed. null for successful or in-progress transcriptions.
webhook_urlstringURL to receive webhook notifications when transcription is completed or fails.
webhook_auth_header_namestringName of the authentication header sent with webhook notifications.
webhook_auth_header_valuestringAuthentication header value. Always returned masked as ******************.
webhook_status_codeintegerHTTP status code received from your server when webhook was delivered. null if not yet sent.
client_reference_idstringTracking identifier string.
Errors
Created transcription.
{
"id": "73d4357d-cad2-4338-a60d-ec6f2044f721",
"status": "queued",
"created_at": "2024-11-26T00:00:00Z",
"model": "stt-async-preview",
"audio_url": "https://soniox.com/media/examples/coffee_shop.mp3",
"file_id": null,
"filename": "coffee_shop.mp3",
"language_hints": [
"en",
"fr"
],
"context": "extra context for the transcription",
"audio_duration_ms": 0,
"error_message": null,
"webhook_url": "https://example.com/webhook",
"webhook_auth_header_name": "Authorization",
"webhook_auth_header_value": "******************",
"webhook_status_code": null,
"client_reference_id": "some_internal_id"
}Invalid request.
Error types:
invalid_request: Invalid request.
{
"status_code": 400,
"error_type": "invalid_request",
"message": "Invalid request.",
"validation_errors": [
{
"error_type": "value_error",
"location": "body.payload.model",
"message": "Invalid model"
}
],
"request_id": "3d37a3bd-5078-47ee-a369-b204e3bbedda"
}Authentication error.
{
"status_code": 401,
"error_type": "unauthenticated",
"message": "Incorrect API key provided. You can get an API key at https://console.soniox.com",
"validation_errors": [],
"request_id": "3d37a3bd-5078-47ee-a369-b204e3bbedda"
}Internal server error.
{
"status_code": 500,
"error_type": "internal_error",
"message": "The server encountered an error. Please try again. If the issue persists contact support@soniox.com.",
"validation_errors": [],
"request_id": "3d37a3bd-5078-47ee-a369-b204e3bbedda"
}