开发者文档以英文发布，侧边栏导航跟随你选择的语言。

API 参考

Base URL：https://api.subdownload.com · 鉴权：Authorization: Bearer sk_live_xxx

接口列表

GET /v1/verify free

校验 API Key 是否有效，返回 Token 和用户信息。不消耗积分。

请求

curl -H "Authorization: Bearer sk_live_xxx" \
  https://api.subdownload.com/v1/verify

响应 200

{
  "valid": true,
  "token": { "name": "My App", "prefix": "sk_live_abc", "monthly_quota": 0, "used_quota": 120 },
  "user": { "id": 42, "email": "[email protected]", "plan": "free", "credits_remaining": 148 }
}

GET /v1/youtube/transcript 1 credit

获取 YouTube 视频的字幕。支持视频 ID 或任意合法 YouTube URL（watch、youtu.be、shorts）。

参数

名称	类型	必填	说明
`video_id`	string	必填	11 位视频 ID 或完整 YouTube URL。别名：`video_url`。
`lang`	string	可选	优先语言代码，逗号分隔（如 `en,zh,ja`）。

请求

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://api.subdownload.com/v1/youtube/transcript?video_id=dQw4w9WgXcQ&lang=en"

响应 200

{
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "language": "en",
    "segments": [
      { "text": "We're no strangers to love", "start": 0.0, "duration": 3.5 }
    ],
    "text": "We're no strangers to love...",
    "meta": { "title": "...", "author": "...", "thumbnail": "..." }
  },
  "credits_used": 1,
  "credits_remaining": 148
}

错误

400 缺少 video_id · 404 没有字幕 · 402 积分耗尽

GET /v1/youtube/search 1 credit

按关键词搜索 YouTube 视频或频道。

参数

名称	类型	必填	说明
`q`	string	必填	搜索词（1-200 字符）。
`type`	string	可选	`video`（默认）或 `channel`。
`limit`	integer	可选	返回 1-50 条（默认 20）。

请求

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://api.subdownload.com/v1/youtube/search?q=rust+tutorial&limit=5"

GET /v1/youtube/channel/resolve free

把任意频道引用（@handle、URL 或 UC… ID）解析为频道信息。

参数

名称	类型	必填	说明
`input`	string	必填	@handle、频道 URL、视频 URL 或 UC… ID。

GET /v1/youtube/channel/search 1 credit

在指定频道内搜索视频。

参数

名称	类型	必填	说明
`channel`	string	必填	@handle、URL 或 UC… ID（别名：`channel_id`）。
`q`	string	必填	搜索词。
`limit`	integer	可选	1-50（默认 30）。

GET /v1/youtube/channel/latest free

通过 RSS 获取频道最近约 15 条视频，快速免费。

参数

名称	类型	必填	说明
`channel`	string	必填	@handle、URL 或 UC… ID（别名：`channel_id`）。

GET /v1/youtube/channel/videos 1 credit/page

列出频道上传的全部视频，每页约 100 条。

参数

名称	类型	必填	说明
`channel`	string	首页必填	@handle、URL 或 UC… ID（别名：`channel_id`）。
`continuation`	string	后续页	上一次返回的 token。

注意：channel 和 continuation 二选一，不要同时传。

GET /v1/youtube/playlist/videos 1 credit/page

分页列出 YouTube 播放列表里的视频。

参数

名称	类型	必填	说明
`playlist`	string	首页必填	播放列表 URL 或 ID（`PL…`、`UU…`、`LL…`、`FL…`、`OL…`）。
`continuation`	string	后续页	上一次返回的 token。

AI 转写（ASR）

为没有字幕的视频跑 Whisper。异步：POST 创建任务，再轮询 GET 直到 status=done。5 credits，仅在成功完成时才扣 —— 同一视频再跑一次免费。

POST /v1/youtube/asr done 时扣 5 credits

创建一个异步 AI Whisper 转写任务。返回 task_id 和 ETA 提示，方便你节奏化轮询。

请求体（JSON）

名称	类型	必填	说明
`video_url`	string	必填	YouTube URL（watch / youtu.be / shorts / embed）。
`lang`	string	可选	语言提示（如 `en`、`zh`）。留空则自动识别。

请求

curl -X POST -H "Authorization: Bearer sk_live_xxx"   -H "Content-Type: application/json"   -d '{"video_url":"https://youtu.be/dQw4w9WgXcQ"}'   https://api.subdownload.com/v1/youtube/asr

响应 202

