[fer-marino]

Adds ApiAsrOptions: the ASR and video pipelines can send the audio to an OpenAI-compatible /v1/audio/transcriptions endpoint instead of running Whisper in the Docling process.

What changes

• pipeline_options_asr_model.py: ApiAsrOptions (url, headers, model, language, initial_prompt, word_timestamps, params, timeout).
• pipeline_options.py: AsrPipelineOptions.asr_options and VideoPipelineOptions.asr_options also accept it.
• asr_transcriber.py: _ApiAsrModel posts the file and parses verbose_json into the same conversation items the inline models produce. _AsrModelFactory.create takes enable_remote_services and refuses the API backend without it (OperationNotAllowed), like the API picture description.
• asr_pipeline.py, video_pipeline.py: pass enable_remote_services to the factory.
• docs/usage/processing_audio_media.md: new section "Transcribing with a remote Whisper server".
• tests/test_asr_api.py: 12 tests with a stand-in HTTP server (no model download, so not marked ml_asr).

Behaviour

• multipart/form-data with response_format=verbose_json; model, language and prompt are sent only when set; timestamp_granularities[] is segment and word with word_timestamps=True; params are extra form fields (response_format cannot be overridden).
• Words are taken from the segments or, as OpenAI returns them, from the top-level list (each word goes to the segment it starts in).
• A non-2xx answer, a body that is not JSON, or an answer without segments fails the conversion with an ErrorItem that says why.
• FFmpeg is not required for audio files with this backend (the video pipeline still uses it to extract the audio track).

Not included: a CLI flag (the CLI selects presets with --asr-model), speaker labels (not part of the OpenAI API), streaming, the translations endpoint. Happy to add a CLI option if wanted.

Issue resolved by this Pull Request:
Resolves #4852

Checklist:

• Documentation has been updated, if necessary.
• Examples have been added, if necessary. (A usage example is in the documentation page; no new example script.)
• Tests have been added, if necessary.

Review evidence:

• Before: AsrPipelineOptions(asr_options=...) accepts inline models only; a remote server cannot be used. After: ApiAsrOptions works with enable_remote_services=True and fails with OperationNotAllowed without it.
• pytest tests/test_asr_api.py: 12 passed. The mock-based ASR tests (test_asr_whisper_s2t.py, test_asr_mlx_whisper.py: 29 passed) and test_options.py, test_video_pipeline.py, test_video_format_routing.py show no change in results.
• ruff check and ruff format --check are clean on the changed files.
• Tried against a real faster-whisper server with tests/data/audio/sources/sample_10s.mp3: two timed segments, ConversionStatus.SUCCESS, text items with TrackSource start and end times.
• Not run: ty, the full prek hooks, and the ML tests that download models.
• Three tests fail in my environment both with and without this change (older installed dependencies than main): test_backend_docling_json.py::test_local_image_uri_is_embedded_with_enable_local_fetch, test_cli.py::test_cli_convert_remote_works_without_local_model_stack, test_cli_tools.py::test_easyocr_lang_is_forwarded_when_easyocr_is_selected.
• The commit is signed off (DCO).

[github-actions]

✅ DCO Check Passed

Thanks @fer-marino, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

🟢 Merge protection satisfied — ready to merge.

Show 1 satisfied protection

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[github-actions]

AI triage (advisory)

Checked commit dd2fb63775. The analysis read the diff only. It did not run code from this pull request.

This pull request adds ApiAsrOptions to transcribe audio through remote OpenAI-compatible HTTP endpoints in the ASR and video pipelines.

Topic labels added: enhancement, asr.

CI safety: no concern found. A maintainer must still approve CI.

1 related pull request(s) in the same code

PR	State	Signal	Assessment
#4771	open	changes the same code	related: PR #4771 adds local Transformers backend support for ASR, while this pull request adds remote API transcription support.

_{The ai:* labels are advisory. They do not approve CI and they do not add tests:full. A new push runs this check again.}

[github-actions]

AI first review (advisory): no blocker found

This review covers the full diff at dd2fb63775. It read the code and did not run it.

The PR adds a remote OpenAI-compatible ASR backend. The implementation mirrors the existing ApiVlmOptions / picture-description pattern correctly. requests is already a core dependency. No behavioral regressions are visible in the changed code. The one thing the human reviewer must confirm is that the InlineAsrOptions | ApiAsrOptions union in AsrPipelineOptions and VideoPipelineOptions deserializes correctly from JSON — the two kind Literal values differ, so Pydantic v2 auto-discriminates, but no explicit Discriminator annotation is present. The identical pattern is already used for vlm_options in the same file, so this is consistent with the repo standard.

_{A maintainer makes the merge decision. This review never approves the pull request.}

[codecov]

Codecov Report

❌ Patch coverage is 94.87179% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/pipeline/asr_transcriber.py	94.02%	2 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

[PeterStaar-IBM]

lgtm!