開発者向けドキュメントは英語で公開されています。サイドバーは選択した言語に追従します。

API リファレンス

Base URL: https://api.subdownload.com · 認証: Authorization: Bearer sk_live_xxx

エンドポイント

GET /v1/verify free

API キーの有効性を確認。トークンとユーザー情報を返します。クレジットは消費しません。

リクエスト

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

チャンネルがアップロードした全動画を 1 ページ約 100 件でページネーション。

パラメータ

名前	型	必須	説明
`channel`	string	1 ページ目	@handle、URL または UC… ID（エイリアス：`channel_id`）。
`continuation`	string	次ページ	前回の呼び出しで返されたトークン。

注意：channel と continuation はどちらか一方のみ指定してください。

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

YouTube プレイリストの動画をページネーションで取得。

パラメータ

名前	型	必須	説明
`playlist`	string	1 ページ目	プレイリスト URL または ID（`PL…`、`UU…`、`LL…`、`FL…`、`OL…`）。
`continuation`	string	次ページ	前回のレスポンスのトークン。

AI 文字起こし（ASR）

字幕のない動画に対して Whisper を実行。非同期：POST でタスクを作成し、GET で status=done までポーリング。5 クレジット、成功時のみ課金。同じ動画を再度 ASR するのは無料です。

POST /v1/youtube/asr done 時 5 クレジット

非同期 AI Whisper 文字起こしを開始。task_id と ETA ヒントを返すので、適切な間隔でポーリングできます。

リクエストボディ（JSON）

名前	型	必須	説明
`video_url`	string	必須	YouTube URL（watch / youtu.be / shorts / embed）。
`lang`	string	任意	言語ヒント（例：`en`、`ja`）。省略で自動検出。

リクエスト

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} 無料

ASR タスクをポーリング。無料 — クレジット・トークンクォータ消費なし。タスクは作成者のみ読み取り可能。

レスポンス 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 トークンクォータ単位を消費。ユーザークレジットは課金されません。

GET /v1/library 無料

ユーザーが Library に保存した項目（文字起こし + 要約）を一覧。

パラメータ

名前	型	必須	説明
`favorite`	string	任意	`1` または `true` でお気に入りのみ。
`q`	string	任意	タイトル / 作者の部分一致。
`tag`	string	任意	タグでフィルタ。
`limit`	integer	任意	1–100（デフォルト 20）。
`offset`	integer	任意	ページネーションオフセット。

GET /v1/library/{id} 無料

単一 Library 項目のメタデータを取得。has_asr / has_summary を見て次にどのコンテンツ API を呼ぶか判断してください。

GET /v1/library/{id}/transcript 無料

Library 項目の ASR segments と連結テキストを取得。完了済みの ASR がない場合 404。

GET /v1/library/{id}/summary 無料

保存済み要約テキストを取得。?locale= で保存済み locale を選択（デフォルトは Accept-Language、次に en）。(video_id, locale) に要約がない場合 404。

POST /v1/library 無料（1 トークンクォータ）

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`）。

DELETE /v1/library/{id} 無料

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 キーの有効性を確認。トークンとユーザー情報を返します。クレジットは消費しません。

リクエスト

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

チャンネルがアップロードした全動画を 1 ページ約 100 件でページネーション。

パラメータ

名前	型	必須	説明
`channel`	string	1 ページ目	@handle、URL または UC… ID（エイリアス：`channel_id`）。
`continuation`	string	次ページ	前回の呼び出しで返されたトークン。

注意：channel と continuation はどちらか一方のみ指定してください。

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

YouTube プレイリストの動画をページネーションで取得。

パラメータ

名前	型	必須	説明
`playlist`	string	1 ページ目	プレイリスト URL または ID（`PL…`、`UU…`、`LL…`、`FL…`、`OL…`）。
`continuation`	string	次ページ	前回のレスポンスのトークン。

AI 文字起こし（ASR）

POST /v1/youtube/asr done 時 5 クレジット

非同期 AI Whisper 文字起こしを開始。task_id と ETA ヒントを返すので、適切な間隔でポーリングできます。

リクエストボディ（JSON）

名前	型	必須	説明
`video_url`	string	必須	YouTube URL（watch / youtu.be / shorts / embed）。
`lang`	string	任意	言語ヒント（例：`en`、`ja`）。省略で自動検出。

リクエスト

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} 無料

ASR タスクをポーリング。無料 — クレジット・トークンクォータ消費なし。タスクは作成者のみ読み取り可能。

レスポンス 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（ユーザーライブラリ）

GET /v1/library 無料

ユーザーが Library に保存した項目（文字起こし + 要約）を一覧。

パラメータ

名前	型	必須	説明
`favorite`	string	任意	`1` または `true` でお気に入りのみ。
`q`	string	任意	タイトル / 作者の部分一致。
`tag`	string	任意	タグでフィルタ。
`limit`	integer	任意	1–100（デフォルト 20）。
`offset`	integer	任意	ページネーションオフセット。

GET /v1/library/{id} 無料

単一 Library 項目のメタデータを取得。has_asr / has_summary を見て次にどのコンテンツ API を呼ぶか判断してください。

GET /v1/library/{id}/transcript 無料

Library 項目の ASR segments と連結テキストを取得。完了済みの ASR がない場合 404。

GET /v1/library/{id}/summary 無料

保存済み要約テキストを取得。?locale= で保存済み locale を選択（デフォルトは Accept-Language、次に en）。(video_id, locale) に要約がない場合 404。

POST /v1/library 無料（1 トークンクォータ）

リクエストボディ（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`）。

DELETE /v1/library/{id} 無料

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

→ 請求・レート制限・エラーコードはサポート & 請求を参照。