langgenius / langgenius/dify

In-app API docs for /audio-to-text drift from implementation: format list, size limit, unreachable error codes

Open
#39,928 2 comments 1 reaction 0 assignees View on GitHub
🐞 bug project#dify
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.