{
  "task_id": "task_01HX...",
  "status": "queued",
  "from_cache": false,
  "queue_position": 2,
  "estimated_wait_seconds": 61,
  "next_poll_after_seconds": 15,
  "poll_url": "/v1/youtube/asr/task_01HX..."
}

按 next_poll_after_seconds 节奏轮询。命中缓存时直接返回 status=done，segments 已内联。

GET /v1/youtube/asr/{task_id} free

轮询 ASR 任务。免费 —— 不扣 credits、不计 token quota。任务仅创建者可读。

响应 200（done）

{
  "task": {
    "task_id": "task_01HX...",
    "status": "done",
    "detected_lang": "en",
    "duration_seconds": 213,
    "segments": [
      { "start": 0.0, "end": 3.5, "text": "..." }
    ],
    "stage_progress": 1
  },
  "estimated_wait_seconds": 0,
  "next_poll_after_seconds": 0
}

状态：queued · downloading · transcribing · done · failed · cancelled。只有 status=done 时 segments 才是最终结果。

Library（用户库）

按用户保存转写和 AI 总结的存储。读取免费；写入计 1 个 token quota 单位。整个 Library API 不扣用户 credits。

GET /v1/library free

列出用户保存到 Library 的条目（转写和总结都在内）。

参数

名称	类型	必填	说明
`favorite`	string	可选	`1` 或 `true` 则只返回收藏项。
`q`	string	可选	对 title / author 做子串匹配。
`tag`	string	可选	按 tag 过滤。
`limit`	integer	可选	1–100（默认 20）。
`offset`	integer	可选	分页偏移。

响应 200

{
  "items": [
    {
      "id": 42,
      "video_id": "dQw4w9WgXcQ",
      "title": "...", "thumbnail": "...",
      "has_asr": true,
      "has_summary": true,
      "is_favorite": false
    }
  ],
  "total": 7, "limit": 20, "offset": 0
}

GET /v1/library/{id} free

获取单个 Library 条目的元数据。用 has_asr / has_summary 判断下一步要调哪个内容接口。

GET /v1/library/{id}/transcript free

取该 Library 条目对应的 ASR segments + 合并后的文本。没有已完成的 ASR 时返回 404。

响应 200

{
  "task_id": "task_01...",
  "detected_lang": "en",
  "duration_seconds": 213,
  "text": "joined
segment
text...",
  "segments": [{ "start": 0.0, "end": 3.5, "text": "..." }]
}

GET /v1/library/{id}/summary free

取该 Library 条目保存的总结文本。用 ?locale= 从多个 locale 中挑（默认 Accept-Language 然后 en）。

响应 200

{
  "locale": "en",
  "text": "...",
  "model": "claude-opus-4",
  "updated_at": "2026-04-22T..."
}

当 (video_id, locale) 没有总结时返回 404。客户端可以换个 ?locale= 重试。

POST /v1/library free（计 1 个 token quota）

kind=asr 标记转写已保存（segments 在 ASR 表里）。kind=summary 把预先生成好的总结文本上传到 summaries 表并标记 has_summary=true。在 (video_id, locale) 上 upsert。

请求体（JSON）

名称	类型	必填	说明
`video_id`	string	必填	YouTube 视频 ID。
`kind`	string	必填	`asr` 或 `summary`。
`title / author / thumbnail / video_url / language / tag`	string	可选	用于展示和过滤的元信息。
`locale`	string	summary 模式	总结的 locale（默认 `Accept-Language` 然后 `en`）。
`text`	string	kind=summary 时必填	要保存的总结文本。
`model`	string	可选	LLM 标识（如 `claude-opus-4`）。

请求（上传总结）

curl -X POST -H "Authorization: Bearer sk_live_xxx"   -H "Content-Type: application/json"   -d '{
    "video_id": "dQw4w9WgXcQ",
    "kind": "summary",
    "locale": "zh",
    "text": "这个视频讲的是...",
    "model": "claude-opus-4",
    "title": "..."
  }'   https://api.subdownload.com/v1/library

DELETE /v1/library/{id} free

软删除一个 Library 条目。后续对同一视频 POST /v1/library 会恢复这行而不是新建重复项。

官方 SDK

用我们的官方客户端库快速接入：

语言	仓库
Python	api-sdk/python
JavaScript	api-sdk/javascript
Go	api-sdk/go
Java	api-sdk/java
Kotlin	api-sdk/kotlin
Rust	api-sdk/rust

