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 密钥仪表板中仍然可用。您可以返回那里查看、复制或撤销它。
🔑 准备好了吗？ 打开API密钥仪表板 在新标签页中，然后返回并按照你上面选择的路径操作。

第 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 的代码示例。

提交需求 表单