In-app API docs for /audio-to-text drift from implementation: format list, size limit, unreachable error codes
- Dominant language
- TypeScript
- Stars
- 156k
- Forks
- 24.6k
- Avg merge
- 22h 9m
- Merged PRs (30d)
- 610
Description
### Self Checks
- [x] I have read the [Contributing Guide](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md) and [Language Policy](https://github.com/langgenius/dify/issues/1542).
- [x] This is only for bug report, if you would like to ask a question, please head to [Discussions](https://github.com/langgenius/dify/discussions/categories/general).
- [x] I have searched for existing issues [search for existing issues](https://github.com/langgenius/dify/issues), including closed ones.
- [x] I confirm that I am using English to submit this report, otherwise it will be closed.
- [x] 【中文用户 & Non English User】请使用英语提交,否则会被关闭 :)
- [x] Please do not modify this template :) and fill in all the required fields.
### Dify version
main (`dc8dd09450`); also present in 1.16.1 and earlier
### Cloud or Self Hosted
Cloud and Self Hosted (the drift is in the shipped code, so it affects every deployment)
### Steps to reproduce
1. Open any Chat/Chatflow app → **API Access** → the *Audio to text* section (rendered from `web/app/components/develop/template/template_chat.*.mdx` / `template_advanced_chat.*.mdx`, en/ja/zh).
2. Compare with the implementation:
- `api/constants/__init__.py` L12: `_AUDIO_EXTENSION_BASE = ("mp3", "m4a", "wav", "amr", "mpga")`
- `api/services/audio_service.py` L31–32: `FILE_SIZE = 30` (MB)
3. Read the `/audio-to-text` OpenAPI docstring in `api/controllers/service_api/app/audio.py` (both `@service_api_ns.doc` response blocks, ~L58 and ~L158) and trace the listed 400 codes to their raise sites.
### ✔️ Expected Behavior
The in-app API docs describe what the endpoint accepts and returns:
- Supported formats: `mp3, m4a, wav, amr, mpga`; file size limit **30 MB**.
- The 400 error list contains only codes reachable via this endpoint.
### ❌ Actual Behavior
Three documentation surfaces disagree with the implementation:
1. **Format list** — the in-app templates say `['mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'wav', 'webm']`. `mp4`, `mpeg` and `webm` are rejected with `unsupported_audio_type` (415); `amr` is accepted but undocumented.
2. **Size limit** — the templates say **15MB**; the service accepts up to **30 MB**, so valid 15–30 MB uploads look forbidden to readers.
3. **Unreachable error codes** — the controller docstring advertises `app_unavailable`, `provider_quota_exceeded` and `model_currently_not_support` for 400 responses, but no code path reachable from `/audio-to-text` raises the mapped exceptions: `AppModelConfigBrokenError` is raised only in `message_based_app_generator`, and `QuotaExceededError` / `ModelCurrentlyNotSupportError` only in the easy-UI model-config converter and `llm/quota`. `AudioService._invoke_speech_to_text` raises none of them. (The reference docs at docs.dify.ai were corrected in langgenius/dify-docs#903; this issue is for the two in-repo surfaces.)
Affected files: `web/app/components/develop/template/template_chat.{en,ja,zh}.mdx`, `template_advanced_chat.{en,ja,zh}.mdx`, `api/controllers/service_api/app/audio.py`.
Contributor guide
Research direction
Read api/constants/__init__.py and api/services/audio_service.py for accepted formats and FILE_SIZE, then compare them with web/app/components/develop/template/template_chat.{en,ja,zh}.mdx and template_advanced_chat.{en,ja,zh}.mdx. Inspect the two /audio-to-text response blocks in api/controllers/service_api/app/audio.py and trace the listed error codes to their raise sites. Done means both in-repo documentation surfaces match the reachable endpoint behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, typescript
- Domain
- api, backend, documentation, frontend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 76/100