API 文檔

居家護理 AI 輔助系統 v2026.07.15-2

REST API 規格摘要

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

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

1. POST 端到端產生 ai-draft.json

Path/api/v1/ai-draft
Content-Typemultipart/form-data
audio_file（必填）錄音檔。可用同名欄位重複上傳多段音檔，副檔名：.mp3 .wav .m4a .webm .ogg，每個檔案後端應用層上限 50 MB。
meta_file（必填）錄音檔 meta.json 或個案 JSON。若含 patient_name、caseName 或 base_data.caseName，糾錯階段會以 AI 保守修正病患姓名誤聽；日期參考時間依序採 started_at_epoch_ms、ended_at_epoch_ms、uploaded_at_epoch_ms。
history_file（必填）單一 history.json。端點會和本次逐字稿融合產生歷史輔助提示、照護計畫評值；若包含 body_assessment_snapshots，本次未評估但 baseline 有值的身評欄位會以 source: carried 沿用。
stt_model / llm_model（選填）模型 ID；留空使用後端預設。
exclude_visit_date（選填）YYYY-MM-DD，排除 history 文字內指定日期訪視內容。

回應

檔名回應 header 會帶 Content-Disposition: attachment; filename="ai-draft.json"
schema_version固定回 ai_output_contract_v1
visit_info / body / vital_signs依 contract v1 輸出三態葉節點：value / this_visit / source，必要時含 snippet / confidence / multiple_values
care_plan_evaluations照護計畫評值建議；plan_id 僅能來自本次 history 的候選計畫，配不到則為 null。confidence 為 0.0-0.95 的校準分數，會依 plan match 方法、score 與評值證據調整，不再以 1.0/0.0 二元表示。
narrative_for_mohw單一字串的訪視摘要 seed，可供護理師校稿後寫入
suggested_visit_date固定回傳完整 YYYY-MM-DD。明確口述年份時以該年份為準；只有月日時，以錄音 metadata 或目前台北日期為參考，從前一年、當年、後一年選距離最近者；未提日期時使用參考日期。例如參考日 2026-07-15 時，2026 4月3號 與 4月3號 都會回傳 2026-04-03。
_soapie_reasoning固定包含 S / O / A / P / I / E 六個字串欄位。各欄優先採 history 融合後的 suggested_soapie，缺漏時回退至本次 LLM 結構化萃取的 record.soapie，兩者皆無則回空字串；屬 review metadata，不得當成正式上傳欄位。
review-aid 欄位missing_or_uncertain / suggested_record_focus / low_confidence / corrected_transcript / transcript 為 display-only，不屬於上傳資料
_identity_not_from_ai宣告身分、日期與時段實值不是由 AI 自產
_meta底線 metadata；除模型與耗時外，含 visit_date_reference_source（recording_started_at / recording_ended_at / recording_uploaded_at / current_time）及 visit_date_reference_date，消費端不得當成正式上傳欄位。
curl -X POST "http://localhost:8000/api/v1/ai-draft" \
  -F "audio_file=@part1.m4a" \
  -F "audio_file=@part2.m4a" \
  -F "meta_file=@recording.meta.json" \
  -F "history_file=@history.json" \
  -F "stt_model=gemini-3.5-flash" \
  -F "llm_model=gemini-3.5-flash" \
  -o ai-draft.json

history.json 支援欄位

plans[]照護計畫候選來源。支援標準鍵 category / problem / goal / measures / is_active，也支援匯出別名 type / item / note / goal_text / measures_table.rows / is_active: "Y"|"N"。
body_assessment_snapshots[]身評 baseline 來源。每筆 snapshot 可用 body、body_assessment、body_assessment_snapshot 或 groups 放置 14 群身評資料。
沿用規則本次逐字稿有評到的 leaf 會維持 source: visit；本次未評但 baseline 有值會輸出 source: carried、this_visit: false；兩者都沒有才輸出 not_evaluated。

2. POST 從逐字稿產生 ai-draft.json

