YouTube API

YouTube API를 사용하면 단일 통합 인터페이스를 통해 YouTube를 검색하고 동영상 메타데이터를 가져올 수 있습니다. 각 엔드포인트는 크레딧 사용량 추적 정보와 함께 구조화된 JSON을 반환합니다.

엔드포인트

엔드포인트	설명
`POST /api/v1/youtube/search`	필터(날짜, 길이, 유형, 화질)로 YouTube 검색
`POST /api/v1/youtube/metadata`	동영상의 구조화된 메타데이터 가져오기 (조회수, 좋아요, 태그, 설명)

인증

헤더	값	필수
`Authorization`	`Bearer YOUR_API_KEY`	예
`Content-Type`	`application/json`	예

YouTube 검색

Bash

POST https://api.scavio.dev/api/v1/youtube/search

YouTube를 검색하고 구조화된 결과를 얻습니다. 업로드 날짜, 길이, 결과 유형, 화질 등으로 필터링을 지원합니다.

요청 본문

파라미터	유형	기본값	설명
`search`	`string`	--	필수. 검색어 (1-500자).
`upload_date`	`string`	--	업로드 날짜로 필터링. 값: `last_hour`, `today`, `this_week`, `this_month`, `this_year`
`type`	`string`	--	결과 유형으로 필터링. 값: `video`, `channel`, `playlist`
`duration`	`string`	--	동영상 길이로 필터링. 값: `short` (4분 미만),`medium` (4-20분), `long` (20분 초과)
`sort_by`	`string`	`relevance`	정렬 순서. 값: `relevance`, `date`, `view_count`, `rating`
`hd`	`boolean`	`false`	HD 동영상만
`4k`	`boolean`	`false`	4K 동영상만
`subtitles`	`boolean`	`false`	자막/캡션이 있는 동영상만
`creative_commons`	`boolean`	`false`	Creative Commons 라이선스 동영상만
`live`	`boolean`	`false`	라이브 스트리밍만
`hdr`	`boolean`	`false`	HDR 동영상만
`360`	`boolean`	`false`	360도 동영상만
`3d`	`boolean`	`false`	3D 동영상만
`location`	`boolean`	`false`	위치 메타데이터가 있는 동영상만
`vr180`	`boolean`	`false`	VR180 동영상만

예시

curl -X POST 'https://api.scavio.dev/api/v1/youtube/search' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "search": "langchain tutorial",
    "type": "video",
    "duration": "medium",
    "sort_by": "view_count",
    "upload_date": "this_year"
  }'

응답 예시

JSON

{
  "data": {
    "results": [
      {
        "videoId": "sVcwVQRHIc8",
        "title": { "runs": [{ "text": "Learn RAG From Scratch - Python AI Tutorial" }] },
        "longBylineText": { "runs": [{ "text": "freeCodeCamp.org" }] },
        "publishedTimeText": { "simpleText": "1 year ago" },
        "lengthText": { "simpleText": "2:33:11" },
        "viewCountText": { "simpleText": "1,258,310 views" },
        "thumbnail": { "thumbnails": [{ "url": "https://i.ytimg.com/vi/sVcwVQRHIc8/hq720.jpg", "width": 360, "height": 202 }] }
      }
    ],
    "search": "langchain tutorial"
  },
  "response_time": 1230,
  "credits_used": 1,
  "credits_remaining": 999
}

동영상 메타데이터

Bash

POST https://api.scavio.dev/api/v1/youtube/metadata

YouTube 동영상의 구조화된 메타데이터를 가져옵니다. 제목, 설명, 조회수, 좋아요 수, 댓글 수, 태그, 썸네일, 업로드 날짜, 채널 정보, 사용 가능한 형식 등이 포함됩니다.

요청 본문

파라미터	유형	설명
`video_id`	`string`	필수. YouTube 동영상 ID (예: `dQw4w9WgXcQ`).

예시

curl -X POST 'https://api.scavio.dev/api/v1/youtube/metadata' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{"video_id": "sVcwVQRHIc8"}'

응답 예시

JSON