→ 完整源码：github.com/SubDownload/api-sdk

→ 计费、速率限制、错误码请看计费与支持。

开发者文档以英文发布，侧边栏导航跟随你选择的语言。

API 参考

Base URL：https://api.subdownload.com · 鉴权：Authorization: Bearer sk_live_xxx

接口列表

GET /v1/verify free

校验 API Key 是否有效，返回 Token 和用户信息。不消耗积分。

请求

curl -H "Authorization: Bearer sk_live_xxx" \
  https://api.subdownload.com/v1/verify

响应 200

{
  "valid": true,
  "token": { "name": "My App", "prefix": "sk_live_abc", "monthly_quota": 0, "used_quota": 120 },
  "user": { "id": 42, "email": "[email protected]", "plan": "free", "credits_remaining": 148 }
}

GET /v1/youtube/transcript 1 credit

获取 YouTube 视频的字幕。支持视频 ID 或任意合法 YouTube URL（watch、youtu.be、shorts）。

参数

名称	类型	必填	说明
`video_id`	string	必填	11 位视频 ID 或完整 YouTube URL。别名：`video_url`。
`lang`	string	可选	优先语言代码，逗号分隔（如 `en,zh,ja`）。

请求

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://api.subdownload.com/v1/youtube/transcript?video_id=dQw4w9WgXcQ&lang=en"

响应 200

{
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "language": "en",
    "segments": [
      { "text": "We're no strangers to love", "start": 0.0, "duration": 3.5 }
    ],
    "text": "We're no strangers to love...",
    "meta": { "title": "...", "author": "...", "thumbnail": "..." }
  },
  "credits_used": 1,
  "credits_remaining": 148
}

错误

400 缺少 video_id · 404 没有字幕 · 402 积分耗尽

GET /v1/youtube/search 1 credit

按关键词搜索 YouTube 视频或频道。

参数

名称	类型	必填	说明
`q`	string	必填	搜索词（1-200 字符）。
`type`	string	可选	`video`（默认）或 `channel`。
`limit`	integer	可选	返回 1-50 条（默认 20）。

请求

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://api.subdownload.com/v1/youtube/search?q=rust+tutorial&limit=5"

GET /v1/youtube/channel/resolve free

把任意频道引用（@handle、URL 或 UC… ID）解析为频道信息。

参数

名称	类型	必填	说明
`input`	string	必填	@handle、频道 URL、视频 URL 或 UC… ID。

GET /v1/youtube/channel/search 1 credit

在指定频道内搜索视频。

参数

名称	类型	必填	说明
`channel`	string	必填	@handle、URL 或 UC… ID（别名：`channel_id`）。
`q`	string	必填	搜索词。
`limit`	integer	可选	1-50（默认 30）。

GET /v1/youtube/channel/latest free

通过 RSS 获取频道最近约 15 条视频，快速免费。

参数

名称	类型	必填	说明
`channel`	string	必填	@handle、URL 或 UC… ID（别名：`channel_id`）。

GET /v1/youtube/channel/videos 1 credit/page

列出频道上传的全部视频，每页约 100 条。

参数

名称	类型	必填	说明
`channel`	string	首页必填	@handle、URL 或 UC… ID（别名：`channel_id`）。
`continuation`	string	后续页	上一次返回的 token。

注意：channel 和 continuation 二选一，不要同时传。

GET /v1/youtube/playlist/videos 1 credit/page

分页列出 YouTube 播放列表里的视频。

参数

名称	类型	必填	说明
`playlist`	string	首页必填	播放列表 URL 或 ID（`PL…`、`UU…`、`LL…`、`FL…`、`OL…`）。
`continuation`	string	后续页	上一次返回的 token。

AI 转写（ASR）

为没有字幕的视频跑 Whisper。异步：POST 创建任务，再轮询 GET 直到 status=done。5 credits，仅在成功完成时才扣 —— 同一视频再跑一次免费。

POST /v1/youtube/asr done 时扣 5 credits

创建一个异步 AI Whisper 转写任务。返回 task_id 和 ETA 提示，方便你节奏化轮询。

请求体（JSON）

名称	类型	必填	说明
`video_url`	string	必填	YouTube URL（watch / youtu.be / shorts / embed）。
`lang`	string	可选	语言提示（如 `en`、`zh`）。留空则自动识别。

请求

curl -X POST -H "Authorization: Bearer sk_live_xxx"   -H "Content-Type: application/json"   -d '{"video_url":"https://youtu.be/dQw4w9WgXcQ"}'   https://api.subdownload.com/v1/youtube/asr