Path/api/v1/ai-draft/from-transcript
Content-Typemultipart/form-data
transcript（必填）本次訪視逐字稿，建議使用已校稿或 STT 糾錯後全文。
history_file（必填）單一 history.json。支援欄位同上：plans[] 作為照護計畫候選，body_assessment_snapshots[] 作為身評 baseline 沿用來源。
llm_model（選填）LLM 模型 ID；留空使用後端預設。
exclude_visit_date（選填）YYYY-MM-DD，排除 history 文字內指定日期訪視內容。

回應

回應格式與 /api/v1/ai-draft 相同，固定為 schema_version: ai_output_contract_v1。此端點只跳過錄音檔上傳、STT 與姓名糾錯，仍會執行 LLM 結構化與 history 融合。由於沒有錄音 metadata，日期補年或未提日期時會使用請求開始當下的台北日期，並在 _meta.visit_date_reference_source 回傳 current_time。

curl -X POST "http://localhost:8000/api/v1/ai-draft/from-transcript" \
  -F "transcript=本次訪視逐字稿內容..." \
  -F "history_file=@history.json" \
  -F "llm_model=gemini-3.5-flash" \
  -o ai-draft.json

3. POST 一鍵分析護理語音

Path/api/v1/nursing-record/analyze
Content-Typemultipart/form-data
audio_file（必填）音檔。副檔名：.mp3 .wav .m4a .webm .ogg，後端應用層上限 50 MB。
meta_file（選填）錄音同名 .meta.json 或個案 JSON。若含 patient_name、caseName 或 base_data.caseName，糾錯階段會以 AI 保守修正病患姓名誤聽；例如 洪秋菊 / 純換管 會取主要姓名 洪秋菊。日期參考時間依序採 started_at_epoch_ms、ended_at_epoch_ms、uploaded_at_epoch_ms，皆無時使用目前台北時間。
stt_model（選填）STT 模型 ID，如 gemini-3.5-flash、gemini-2.5-flash；留空使用預設 gemini-3.5-flash。
llm_model（選填）LLM 模型 ID，如 gemini-3.5-flash、gemini-2.5-flash、gemma-4-26b-a4b-it、gemma-4-31b-it、gemma-4-12b；留空使用預設 gemini-3.5-flash。其中 gemma-4-12b 走專案內文檔對應的 Public API（OpenAI-compatible Chat Completions）。

回應欄位

visit_info / modules / soapie結構化護理紀錄
warnings / changes / low_confidence字串陣列
transcriptSTT 原始逐字稿；後端會統一正規化為繁體中文
visit_info訪視資訊；含 date / visit_start_time / visit_end_time。date 固定為完整 YYYY-MM-DD：明確年份以逐字稿為準，只有月日時依參考日取距離最近年份，未提日期則使用參考日。
corrected_transcript醫療字典糾錯後全文；無實際糾錯時為 null
correction_segments高亮分段：plain / replaced
corrections替換項目：from, to, span, reason，並保留相容欄位 original, corrected, count
schema_version目前為 2.2
body_assessment / vital_signsv2.2 structured scaffold，每個 sub-field 含 value / evaluated / source_snippet；R7 12 題 body enum 已正規化，multi 欄位另含 multiple_values
missing_or_uncertain與舊 warnings 同步，供後續統一命名
_meta效能資訊與日期參考：stt_model, stt_elapsed_ms, correction_status, correction_elapsed_ms, llm_model, llm_elapsed_ms, total_elapsed_ms, audio_duration_sec, enum_normalization, visit_date_reference_source, visit_date_reference_date
curl -X POST "http://localhost:8000/api/v1/nursing-record/analyze" \
  -F "audio_file=@sample.wav" \
  -F "meta_file=@sample.meta.json" \
  -F "stt_model=gemini-3.5-flash" \
  -F "llm_model=gemini-3.5-flash"

4. POST 語音轉文字 (STT)

Path/api/v1/stt/transcribe
Content-Typemultipart/form-data
audio_file（必填）音檔。可用同名欄位重複上傳多段音檔，副檔名：.mp3 .wav .m4a .webm .ogg；後端應用層上限 50 MB。
model（選填）STT 模型 ID；可用 gemini-3.5-flash、gemini-3-flash-preview、gemini-2.5-flash、gemini-2.5-flash-lite、gemini-2.5-pro

