API 文檔

居家護理 AI 輔助系統

REST API 規格摘要

基底路徑為伺服器根目錄（例：http://localhost:8000）。所有 JSON 回應均為 application/json。

Swagger UI（互動試打） ReDoc openapi.json API 測試頁

1. POST 一鍵分析護理語音

Path/api/v1/nursing-record/analyze
Content-Typemultipart/form-data
audio_file（必填）音檔。副檔名：.mp3 .wav .m4a .webm .ogg，後端邏輯上限 50 MB；Vercel 線上版單次請求建議小於 4 MB
stt_model（選填）STT 模型 ID，如 gemini-2.5-flash；留空使用預設
llm_model（選填）LLM 模型 ID，如 gemma-4-26b-a4b-it；留空使用預設

回應欄位

visit_info / modules / soapie結構化護理紀錄
warnings / changes / low_confidence字串陣列
transcriptSTT 原始逐字稿
corrected_transcript醫療字典糾錯後全文
correction_segments高亮分段：plain / replaced
corrections替換統計：original, corrected, count
_meta效能資訊：stt_model, stt_elapsed_ms, correction_elapsed_ms, llm_model, llm_elapsed_ms, total_elapsed_ms
curl -X POST "http://localhost:8000/api/v1/nursing-record/analyze" \
  -F "audio_file=@sample.wav" \
  -F "stt_model=gemini-2.5-flash" \
  -F "llm_model=gemma-4-26b-a4b-it"

2. POST 語音轉文字 (STT)

Path/api/v1/stt/transcribe
Content-Typemultipart/form-data
audio_file（必填）音檔。可用同名欄位重複上傳多段音檔，副檔名：.mp3 .wav .m4a .webm .ogg；Vercel 線上版請讓單次請求小於 4 MB
model（選填）STT 模型 ID

回應

transcript逐字稿文字
model_used實際使用的模型 ID
elapsed_ms耗時毫秒
segments每段音檔的檔名、逐字稿、模型與耗時
curl -X POST "http://localhost:8000/api/v1/stt/transcribe" \
  -F "audio_file=@part1.m4a" \
  -F "audio_file=@part2.m4a" \
  -F "model=gemini-2.5-pro"

3. POST 醫療名詞糾錯

Path/api/v1/correction/apply
Content-Typeapplication/json
Body{ "text": "原始逐字稿" }

回應

corrected_text糾錯後全文
corrections替換統計陣列
correction_segments高亮分段
elapsed_ms耗時毫秒
curl -X POST "http://localhost:8000/api/v1/correction/apply" \
  -H "Content-Type: application/json" \
  -d '{"text":"患者恩居管已更換，血養正常"}'

4. POST LLM 結構化萃取

Path/api/v1/llm/structure
Content-Typeapplication/json
Body{ "text": "糾錯後逐字稿", "model": "(選填) 模型 ID" }

回應

record結構化護理紀錄 JSON（含 visit_info、modules、soapie、warnings 等）
model_used實際使用的模型 ID
elapsed_ms耗時毫秒
curl -X POST "http://localhost:8000/api/v1/llm/structure" \
  -H "Content-Type: application/json" \
  -d '{"text":"患者 NG tube 已更換，SpO2 正常","model":"gemini-2.5-flash"}'

5. POST 歷史紀錄輔助提示

Path/api/v1/history/brief
Content-Typemultipart/form-data
history_files（必填，可多檔）病患歷史紀錄。支援 .html .htm .txt .md .json .csv .dat
transcript（必填）本次 STT 逐字稿，建議使用糾錯後全文
model（選填）LLM 模型 ID；留空使用預設

回應

insight.patient_baseline歷史可沿用的個案基線
insight.current_visit_updates本次逐字稿提到的新狀況與處置
insight.changes_from_history相較歷史紀錄的變化
insight.suggested_record_focus本次紀錄建議補入的條列重點
insight.missing_or_uncertain需人工確認的缺漏、矛盾或低信心資訊
insight.risk_alerts風險提醒
insight.suggested_soapieSOAPIE 草稿
history_files / input_chars解析檔案與輸入字數資訊
curl -X POST "http://localhost:8000/api/v1/history/brief" \
  -F "history_files=@P201715443.html" \
  -F "transcript=今日訪視個案..." \
  -F "model=gemini-2.5-flash"

6. POST LINE 家屬訊息摘要

Path/api/v1/llm/line-family-summary
Content-Typeapplication/json
Body{ "text": "護理口述逐字稿", "model": "(選填) LLM 模型 ID" }

回應

message適合貼在 LINE 群組給家屬的繁體中文訊息本文
model_used實際使用的模型 ID
elapsed_ms耗時毫秒
curl -X POST "http://localhost:8000/api/v1/llm/line-family-summary" \
  -H "Content-Type: application/json" \
  -d '{"text":"今日訪視個案意識清楚，SpO2 95% 鼻導管 2L…","model":"gemini-3-flash-preview"}'

7. POST 家屬訊息語音合成 (TTS)

Path/api/v1/tts/line-family-speech
Content-Typeapplication/json
text（必填）要朗讀的家屬訊息全文
model（選填）TTS 模型 ID，如 gemini-2.5-flash-preview-tts；留空使用後端預設
voice_name（選填）預建語音名稱，預設 Kore
language_code（選填）預設 zh-TW

回應

audio_base64音訊二進位之標準 Base64
mime_type例如 audio/mpeg
truncated若文字過長已截斷則為 true
model_used實際使用的 TTS 模型 ID
elapsed_ms耗時毫秒
curl -X POST "http://localhost:8000/api/v1/tts/line-family-speech" \
  -H "Content-Type: application/json" \
  -d '{"text":"家屬您好，今日訪視時長輩精神穩定…","model":"gemini-2.5-flash-preview-tts"}'

8. GET 可選模型清單

Path/api/v1/system/available-models
回應stt_models、stt_default、llm_models、llm_default、tts_models、tts_default
curl "http://localhost:8000/api/v1/system/available-models"

9. GET 醫療糾錯字典

Path/api/v1/system/mapping-dictionary
回應mapping（鍵→值對照）、count
curl "http://localhost:8000/api/v1/system/mapping-dictionary"

錯誤回應

HTTP 4xx / 5xx 時，FastAPI 預設為 JSON：{"detail": "…"} 或驗證錯誤時為陣列結構。請以實際 /docs 試打為準。