响应 202

{
  "task_id": "task_01HX...",
  "status": "queued",
  "from_cache": false,
  "queue_position": 2,
  "estimated_wait_seconds": 61,
  "next_poll_after_seconds": 15,
  "poll_url": "/v1/youtube/asr/task_01HX..."
}

按 next_poll_after_seconds 节奏轮询。命中缓存时直接返回 status=done，segments 已内联。

GET /v1/youtube/asr/{task_id} free

轮询 ASR 任务。免费 —— 不扣 credits、不计 token quota。任务仅创建者可读。

响应 200（done）

{
  "task": {
    "task_id": "task_01HX...",
    "status": "done",
    "detected_lang": "en",
    "duration_seconds": 213,
    "segments": [
      { "start": 0.0, "end": 3.5, "text": "..." }
    ],
    "stage_progress": 1
  },
  "estimated_wait_seconds": 0,
  "next_poll_after_seconds": 0
}

状态：queued · downloading · transcribing · done · failed · cancelled。只有 status=done 时 segments 才是最终结果。

Library（用户库）

按用户保存转写和 AI 总结的存储。读取免费；写入计 1 个 token quota 单位。整个 Library API 不扣用户 credits。

GET /v1/library free

列出用户保存到 Library 的条目（转写和总结都在内）。

参数

名称	类型	必填	说明
`favorite`	string	可选	`1` 或 `true` 则只返回收藏项。
`q`	string	可选	对 title / author 做子串匹配。
`tag`	string	可选	按 tag 过滤。
`limit`	integer	可选	1–100（默认 20）。
`offset`	integer	可选	分页偏移。

响应 200

{
  "items": [
    {
      "id": 42,
      "video_id": "dQw4w9WgXcQ",
      "title": "...", "thumbnail": "...",
      "has_asr": true,
      "has_summary": true,
      "is_favorite": false
    }
  ],
  "total": 7, "limit": 20, "offset": 0
}

GET /v1/library/{id} free

获取单个 Library 条目的元数据。用 has_asr / has_summary 判断下一步要调哪个内容接口。

GET /v1/library/{id}/transcript free

取该 Library 条目对应的 ASR segments + 合并后的文本。没有已完成的 ASR 时返回 404。

响应 200

{
  "task_id": "task_01...",
  "detected_lang": "en",
  "duration_seconds": 213,
  "text": "joined
segment
text...",
  "segments": [{ "start": 0.0, "end": 3.5, "text": "..." }]
}

GET /v1/library/{id}/summary free

取该 Library 条目保存的总结文本。用 ?locale= 从多个 locale 中挑（默认 Accept-Language 然后 en）。

响应 200

{
  "locale": "en",
  "text": "...",
  "model": "claude-opus-4",
  "updated_at": "2026-04-22T..."
}

当 (video_id, locale) 没有总结时返回 404。客户端可以换个 ?locale= 重试。

POST /v1/library free（计 1 个 token quota）

请求体（JSON）

名称	类型	必填	说明
`video_id`	string	必填	YouTube 视频 ID。
`kind`	string	必填	`asr` 或 `summary`。
`title / author / thumbnail / video_url / language / tag`	string	可选	用于展示和过滤的元信息。
`locale`	string	summary 模式	总结的 locale（默认 `Accept-Language` 然后 `en`）。
`text`	string	kind=summary 时必填	要保存的总结文本。
`model`	string	可选	LLM 标识（如 `claude-opus-4`）。

请求（上传总结）

curl -X POST -H "Authorization: Bearer sk_live_xxx"   -H "Content-Type: application/json"   -d '{
    "video_id": "dQw4w9WgXcQ",
    "kind": "summary",
    "locale": "zh",
    "text": "这个视频讲的是...",
    "model": "claude-opus-4",
    "title": "..."
  }'   https://api.subdownload.com/v1/library

DELETE /v1/library/{id} free

软删除一个 Library 条目。后续对同一视频 POST /v1/library 会恢复这行而不是新建重复项。

官方 SDK

用我们的官方客户端库快速接入：

语言	仓库
Python	api-sdk/python
JavaScript	api-sdk/javascript
Go	api-sdk/go
Java	api-sdk/java
Kotlin	api-sdk/kotlin
Rust	api-sdk/rust

→ 完整源码：github.com/SubDownload/api-sdk

→ 计费、速率限制、错误码请看计费与支持。