FTIR.funFTIR.fun
開發者與AI整合

將FTIR.fun連接到任何AI工具或應用程式

讓您的 AI 助手或您自行撰寫的程式碼直接存取 320,000+ 個參考光譜、知識圖譜峰值推理，以及以文獻為依據的解讀。選擇三種連接方式之一——適用於 AI 助手的 MCP、適用於程式碼的 REST API，或適用於無程式碼平台的現成 Skill。以下每種方式都提供為首次使用者撰寫的逐步操作說明。

1. 選擇您的路徑 2. MCP 設定 3. REST API 4. 技能與外掛 5. 你的 AI 能做什麼 6. 疑難排解
列出於

開始前 — 取得你的 API 金鑰

MCP 與 REST API 均使用同一個 FTIR.fun API 金鑰。Coze/Doubao 使用由外掛發布者設定的服務金鑰，因此終端使用者可透過外掛操作，而無需貼上個人金鑰。取得個人金鑰約需一分鐘：

  1. 登入 FTIR.fun 建立免費帳戶（新帳戶包含免費試用點數）。
  2. 開啟 API 金鑰儀表板 前往 帳戶 → API 金鑰 然後點擊「產生」。
  3. 檢視或複製您的 API 金鑰 完整金鑰（以 ftir_ 開頭）仍可在 API Keys 儀表板中取得。您可以返回該處檢視、複製或撤銷它。
🔑 準備好了？ 打開 API Keys 儀表板 在新分頁中，然後回來按照您上面選擇的路徑操作。

步驟 1 — 哪種連線適合你？

三者都連接至相同的引擎：320,000+ 個光譜、知識圖譜推理，以及文獻引用。您只需要選擇一種。請選擇符合您工作方式的路徑；對 AI 助理使用者而言，MCP 是一個便利的選項。

您的 AI 實際上能做什麼

統一的 MCP 與 REST 服務公開相同的 FTIR.fun 操作目錄。API 金鑰可能僅具較小的功能範圍，而平台特定的宣告則可刻意僅發布其中一部分。以下操作共用相同的 FTIR.fun 服務。

任務 MCP 工具 REST 端點 對您的 AI 說這句話
讀取儀器檔案 parse_ftir_spectrum POST /parse-spectrum 解析 sample.spc 並列出檢測到的峰。
轉換原生資料並保存元資料 convert_native_spectrum POST /native-spectrum/convert 將 sample.spa 轉換為 JDX 並保留源元數據。
識別未知光譜 analyze_ftir_spectrum POST /ftir/analyze_spectrum 識別此光譜為何種聚合物。
提交完整的三軸報告 submit_ftir_report POST /ftir/reports 提交 sample.spa 以在 ATR 模式下獲得完整報告。
輪詢並檢索該報告 get_ftir_report_status GET /ftir/reports/{task_id} 檢查報告任務，完成後給我連結。
解釋譜峰 explain_peaks POST /ftir/explain_peak_assignments 1715 和 1450 cm-1 處的譜峰表示什麼？
尋找已知參考光譜 find_spectra POST /ftir/find_spectra 查找聚苯乙烯的參考光譜。
重新開啟先前的結果 fetch_result GET /ftir/result/{result_num} 獲取結果 20260528100755416137536。
🎓 學術峰歸屬 — 对于组成已知的样品，高级 FTIR.fun REST/MCP 功能会为每个测得的峰分配文献可追溯的证据。每次提交费用为 30 点数；拥有有效订阅时则免费；状态查询不收费。 自然地描述任務（例如：「為此光譜指定所有量測到的 FTIR 峰值；樣品已知為 PMMA；將報告寄給我」）——用戶端會提供檔案，您無需自行建構 JSON 或 Base64。完成後的結果會同時回傳 JSON 狀態和受保護的報告位址；報告不會在公開下載路徑上公開。

支援的光譜檔案副檔名（36）：.spa, .spc, .sp, .abs, .irf, .irs, .dt, .jws, .jdx, .dx, .asc, .dpt, .opju, .opus, .ispd, .[0-9]+, .xlsx, .xls, .ods, .csv, .dat, .txt, .tsv, .json, .tab, .a2r, .asp, .spe, .map, .bsp, .spg, .srs, .smf, .ird, .fsm, .mat。請保留原始檔案副檔名。不支援或無法讀取的檔案會回傳supported_extensions和supported_formats。有效的sampling_mode值為KBr Pellet、Vapor、Solvent、Thin Film、Paraffin Mull、ATR、Diffuse Reflectance、Micro IR和Others。Transmission不是有效值。

find_spectra 回應範例

find_spectra 回應 
{
  "success": true,
  "query": "polystyrene",
  "match_mode": "synonym",
  "match_count": 3,
  "summary": "Found 3 reference spectrum candidates for 'polystyrene'.",
  "results": [
    {"num": 555, "spectrum_number": 555, "name": "PS/PPO",
     "cas": "-", "source_type": "instrument_import",
     "peaks": [697, 756, 1028, ...], "x": [...], "y": [...]}
  ]
}