{
  "data": {
    "title": "Learn RAG From Scratch - Python AI Tutorial",
    "description": "Learn how to implement RAG from scratch...",
    "upload_date": 20240417,
    "duration": 9191,
    "view_count": 1258310,
    "like_count": 23211,
    "comment_count": 295,
    "categories": ["Education"],
    "tags": ["rag", "langchain", "python", "llm"],
    "channel_id": "UC8butISFwT-Wl7EV0hUK0BQ",
    "channel_url": "https://www.youtube.com/channel/UC8butISFwT-Wl7EV0hUK0BQ",
    "uploader": "freeCodeCamp.org",
    "uploader_id": "@freecodecamp",
    "uploader_url": "https://www.youtube.com/@freecodecamp",
    "video_id": "sVcwVQRHIc8",
    "is_live": false,
    "age_limit": 0,
    "thumbnails": [
      {
        "url": "https://i.ytimg.com/vi/sVcwVQRHIc8/maxresdefault.jpg",
        "width": 1280,
        "height": 720
      }
    ],
    "formats": []
  },
  "response_time": 890,
  "credits_used": 1,
  "credits_remaining": 998
}

응답 형식

모든 YouTube 엔드포인트는 일관된 응답 래퍼를 반환합니다.

필드	유형	설명
`data`	`object \| null`	응답 페이로드입니다. 형태는 엔드포인트에 따라 다릅니다. 검색은 `{results, search}`를 반환하고, 메타데이터는 동영상 객체를 반환합니다. 상위 요청이 실패하면 `null`입니다.
`response_time`	`number`	서버 측 응답 시간(밀리초)
`credits_used`	`number`	이 요청에 사용된 크레딧 수
`credits_remaining`	`number`	현재 결제 기간에 남은 크레딧

오류 응답

상태	설명
`401`	인증되지 않음 -- API 키가 없거나 유효하지 않음
`429`	요금제의 속도 또는 사용량 한도 초과
`502`	상위 오류 -- 잠시 후 재시도
`503`	상위 서비스를 사용할 수 없음 -- 나중에 재시도

전체 오류 참조 및 재시도 모범 사례는 오류를 참조하세요.

YouTube API

엔드포인트

엔드포인트	설명
`POST /api/v1/youtube/search`	필터(날짜, 길이, 유형, 화질)로 YouTube 검색
`POST /api/v1/youtube/metadata`	동영상의 구조화된 메타데이터 가져오기 (조회수, 좋아요, 태그, 설명)

인증

헤더	값	필수
`Authorization`	`Bearer YOUR_API_KEY`	예
`Content-Type`	`application/json`	예

YouTube 검색

Bash

POST https://api.scavio.dev/api/v1/youtube/search

YouTube를 검색하고 구조화된 결과를 얻습니다. 업로드 날짜, 길이, 결과 유형, 화질 등으로 필터링을 지원합니다.

요청 본문

파라미터	유형	기본값	설명
`search`	`string`	--	필수. 검색어 (1-500자).
`upload_date`	`string`	--	업로드 날짜로 필터링. 값: `last_hour`, `today`, `this_week`, `this_month`, `this_year`
`type`	`string`	--	결과 유형으로 필터링. 값: `video`, `channel`, `playlist`
`duration`	`string`	--	동영상 길이로 필터링. 값: `short` (4분 미만),`medium` (4-20분), `long` (20분 초과)
`sort_by`	`string`	`relevance`	정렬 순서. 값: `relevance`, `date`, `view_count`, `rating`
`hd`	`boolean`	`false`	HD 동영상만
`4k`	`boolean`	`false`	4K 동영상만
`subtitles`	`boolean`	`false`	자막/캡션이 있는 동영상만
`creative_commons`	`boolean`	`false`	Creative Commons 라이선스 동영상만
`live`	`boolean`	`false`	라이브 스트리밍만
`hdr`	`boolean`	`false`	HDR 동영상만
`360`	`boolean`	`false`	360도 동영상만
`3d`	`boolean`	`false`	3D 동영상만
`location`	`boolean`	`false`	위치 메타데이터가 있는 동영상만
`vr180`	`boolean`	`false`	VR180 동영상만

