API 介面概覽與鑑權機制
OneASR 提供了一套標準化、高效能的 REST 與 WebSocket 介面體系，涵蓋通用語音轉錄、即時串流辨識、非同步任務管理與媒體處理。
服務基礎位址 (Base URL)
- 本機單機環境：
http://localhost:8000 - OpenAI 相容端點：
http://localhost:8000/v1 - 即時 WebSocket 端點：
ws://localhost:8000/v1/realtime（或/v1/realtimeext）
身分鑑權方式
所有存取 OneASR 閘道的請求均需透過 API Key 進行鑑權（在 config.yaml 中設定 api_key: sk-oneasr-...）。
支援以下三種憑證傳遞方式：
1. HTTP 請求標頭 Bearer Token（標準 OpenAI 格式）
http
Authorization: Bearer sk-oneasr-v1-p_L3kXm9QZ8sT2vA4wE7rY1u2. 自訂請求標頭 (X-API-Key)
http
X-API-Key: sk-oneasr-v1-p_L3kXm9QZ8sT2vA4wE7rY1u3. URL Query 參數（適用於 WebSocket 建立信號交握）
text
ws://localhost:8000/v1/realtime?api_key=sk-oneasr-v1-p_L3kXm9QZ8sT2vA4wE7rY1u核心 API 功能分組
| 分組模組 | 涵蓋端點 | 通訊協定 | 說明 |
|---|---|---|---|
| OpenAI 相容 | /v1/audio/transcriptions, /v1/models | HTTP REST | 零修改平替 OpenAI 語音轉錄與模型探索 |
| 即時串流傳輸 | /v1/realtime, /v1/realtimeext | WebSocket | < 160ms 區塊級即時雙工音訊串流辨識 |
| 非同步檔案轉錄 | /v1/file-transcription/transcriptions | HTTP & SSE | 超長影音（≤2GB）後台非同步任務與進度推播 |
| 檔案儲存管理 | /v1/files/*, /v1/files/fetch-url | HTTP REST | 音訊上傳管理與網路影音直連非同步擷取 |
| 媒體與引擎監控 | /v1/media/parse, /v1/providers | HTTP REST | 媒體音軌擷取與 ASR 引擎執行狀態查詢 |