Audio to Text API (/audio-to-text)#
POST /audio-to-text converts an uploaded audio file to text using the app's configured speech-to-text model. The endpoint is registered on the service API router and requires Bearer token authentication via the standard Dify API key.
Request#
Multipart/form-data with two fields :
| Field | Type | Required | Description |
|---|---|---|---|
file | File | Yes | Audio file to transcribe |
user | string | Yes | End-user identifier (unique per app) |
Supported Formats and Size Limit#
Validation happens in AudioService._invoke_speech_to_text. The file's Content-Type must match one of the MIME types derived from the AUDIO_EXTENSIONS constant β currently mp3, m4a, wav, amr, mpga .
Before validation, the MIME type is normalized using _ASR_MIME_TYPE_ALIASES. Currently audio/x-m4a is mapped to audio/m4a; this alias is commonly used by iOS and React Native applications for .m4a recordings. After normalization, the MIME check is audio/{ext} for each entry in AUDIO_EXTENSIONS .
The file size limit is 30 MB, enforced by comparing the raw byte length against FILE_SIZE_LIMIT = 30 * 1024 * 1024 .
Format discrepancy β read before adding new formats. PR #31381 (open as of 2026-08-03) proposes adding
webm,mp4, andmpegtoAUDIO_EXTENSIONS. PR #23287 previously adjusted the extension set to align with the web UI, which is whenwebmwas moved from audio to video andmpgawas added .
Response#
{ "text": "<transcribed string>" }
Returned as AudioTranscriptResponse .
Error Codes#
| HTTP | Code | Cause |
|---|---|---|
| 400 | app_unavailable | App config broken |
| 400 | speech_to_text_disabled | STT not enabled for this app |
| 400 | provider_not_support_speech_to_text | Provider lacks STT capability |
| 400 | provider_not_initialize | No valid provider credentials |
| 400 | provider_quota_exceeded | Quota exhausted |
| 400 | model_currently_not_support | Model doesn't support this operation |
| 400 | completion_request_error | Recognition request failed |
| 413 | audio_too_large | File exceeds 30 MB |
| 415 | unsupported_audio_type | MIME type not in AUDIO_EXTENSIONS (after normalization) |
| 500 | internal_server_error | Unhandled exception |
Service Layer#
AudioService.transcript_asr dispatches based on app mode before reaching the shared _invoke_speech_to_text method:
- Agent apps β checks the published Agent Soul's merged feature projection .
- Advanced Chat / Workflow apps β reads
speech_to_text.enabledfrom the workflow's features dict . - All other apps β reads
speech_to_text_dict["enabled"]fromAppModelConfig.
All paths raise SpeechToTextDisabledServiceError if the feature is off, which the controller maps to HTTP 400 speech_to_text_disabled .
Key Source Files#
| File | Role |
|---|---|
api/controllers/service_api/app/audio.py | Route definition, error mapping |
api/services/audio_service.py | Business logic, format/size validation |
api/constants/__init__.py | AUDIO_EXTENSIONS constant |