生产 REST API · v1

使用 YTSave 构建下载

解析公共媒体URL，选择精确格式，创建异步任务并将签名结果交给用户。相同的绑定生产管道支持YTSave网站。

YTSaveClientHTTPS 上的 JSON异步作业限定权限凭证

快速开始

YTSave 通过首先识别支持激活的凭据来处理 API 主机。随后是分配的租户端点，并保持服务器专用调用路径可见。

租户网址https://ytsave.app

认证X-API-Key: ys_live_…

客户端配置文件YTSaveClient

API 版本v1

# Available only after support activation
export YTSAVE_API_KEY="issued-after-review"

curl -X POST https://ytsave.app/v1/resolve \
  -H "X-API-Key: $YTSAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=VIDEO_ID"}'

为说明凭证安全，YTSave 将服务器端秘密存储与无客户端包嵌入分开。证据记录不会为公共日志或存储库提供独立位置。

解析链接

YTSave 通过首先识别源检测来处理解析操作。随后处理来自一个提交 URL 的格式，并保持视图中无虚构输出。

发布/v1/resolve范围：解析

字段	类型	必填	描述
`url`	HTTPS URL	是	公共或授权媒体页面进行分析。
`tenant`	字符串	否	已分配租户域。通常省略。

{
  "success": true,
  "platform": "youtube",
  "title": "Example video",
  "formats": [
    {"id":"18","type":"video","quality":"360p","container":"mp4"}
  ],
  "cached": false
}

为了解释格式标识符，YTSave 将返回值与每个链接的可用性分开，保持不变。证据记录不会为猜测的质量标签分配位置。

创建并跟踪下载任务

对于作业创建，YTSave 从异步准备开始。其证据记录将其与简短 HTTP 请求配对，最终以有限工作线程执行结束。

发布/v1/jobs范围：职位

字段	类型	必填	描述
`url`	HTTPS URL	是	提交了相同的规范化来源以解决。
`format_id`	字符串	是	解析响应中的精确 ID。
`tenant`	字符串	否	已分配租户域。通常省略。

curl -X POST https://ytsave.app/v1/jobs \
  -H "X-API-Key: $YTSAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=VIDEO_ID","format_id":"18"}'

1202 已接受保存 job_id.

2投票状态GET /v1/jobs/{job_id} 使用相同的密钥。

3准备好打开已签名的下载链接。

状态	含义	客户操作
`queued`	已加入有界队列。	使用退避策略再次投票。
`extracting`	正在刷新源元数据或路由。	继续轮询。
`processing`	正在下载、重混或合并。	显示服务器进度。
`ready`	已提供签名下载。	将网址发送给用户。
`failed`	终端结构化错误。	读取 `error_code`. 仅在建议时重试。
`expired`	临时输出已被移除。	创建新任务。

curl https://ytsave.app/v1/jobs/JOB_ID \
  -H "X-API-Key: $YTSAVE_API_KEY"

YTSave 使任务轮询易于扫描。页面以一秒的初始等待开始，转为有上限的退避，并明确说明临时签署交付。

可预测的错误

对于错误合约，YTSave 在支持请求 ID 之前检查一个非 2xx 信封。此证据记录也使可预测的客户端处理变得清晰。

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "category": "rate_limited",
    "message": "Too many requests. Please try again shortly.",
    "retryable": true,
    "details": {"retry_after_seconds": 20}
  },
  "request_id": "…"
}

HTTP	典型含义	动作
400	无效的URL、正文或不可用的格式。	请求有误。请重新解析格式。
401	缺失、无效、过期或范围错误的密钥。	检查服务器端凭证。
403	租户或源策略拒绝了请求。	不要绕过政策。请联系支持。
404	未知或已过期的任务。	如适用，创建新任务。
429	请求或活动任务已达上限。	荣誉 `retry_after_seconds`.
503	队列/容量或上游暂时不可用。	使用指数退避和抖动重试。

运营合同

YTSave 在每次批准时发放操作配额，以保护 API 使用者和上游媒体服务。

使用幂等的应用逻辑，绝不为同一用户点击启动重复的任务。
缓存解析元数据时间短，但始终将签名下载 URL 视为过期。
对……使用带抖动的有界指数退避 429, 503 和可重试错误。
仅处理公开媒体或您有权限访问的媒体。不绕过 DRM 和访问控制。
在私有操作日志中保留请求 ID 和作业 ID。不要不必要地记录提交的 URL。

YTSave通过先识别激活再进行探索来处理Schema访问。随后进行分配的身份验证，并保持请求形态的文档可见。 OpenAPI 参考

运营商审核访问

请求您的API密钥

记录API使用者、其每月请求估计和支持的平台要求。YTSave在发放一次性可见密钥前，会审查解析、任务提交或两者是否合理。

请求 API 访问权限密钥是租户范围的，可撤销，并通过联系表单发放。匿名脚本无法执行下载器工作。