URL Scheme
snipkap:// 动作参考。路径段对应 CLI 位置参数，查询参数对应选项；当前动作 Schema 为 6。
snipkap:// 与 CLI 共用动作 Schema 6、同一套校验和结果码。适合浏览器、快捷指令、Raycast、Alfred 和其他桌面应用。
URL 不能把执行结果同步返回网页。需要可靠结果时用 CLI，并为查询或 OCR 指定 --to。
snipkap://<command>/<位置参数>?<查询参数>路径段对应 CLI 位置参数；查询参数只使用下列名称，顺序不影响结果。
编码与限制
- 路径、空格和特殊字符必须 UTF-8 百分号编码。空格写成
%20，加号写成%2B。例如/tmp/a b.png→%2Ftmp%2Fa%20b.png。 - 不允许凭据、端口、
#片段、控制字符、NUL、畸形百分号编码、空查询项或未声明参数。 - 同一查询名不能重复，
pin-paths的path除外。 - 不要在 URL 里放置密钥、Token 或其他敏感信息。
危险 URL 会要求确认
网页也可以触发自定义 Scheme。关闭贴图、退出应用、写入任何本地文件、删除或清空历史时，会弹出确认。CLI 视为本机明确指令，不增加这层确认，但仍不覆盖已有文件。
capture
snipkap://capture?mode=<mode>&output=<output>&irregular=<pen|freehand>&horizontal=<bool>&sides=<3..64>&width=<1..32768>&height=<1..32768>&to=<encoded-path>只填写当前模式需要的参数。horizontal=true 对应 CLI 的 --horizontal 开关。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
mode | 枚举 | 否 | rect、irregular、long、gif、fixed、delay、whiteboard。别名 rectangle、shape |
output | 枚举 | 否 | interactive、clipboard、save、pin、history |
irregular | 枚举 | 仅异型 | pen 或 freehand |
horizontal | 布尔 | 否 | 仅长截图。true / false / on / off / 1 / 0 |
sides | 3..64 | 仅固定形状 | 正多边形边数 |
width / height | 1..32768 | 仅固定形状 | 必须成对出现 |
to | 编码路径 | 保存时 | 隐式 save；目标必须不存在 |
gif、delay、whiteboard 只接受默认的 interactive 输出。
snipkap://capture?mode=rect&output=clipboard
snipkap://capture?mode=long&horizontal=true&output=pin
snipkap://capture?mode=fixed&sides=6&width=800&height=600&to=%2Ftmp%2Fc.png创建贴图
snipkap://pin-clipboard
snipkap://pin-paths?path=<encoded-path>&path=<encoded-path>...
snipkap://restore-pins| URL | 说明 |
|---|---|
pin-clipboard | 从剪贴板创建贴图 |
pin-paths | 每个 path 创建一个贴图，最多 256 项 |
restore-pins | 恢复上次保存的穿透贴图 |
snipkap://pin-paths?path=%2Ftmp%2Fone.png&path=%2Ftmp%2Ftwo.pngpins
snipkap://pins/list[?to=<encoded-json-path>]
snipkap://pins/close/<id|all>
snipkap://pins/passthrough/<id|all>/<on|off>
snipkap://pins/rotate/<id|all>/<left|right|180>
snipkap://pins/mirror/<id|all>
snipkap://pins/opacity/<id|all>/<10..100>
snipkap://pins/scale/<id|all>/<10..1000>
snipkap://pins/reset/<id|all>
snipkap://pins/copy/<id>
snipkap://pins/save/<id>?to=<encoded-image-path>copy、save 不接受 all。close 与 save 会要求用户确认。
snipkap://pins/passthrough/all/on
snipkap://pins/save/0123456789abcdef0123456789abcdef?to=%2Ftmp%2Fpin.pnghistory
snipkap://history/enable
snipkap://history/disable
snipkap://history/pause
snipkap://history/resume
snipkap://history/settings?days=<1..365>&maxEntries=<1..10000>
snipkap://history/open
snipkap://history/list[?to=<encoded-json-path>]
snipkap://history/latest
snipkap://history/pin?id=<id>
snipkap://history/copy?id=<id>
snipkap://history/save?id=<id>&to=<encoded-image-path>
snipkap://history/delete?id=<id>
snipkap://history/clear
snipkap://history/dock/show
snipkap://history/dock/hide
snipkap://history/dock/toggle| 查询名 | 对应 CLI | 说明 |
|---|---|---|
days | --days | 保留天数 1..365，必须与 maxEntries 成对 |
maxEntries | --max-entries | 最大条数 1..10000。注意是驼峰，不是 max-entries |
id | 位置参数 | 32 位小写十六进制历史 ID |
to | --to | 新文件路径，必须尚不存在 |
delete 与 clear 会要求用户确认。
snipkap://history/settings?days=7&maxEntries=1024
snipkap://history/dock/showocr
snipkap://ocr/history/<id>[?output=<panel|clipboard|text|json>&to=<encoded-path>]
snipkap://ocr/path?path=<encoded-image-path>&output=<panel|clipboard|text|json>&to=<encoded-path>默认 output=panel。text / json 必须有 to；panel / clipboard 禁止 to。
| 参数 | 用于 | 说明 |
|---|---|---|
path | 仅 ocr/path | 本地图片的编码路径 |
output | 两种来源 | panel、clipboard、text、json |
to | text / json | 新结果文件 |
snipkap://ocr/history/0123456789abcdef0123456789abcdef?output=clipboard
snipkap://ocr/path?path=%2Ftmp%2Fimage.png&output=json&to=%2Ftmp%2Focr.json能力与状态
snipkap://capabilities[?to=<encoded-json-path>]
snipkap://status[?to=<encoded-json-path>]带 to 时写入 JSON 新文件，并要求用户确认。不带 to 只显示桌面反馈。AI 应使用 CLI 的 --to。
设置与生命周期
snipkap://smart-paste?enabled=<bool>
snipkap://launch-at-login?enabled=<bool>
snipkap://settings/open/general
snipkap://settings/open/ocr
snipkap://settings/open/capture-hotkey
snipkap://settings/open/pin-hotkey
snipkap://settings/open/permissions
snipkap://settings/open/history
snipkap://settings/open/personalization
snipkap://settings/open/watermark
snipkap://settings/open/translation
snipkap://settings/open/about
snipkap://preferences
snipkap://entitlement
snipkap://tool/scale-ruler
snipkap://tool/caliper
snipkap://tool/angle
snipkap://help
snipkap://about
snipkap://quitsmart-paste 与 launch-at-login 必须且只能带查询参数 enabled。watermark 是个性化水印页别名。preferences 在 Windows 打开通用设置，在 macOS 打开截图快捷键设置。quit 会要求确认。
结果码
与 CLI 相同。URL 无法把码同步返回调用页；机器调用请改用 CLI。
| 码 | 含义 |
|---|---|
0 | 成功或已接受 |
1 | 执行失败 |
2 | 参数无效 |
3 | 当前忙 |
4 | 文件、历史或 Pin 不存在 |
5 | 权限不足或用户拒绝 |
6 | 当前平台不支持 |
7 | 超过资源限制 |