docs: add OpenAI API smoke test quickstart

Merge pull request #2864 from codex/api-quickstart-20k

README.md

@@ -177,14 +177,26 @@ result = model.generate(input="audio.wav", granularity="utterance")
 ```bash
 # OpenAI-compatible API (recommended)
 pip install funasr fastapi uvicorn python-multipart
-funasr-server --device cuda
+funasr-server --model sensevoice --device cuda
 # → POST /v1/audio/transcriptions at localhost:8000
+```
 
+Verify it with a public sample:
+
+```bash
+curl -L https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav
+curl http://localhost:8000/v1/audio/transcriptions \
+  -F file=@sample.wav \
+  -F model=sensevoice \
+  -F response_format=verbose_json
+```
+
+```bash
 # Docker streaming service
 docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12
 ```
 
-[Deployment docs →](./runtime/readme.md) · [Agent integration →](https://modelscope.github.io/FunASR/agent.html)
+[OpenAI API example →](./examples/openai_api/) · [Deployment docs →](./runtime/readme.md) · [Agent integration →](https://modelscope.github.io/FunASR/agent.html)
 
 ---
 

README_zh.md

@@ -176,14 +176,26 @@ result = model.generate(input="audio.wav", granularity="utterance")
 ```bash
 # OpenAI 兼容 API（推荐）
 pip install funasr fastapi uvicorn python-multipart
-funasr-server --device cuda
+funasr-server --model sensevoice --device cuda
 # → POST /v1/audio/transcriptions，地址 localhost:8000
+```
 
+使用公开样例音频验证服务：
+
+```bash
+curl -L https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav
+curl http://localhost:8000/v1/audio/transcriptions \
+  -F file=@sample.wav \
+  -F model=sensevoice \
+  -F response_format=verbose_json
+```
+
+```bash
 # Docker 流式服务
 docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12
 ```
 
-[部署文档 →](./runtime/readme_cn.md) · [Agent 集成 →](https://modelscope.github.io/FunASR/agent.html)
+[OpenAI API 示例 →](./examples/openai_api/) · [部署文档 →](./runtime/readme_cn.md) · [Agent 集成 →](https://modelscope.github.io/FunASR/agent.html)
 
 ---
 

examples/openai_api/README.md

@@ -11,6 +11,25 @@ python server.py --model sensevoice --device cuda --port 8000
 
 Server starts in ~20s (model loading). Health check: `GET /health`
 
+### End-to-end smoke test
+
+In another terminal, download a public sample and verify both health and transcription:
+
+```bash
+bash smoke_test.sh
+```
+
+Equivalent manual commands:
+
+```bash
+curl -L https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav
+curl http://localhost:8000/health
+curl http://localhost:8000/v1/audio/transcriptions \
+  -F file=@sample.wav \
+  -F model=sensevoice \
+  -F response_format=verbose_json
+```
+
 ## Usage with OpenAI SDK (Python)
 
 ```python
@@ -102,3 +121,9 @@ docker run --gpus all -p 8000:8000 funasr-api
 | `--port` | 8000 | Port |
 | `--device` | cuda | Device (cuda/cpu/mps) |
 | `--model` | sensevoice | Pre-load model at startup |
+
+## Troubleshooting
+
+- If CUDA is unavailable, use `--device cpu` for a slower but simple smoke test.
+- If port 8000 is occupied, start with `--port 9000` and run `BASE_URL=http://localhost:9000 bash smoke_test.sh`.
+- If model download is slow, retry with a stable network or pre-download the model from ModelScope/Hugging Face.

examples/openai_api/smoke_test.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASE_URL="${BASE_URL:-http://localhost:8000}"
+MODEL="${MODEL:-sensevoice}"
+RESPONSE_FORMAT="${RESPONSE_FORMAT:-verbose_json}"
+AUDIO_PATH="${1:-sample.wav}"
+SAMPLE_URL="${SAMPLE_URL:-https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav}"
+
+if [ ! -f "$AUDIO_PATH" ]; then
+  echo "Downloading sample audio to $AUDIO_PATH"
+  curl -L "$SAMPLE_URL" -o "$AUDIO_PATH"
+fi
+
+echo "Checking $BASE_URL/health"
+curl -fsS "$BASE_URL/health"
+printf '\n\n'
+
+echo "Transcribing $AUDIO_PATH with model=$MODEL"
+curl -fsS "$BASE_URL/v1/audio/transcriptions" \
+  -F "file=@${AUDIO_PATH}" \
+  -F "model=${MODEL}" \
+  -F "response_format=${RESPONSE_FORMAT}"
+printf '\n'