explain_peaks 回應範例

explain_peaks 回應 
{
  "success": true,
  "search_mode": "peak_explanation",
  "peak_explanations": [
    {"peaks_cm1": [1715, 1450],
     "assignment": "1715 cm-1 suggests C=O stretching (ester or carboxylic acid)...",
     "evidence_type": "llm_general_knowledge"}
  ],
  "summary": "Peak explanation based on general FTIR knowledge..."
}

獲取完整報告（非同步）

快速篩選（analyze_spectrum）會立即返回結果。完整的三軸報告會在背景執行，通常需要 30–90 秒。請保留 task_id 並輪詢它，不要重新提交。

  1. 提交 呼叫 submit_ftir_report (MCP) 或 POST /ftir/reports (REST)。您會收到一個 task_id 和一個保留的 result_num。file_base64 欄位是必需的；其他欄位（sampling_mode、prior_context、language_code、sample_name、sample_order_no）是可選的。
    提交範例（REST） 
    curl -X POST https://ftir.fun/ftir/reports \
  -H "X-API-Key: ftir_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"file_base64": "V2F2ZW51bWJlci...", "filename": "sample.spa", "sampling_mode": "ATR", "language_code": "en"}'
    提交回應 
    {"success": true, "task_id": "rpt_abc123...", "result_num": "20260713...",
 "status": "queued", "status_url": "https://ftir.fun/ftir/reports/rpt_abc123..."}
  2. 輪詢 每 5–10 秒呼叫一次 get_ftir_report_status (MCP) 或 GET /ftir/reports/{task_id}，直到 completed 為 true。完成後的回應包含 report_url、一個 report 物件（結構化結果內容，其中包含詳細的 report_view）以及 result_num。
    輪詢範例 
    curl https://ftir.fun/ftir/reports/rpt_abc123 \
  -H "X-API-Key: ftir_your_key_here"
    輪詢回應（進行中） 
    {"success": true, "task_id": "rpt_abc123", "status": "running", "progress": 45, "completed": false}
    輪詢回應（已完成） 
    {"success": true, "task_id": "rpt_abc123", "status": "completed", "completed": true,
 "result_num": "20260713...", "report_url": "https://ftir.fun/outputdata/?num=20260713..."}
  3. 開啟最終報告 在瀏覽器中開啟完整 URL https://ftir.fun/outputdata/?num={result_num} 以檢視由 FTIR.fun 渲染的完整三軸結果頁面。
⚠️ task_idを保持し、完了または失敗するまでポーリングしてください。キュー待ちまたは実行中に重複送信すると、ポイントが無駄になります。

疑難排解

您看到的內容 其含義 該怎麼做
用戶端開啟瀏覽器授權頁面，或顯示授權頁面不存在。 您的用戶端使用舊的 OAuth 風格伺服器條目。FTIR.fun 不使用 OAuth — 僅使用 API 金鑰。 刪除舊的 ftirfun 伺服器條目，從此頁面貼上確切的配置，重新載入用戶端，然後重新啟動 ftirfun。
401 (MCP) / 401 invalid_api_key (REST) API 金鑰遺失、過期、被撤銷或貼上不正確。 重新啟動伺服器並僅貼上原始金鑰（以 ftir_ 開頭）。 從 API 金鑰儀表板 如有需要。
伺服器啟動但沒有工具出現。 用戶端尚未重新整理其目錄，或配置使用了錯誤的金鑰名稱。 對於 VS Code，確認 mcp.json 使用 servers（而非 mcpServers）。然後停止並重新啟動 ftirfun，或重新載入視窗。
403 insufficient_balance 該帳戶沒有足夠的點數進行該分析。 請在 FTIR.fun 檢查您的餘額或訂閱，然後重試。
429 rate_limit_exceeded REST 分析和解析允許每個 API 金鑰每分鐘 60 次請求；REST 結果和報告狀態讀取使用單獨的每分鐘 120 次請求儲存桶；MCP 允許每個 API 金鑰和工具每分鐘 60 次呼叫。 請等待工具報告的重試時間後再重新呼叫。
報告保持在佇列中或正在執行。 完整報告是非同步執行的，且比快速篩選需要更長時間。 保留相同的 task_id 並進行輪詢。若遺失 task_id，請呼叫 GET /ftir/tasks 列出您最近的任務，並再次找到它。
422 或 missing_input 請求體缺少必要欄位或格式無效。對於 analyze_spectrum，您必須提供至少以下一項：peaks、query 或 file_base64。 請檢查您的 JSON 是否有效、Content-Type 是否為 application/json，以及必要欄位是否存在。請參閱上面的範例請求。
413 file_too_large 上傳的光譜檔案超過大小限制。 匯出較小的檔案或僅透過 spectrum.peaks 欄位使用峰值位置。

準備好建立了嗎？

完整的 REST 參考包含每個端點、請求和回應格式、驗證、速率限制、錯誤代碼、MCP 工具定義，以及 Python 和 curl 的程式碼範例。

提交需求 表單