回應

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-3.5-flash"

4. POST 醫療名詞糾錯

Path/api/v1/correction/apply
Content-Typeapplication/json
Bodytext 必填；後端會先套用本地醫療字典，再用 AI 保守修正明顯錯字、STT 誤聽與醫學專有名詞。patient_name 或 meta 選填；若兩者都提供，優先使用 patient_name。meta 是 request body 裡的 JSON object，可放 patient_name、caseName、base_data.caseName、patient.name 等姓名欄位。

Body 欄位

text必填。原始 STT 逐字稿。
patient_name選填。正確病患姓名；例如 廖振景。若含 /、／、| 或括號備註，後端會取主要姓名。
meta選填。JSON object，不是檔案上傳。可直接放個案 meta，後端會依序尋找 patient_name、caseName、base_data.caseName、patient.name 等欄位。
model選填。AI 醫療校稿與姓名糾錯使用的 LLM 模型 ID；留空使用後端預設。

回應

corrected_text糾錯後全文
corrections替換項目陣列，每筆含 from / to / span / reason
correction_segments高亮分段
ai_text_correctionAI 醫療逐字稿校稿狀態、使用模型、修正數量與錯誤訊息；AI 失敗時不阻斷本地字典糾錯。
patient_name_correction若有提供姓名，回傳姓名糾錯狀態、主要姓名、模型與修正數量；AI 失敗時不阻斷本地醫療字典糾錯。
elapsed_ms耗時毫秒
curl -X POST "http://localhost:8000/api/v1/correction/apply" \
  -H "Content-Type: application/json" \
  -d '{"text":"個案廖曾謹，訪視日期是6月3號。","patient_name":"廖振景","model":"gemini-3.5-flash"}'

若姓名在個案 JSON 裡，請把它放在 body 的 meta 欄位：

curl -X POST "http://localhost:8000/api/v1/correction/apply" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "個案廖曾謹，訪視日期是6月3號。",
    "meta": {
      "base_data": {
        "caseName": "廖振景",
        "caseID": "P201600198"
      }
    },
    "model": "gemini-3.5-flash"
  }'

5. 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-3.5-flash"}'

6. POST 歷史紀錄輔助提示

Path/api/v1/history/brief
Content-Typemultipart/form-data
history_files（必填，可多檔）病患歷史紀錄。支援 .html .htm .txt .md .json .csv .dat
transcript（必填）本次 STT 逐字稿，建議使用糾錯後全文
model（選填）LLM 模型 ID；留空使用預設
exclude_visit_date（選填）YYYY-MM-DD，從歷史 HTML 排除該日期訪視卡片，避免融合本次紀錄

回應

insight.patient_baseline歷史可沿用的個案基線
insight.current_visit_updates本次逐字稿提到的新狀況與處置
insight.changes_from_history相較歷史紀錄的變化
insight.suggested_record_focus本次紀錄建議補入的條列重點
insight.care_plan_evaluations依歷史照護計畫分類、目標與措施，自動產生本次評值建議；每筆含 plan_id / plan_status / plan_match / evaluated / source_snippet
insight.missing_or_uncertain需人工確認的缺漏、矛盾或低信心資訊
insight.risk_alerts風險提醒
insight.suggested_soapieSOAPIE 草稿
insight.suggested_soapie_summarySOAPIE 草稿整合後的一段式敘述摘要，600 字內
schema_version / _metav2.2 schema 標記、歷史過濾狀態、候選照護計畫數、模型與耗時
history_files / input_chars解析檔案與輸入字數資訊
curl -X POST "http://localhost:8000/api/v1/history/brief" \
  -F "history_files=@P201715443.html" \
  -F "transcript=今日訪視個案..." \
  -F "model=gemini-3.5-flash" \
  -F "exclude_visit_date=2026-05-11"

7. 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.5-flash"}'

8. 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"}'

9. 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"

10. 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 試打為準。