예시

curl -X POST 'https://api.scavio.dev/api/v1/youtube/search' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "search": "langchain tutorial",
    "type": "video",
    "duration": "medium",
    "sort_by": "view_count",
    "upload_date": "this_year"
  }'

응답 예시

JSON

{
  "data": {
    "results": [
      {
        "videoId": "sVcwVQRHIc8",
        "title": { "runs": [{ "text": "Learn RAG From Scratch - Python AI Tutorial" }] },
        "longBylineText": { "runs": [{ "text": "freeCodeCamp.org" }] },
        "publishedTimeText": { "simpleText": "1 year ago" },
        "lengthText": { "simpleText": "2:33:11" },
        "viewCountText": { "simpleText": "1,258,310 views" },
        "thumbnail": { "thumbnails": [{ "url": "https://i.ytimg.com/vi/sVcwVQRHIc8/hq720.jpg", "width": 360, "height": 202 }] }
      }
    ],
    "search": "langchain tutorial"
  },
  "response_time": 1230,
  "credits_used": 1,
  "credits_remaining": 999
}

동영상 메타데이터

Bash

POST https://api.scavio.dev/api/v1/youtube/metadata

요청 본문

파라미터	유형	설명
`video_id`	`string`	필수. YouTube 동영상 ID (예: `dQw4w9WgXcQ`).

예시

curl -X POST 'https://api.scavio.dev/api/v1/youtube/metadata' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{"video_id": "sVcwVQRHIc8"}'

응답 예시

JSON

{
  "data": {
    "title": "Learn RAG From Scratch - Python AI Tutorial",
    "description": "Learn how to implement RAG from scratch...",
    "upload_date": 20240417,
    "duration": 9191,
    "view_count": 1258310,
    "like_count": 23211,
    "comment_count": 295,
    "categories": ["Education"],
    "tags": ["rag", "langchain", "python", "llm"],
    "channel_id": "UC8butISFwT-Wl7EV0hUK0BQ",
    "channel_url": "https://www.youtube.com/channel/UC8butISFwT-Wl7EV0hUK0BQ",
    "uploader": "freeCodeCamp.org",
    "uploader_id": "@freecodecamp",
    "uploader_url": "https://www.youtube.com/@freecodecamp",
    "video_id": "sVcwVQRHIc8",
    "is_live": false,
    "age_limit": 0,
    "thumbnails": [
      {
        "url": "https://i.ytimg.com/vi/sVcwVQRHIc8/maxresdefault.jpg",
        "width": 1280,
        "height": 720
      }
    ],
    "formats": []
  },
  "response_time": 890,
  "credits_used": 1,
  "credits_remaining": 998
}

응답 형식

모든 YouTube 엔드포인트는 일관된 응답 래퍼를 반환합니다.

필드	유형	설명
`data`	`object \| null`	응답 페이로드입니다. 형태는 엔드포인트에 따라 다릅니다. 검색은 `{results, search}`를 반환하고, 메타데이터는 동영상 객체를 반환합니다. 상위 요청이 실패하면 `null`입니다.
`response_time`	`number`	서버 측 응답 시간(밀리초)
`credits_used`	`number`	이 요청에 사용된 크레딧 수
`credits_remaining`	`number`	현재 결제 기간에 남은 크레딧

오류 응답

상태	설명
`401`	인증되지 않음 -- API 키가 없거나 유효하지 않음
`429`	요금제의 속도 또는 사용량 한도 초과
`502`	상위 오류 -- 잠시 후 재시도
`503`	상위 서비스를 사용할 수 없음 -- 나중에 재시도

전체 오류 참조 및 재시도 모범 사례는 오류를 참조하세요.

YouTube API

엔드포인트

인증

YouTube 검색

요청 본문

예시

응답 예시

동영상 메타데이터

요청 본문

예시

응답 예시

응답 형식

오류 응답

관련 항목

YouTube API

엔드포인트

인증

YouTube 검색

요청 본문

예시

응답 예시

동영상 메타데이터

요청 본문

예시

응답 예시

응답 형식

오류 응답

관련 항목