# Apple 快捷指令配置 本服务提供 `GET /api/shortcut`,专门用于 iPhone 的分享菜单。接口返回的是服务端下载地址,而不是平台的短时原始媒体地址。YouTube / Bilibili 的高画质 DASH 视频与音频会分别提供,快捷指令可按需要选择其中一个流。 ## 先准备服务器地址 部署后在服务端配置: ```dotenv PUBLIC_BASE_URL=https://media.example.com API_KEY=请生成一段足够长的随机密钥 ``` 将下列示例的 `https://media.example.com` 替换为你的 HTTPS 域名。不要把本机 `127.0.0.1` 填到 iPhone 上;手机无法访问电脑自己的回环地址。 ## 建立“下载最高画质视频流”快捷指令 1. 新建快捷指令,打开“在共享表单中显示”,接收类型选择 **URL、文本**。 2. 加入“URL 编码”动作,输入为“快捷指令输入”。这一步能处理抖音、Bilibili 等 App 分享出的整段文案。 3. 加入“获取 URL 内容”: ```text https://media.example.com/api/shortcut?url=[URL 编码后的文本] ``` 方法选 `GET`。如果配置了 API 密钥,建议在 Headers 添加: ```text X-API-Key: 你的 API_KEY ``` 也可使用查询参数 `&key=你的 API_KEY`,但 Header 更不容易泄露。 4. 加入“从输入中获取字典”,依次取:`video` → `highest` → `downloadUrl`。 5. 对得到的 `downloadUrl` 再加入一次“获取 URL 内容”。该文件是平台的原始最高画质视频流;若页面标记“视频”,该流不含音频。 6. 连接“存储文件”或“存储到照片相册”。长视频或 4K 建议先“存储文件”,可靠性更高。 ## 建立“仅下载音频”快捷指令 步骤 1–3 与上面相同;第 4 步改为依次取:`audio` → `best` → `downloadUrl`,之后“获取 URL 内容”并“存储文件”。YouTube 和 Bilibili 会保留平台提供的最佳音频封装格式(通常为 M4A 或 WebM)。 ## 快捷指令广告与收费 Apple 快捷指令本身不能可靠显示网页广告。免费方案可以在“获取 URL 内容”后读取 `billing.adRequired`:如果为 `true`,先使用“打开 URL”打开 `billing.adUrl`(你的广告/赞助页),用户返回快捷指令后再继续下载;付费 API Key 返回 `adFree: true`,跳过广告。广告页的展示、会员校验和支付由你的服务器或广告平台负责,不能仅凭快捷指令动作判断用户已付费。 ## 接口返回示例 ```json { "ok": true, "apiVersion": "1.1", "title": "示例标题", "video": { "highest": { "quality": "1080p · 60fps", "downloadUrl": "https://media.example.com/api/download/…" } }, "audio": { "best": { "quality": "128 kbps", "downloadUrl": "https://media.example.com/api/download/…" } }, "downloadsExpireAt": "2026-08-29T00:00:00.000Z" } ``` 下载 URL 当前会在解析后 **30 分钟**过期,快捷指令需要在同一次运行中立即完成下载。它也只在产生该链接的同一服务进程中有效;多实例部署时请使用粘性会话,或将下载任务状态改为 Redis / 数据库共享。