TypeWhisper 本地 HTTP API v1 完全参考：转写、模型管理、录音控制与认证详解

语音音频AI 应用桌面应用CLI插件系统【免费下载链接】typewhisper-macLocal speech-to-text for macOS on-device AI, fully private, optional cloud项目地址https://gitcode.com/gh_mirrors/ty/typewhisper-mac点击查看免费下载TypeWhisper 的本地 HTTP API 让任何本地脚本、Raycast 扩展或自动化工具都能通过127.0.0.1直接调用这台 Mac 上的语音转写能力上传音频转写、管理模型引擎、远程启动听写与录音、读写历史和词典。默认端口8978只绑定回环地址默认关闭建议开启 Token 认证。这篇参考基于源码逐端点整理帮你快速把 TypeWhisper 接入自己的自动化流程。1. 30 秒了解架构与安全边界整个 API 服务只有四个核心文件结构非常清爽HTTPServer.swift — 基于 Network.framework 的 TCP 监听器强制绑定127.0.0.1局域网设备无法访问请求体上限 256 MiB超出返回413APIRouter.swift — 路由分发 认证校验Token 采用恒定时间比较防止时序攻击APIHandlers.swift — 全部/v1/*端点的实现APIServerViewModel.swift — 启停管理与端口/令牌发现文件一个值得注意的细节路由器会主动拒绝来自网页的跨站请求Host 必须是127.0.0.1/localhostOrigin 检查 sec-fetch-site校验即使你关闭了 Token 认证恶意网页也无法利用 DNS rebinding 调用你的听写和历史数据。2. 启用 API 服务器并获取认证 Token打开设置 → 高级 → API Server区域打开Enable API Server开关服务器启动并显示Running on port 8978保持Require API Token开启默认开启。关闭时设置界面会用橙色警告你这台 Mac 上的任何应用都能通过 API 发起听写和读取历史点击Copy API Token复制令牌认证机制在 LocalAPIAuthenticator 中实现项目说明Token 生成32 字节随机数SecRandomCopyBytesBase64URL 编码共 44 字符存储位置macOS 钥匙串Keychain servicelocal-api-token发现文件~/Library/Application Support/TypeWhisper/api-discovery.json权限0600含port和token字段传递方式请求头Authorization: Bearer token或自定义头X-TypeWhisper-API-TokenCLI、Raycast 扩展等本地工具都通过 PortDiscovery 读取这个发现文件自动拿到端口和令牌无需手工配置。# 检查服务器状态唯一无需 Token 的公开端点 curl http://127.0.0.1:8978/v1/status返回示例statusready/no_model、当前engine、model、api_version: 1.2以及supports_streaming、supports_translation等能力位。3. 端点总览v1方法路径功能GET/v1/status服务器状态公开无需 TokenPOST/v1/transcribe上传音频并转写POST/v1/transcribe/local-file转写本机已存在的音频文件GET/v1/models列出全部引擎与模型目录POST/v1/models/load加载指定引擎的模型POST/v1/models/unload卸载引擎模型DELETE/v1/models?enginemodel删除已下载的模型GET/v1/history?qlimitoffset搜索/分页查询转写历史DELETE/v1/history?id删除一条历史GET/PUT/v1/rules、/v1/rules/toggle查看/启停工作流规则/v1/profiles为别名POST/v1/dictation/start、/v1/dictation/stop远程启动/停止听写GET/v1/dictation/status、/v1/dictation/transcription?id查询听写状态与结果POST/v1/recorder/start、/v1/recorder/stop启动/停止 Recorder 录音GET/v1/recorder/status、/v1/recorder/session?id、/v1/recorder/recordings?since查询录音状态、会话与完成稿GET/PUT/DELETE/v1/dictionary/terms、/v1/dictionary/corrections词典词条与纠错规则管理GET/v1/settings/export导出全部设置JSON 备份POST/v1/settings/import?modemerge\|replace导入设置备份GET/PATCH/v1/settings/audio查看/修改麦克风优先级、音频闪避等4. 转写接口/v1/transcribe这是最核心的端点实现见 handleTranscribe。它支持两种请求方式方式一multipart 表单推荐file字段为音频文件WAV/MP3/M4A/FLAC/OGG/AAC其余选项作为普通表单字段language指定语言或可重复的language_hint混合语言提示两者不能同时用tasktranscribe默认或translatetarget_language转写后本地翻译的目标语言需 macOS 15response_formatjson默认或verbose_json额外返回带时间戳的segmentsengine/model按请求覆盖STT 引擎和模型见下节prompt自定义提示词会与词典词条提示自动合并normalize_numbers、apply_corrections默认truedetect_speakers需 Premiumspeaker_count方式二裸音频 x-请求头请求体直接放音频二进制语言、引擎等选项通过x-language、x-engine、x-model、x-prompt等头部传递适合流式管道场景。curl -X POST http://127.0.0.1:8978/v1/transcribe \ -H Authorization: Bearer $TW_TOKEN \ -F filemeeting.wav \ -F languagezh \ -F response_formatverbose_jsonPOST /v1/transcribe/local-file则接受 JSON 体{path: /path/to/file.wav, ...}字段与 multipart 模式一致适合服务器本机批量处理。engine/model 覆盖的四种组合resolveEngineModelOverride 实现了清晰的解析矩阵enginemodel行为不传不传使用 GUI 当前选中的引擎与模型✅不传该引擎的默认模型不传✅跨引擎扫描模型目录自动推断若多个引擎提供同名模型返回 400 要求补充engine✅✅直接使用若该引擎未提供此模型返回 400若目标引擎尚未配置缺 API Key 或未下载权重默认返回409追加?await_download1可让服务器等待模型恢复/下载完成再转写。5. 模型管理端点GET /v1/models— 返回所有引擎的完整模型目录id、engine、size_description、language_count、statusready/not_configured、selected、downloaded、loadedPOST /v1/models/load— 请求体{engine: mlx, model: whisper-large-v3}成功返回status: readyPOST /v1/models/unload— 释放内存引擎不支持时返回409DELETE /v1/models?enginemodel— 删除已下载的本地权重为磁盘空间腾位置配合/v1/status你可以写一个按需加载 → 转写 → 卸载的脚本让大模型只在需要时驻留内存。6. 录音控制听写与 Recorder远程听写/v1/dictation/*POST /v1/dictation/start可带workflow_id指定工作流不存在返回 404已禁用返回 409启动后文本会插入到当前前台应用——这是实现让 Mac 替我打字自动化的关键。流程POST /v1/dictation/start→ 返回会话id用户说话后POST /v1/dictation/stopGET /v1/dictation/transcription?id→ 拿到status含失败原因error、transcription正文、原始文本、引擎、词数和latency首帧延迟、后处理耗时等完整链路追踪GET /v1/dictation/status随时查看当前状态与激活的工作流。录音器/v1/recorder/*Recorder 是独立于听写的录音通道支持麦克风 系统内录POST /v1/recorder/start?mictruesystem_audiotrue— 至少开启一个音源POST /v1/recorder/stop— 返回status: finalizingGET /v1/recorder/session?id— 查询会话的转写文本与输出文件路径GET /v1/recorder/recordings?sinceUnix秒|ISO8601— 增量拉取完成的转写稿适合会议录制 → 自动归档这类轮询型集成7. 历史、词典与设置GET /v1/history— 支持q搜索、limit0–200默认 50、offset分页、includespeaker_segments附带说话人分段返回条目含来源应用app_name、app_bundle_id、app_url词典—GET/PUT/DELETE /v1/dictionary/terms管理发音提示词支持ctc_min_similarity字段/v1/dictionary/corrections管理原文 → 替换纠错规则PUT为 upsert 语义设置备份—GET /v1/settings/export导出全量 JSONPOST /v1/settings/import支持modemerge默认只新增或modereplace同名覆盖。多机配置同步、CI 环境初始化都靠它音频设置—GET/PATCH /v1/settings/audio修改麦克风优先级列表、音频闪避、声音反馈录音中会返回 409拒绝并发修改8. 配套 CLItypewhisper 命令仓库自带命令行工具 typewhisper-cli应用内可一键安装到/usr/local/bin/typewhisper自动发现端口和 Tokentypewhisper status # 服务器状态 typewhisper models # 列出模型 typewhisper transcribe meeting.wav --language de # 转写文件 typewhisper transcribe - audio.wav --json # 管道输入 typewhisper transcribe rec.wav --engine groq --model whisper-large-v3-turbo typewhisper export settings.json typewhisper import settings.json --replace typewhisper audio # 查看/修改音频设置--no-corrections可关闭词典纠错拿到原始转写--port/--api-token用于覆盖自动发现。9. 常见错误码速查错误统一为{error: {code: ..., message: ...}}结构定义于 HTTPResponse.swiftHTTPcode典型场景400bad_request参数缺失/格式错误language与language_hint混用模型 ID 有歧义401unauthorizedToken 缺失或不匹配403forbidden来自外部网页的跨站请求含 DNS rebinding 防护404not_found未知引擎/模型/会话/历史条目409service_unavailable引擎未配置、正在录音中重复启动、录音中改音频设置413payload_too_large请求体超过 256 MiB503service_unavailable无可用引擎、说话人检测不可用10. 参考资料API 路由与认证APIRouter.swift、HTTPServer.swift端点实现APIHandlers.swift请求解析256 MiB 上限、multipart 支持HTTPRequestParser.swiftToken 与发现文件APIServerViewModel.swiftCLI 与端口发现main.swift、PortDiscovery.swift功能演进记录1.3.0 发布说明按请求选择引擎/模型、1.4.0 发布说明Recorder 与词典端点 安全建议API 虽只监听回环地址但同机其他应用仍可访问。请保持 Token 认证开启并定期检查api-discovery.json权限应为600。赞分享语音音频AI 应用桌面应用CLI插件系统【免费下载链接】typewhisper-macLocal speech-to-text for macOS on-device AI, fully private, optional cloud项目地址https://gitcode.com/gh_mirrors/ty/typewhisper-mac点击查看免费下载相关推荐mlx-audio 语音识别STTAPI 参考模型加载、转写 CLI 与参数详解mlx audio 语音识别STTAPI 参考模型加载、转写 CLI 与参数详解 mlx audio 是基于 Apple MLX 框架的语音库其 STT语音音频人工智能本地部署模型推理服务手柄上刷B站的客厅方案Switch B站客户端 wiliwili 安装教程手柄上刷B站的客厅方案Switch B站客户端 wiliwili 安装教程 把 Switch 接到客厅电视手柄一握B 站的弹幕就飘起来了这是 wiliw音视频桌面应用ClawHub HTTP API 完整参考公开目录、CLI 认证端点与速率限制实践指南ClawHub HTTP API 完整参考公开目录、CLI 认证端点与速率限制实践指南 ClawHub 是 OpenClaw 生态的 Skill Plug后端前端AI 技能AI 插件搜索引擎创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考