개발자 문서는 영어로 제공됩니다. 사이드바는 선택한 언어를 따릅니다.

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

채널이 업로드한 모든 영상을 페이지당 약 100개로 페이지네이션.

파라미터

이름	타입	필수	설명
`channel`	string	첫 페이지	@handle, URL 또는 UC… ID(별칭: `channel_id`).
`continuation`	string	다음 페이지	이전 호출에서 반환된 토큰.

참고: channel 또는 continuation 중 하나만 지정하세요.

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

YouTube 재생목록의 영상을 페이지네이션으로 가져오기.

파라미터

이름	타입	필수	설명
`playlist`	string	첫 페이지	재생목록 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`, `ko` 등). 생략 시 자동 감지.

요청

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 작업을 폴링. 무료 — 크레딧·토큰 쿼터 소비 없음. 생성자만 읽을 수 있습니다.

상태: 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 플래그로 다음 호출할 콘텐츠 엔드포인트를 판단하세요.

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

채널이 업로드한 모든 영상을 페이지당 약 100개로 페이지네이션.

파라미터

이름	타입	필수	설명
`channel`	string	첫 페이지	@handle, URL 또는 UC… ID(별칭: `channel_id`).
`continuation`	string	다음 페이지	이전 호출에서 반환된 토큰.

참고: channel 또는 continuation 중 하나만 지정하세요.

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

YouTube 재생목록의 영상을 페이지네이션으로 가져오기.

파라미터

이름	타입	필수	설명
`playlist`	string	첫 페이지	재생목록 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`, `ko` 등). 생략 시 자동 감지.

요청

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 작업을 폴링. 무료 — 크레딧·토큰 쿼터 소비 없음. 생성자만 읽을 수 있습니다.

상태: 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 플래그로 다음 호출할 콘텐츠 엔드포인트를 판단하세요.

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

→ 결제, 속도 제한, 오류 코드는 지원 및 결제 참고.