> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTube API

> YouTube를 검색하고 동영상, 댓글, 채널, 채널 업로드, 자막을 JSON으로 읽습니다. 조회수, 좋아요, 게시 시각, 챕터, 자막 텍스트를 함께 받습니다.

공개 YouTube 데이터를 비동기 task API로 JSON으로 읽습니다. `taskType` `SOCIAL`에 `platform` `youtube`를 보내고 `action`으로 읽을 대상을 고릅니다. 완료된 요청당 **0.5크레딧**입니다.

## 요청

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "SOCIAL", "payload": { "platform": "youtube", "action": "search", "query": "wireless earbuds review", "limit": 10 } }'
```

task를 제출한 뒤 `GET /v1/async/task/{id}`를 폴링하거나 웹훅으로 받습니다. 참고: [비동기 task](https://docs.querying.ai/ko/concepts/async-tasks.md).

## 동작

| `action` | 읽는 대상 | 필수 |
| - | - | - |
| `search` (기본값) | YouTube 검색 결과 | `query` |
| `recent` | 검색어의 최신 업로드, 최신순 | `query` |
| `video` | 동영상 하나의 시청 페이지 | `videoId` |
| `comments` | 동영상의 댓글과 답글 | `videoId` |
| `channel` | 채널 정보와 링크 | `channel` |
| `channel_videos` | 채널의 동영상, Shorts, 라이브 스트림 | `channel` |
| `transcript` | 동영상 자막 | `videoId` |

`videoId`는 동영상 ID나 YouTube 동영상 URL(시청 페이지, `youtu.be`, Shorts, 퍼가기)을 받습니다. `channel`은 채널 ID(`UC...`), `@handle`, 채널 URL을 받습니다.

## 입력

`search`와 `recent`:

* `query`: 필수. 검색어입니다.
* `limit`: 선택. 정수 1-50이며 기본값은 10입니다.
* `type`: `video`(기본값), `all`, `shorts`, `channel`, `playlist`, `movie` 중 하나입니다.
* `order`: `relevance`(기본값), `viewCount`, `date`, `rating` 중 하나입니다. `date`는 `recent`처럼 최신 업로드부터 나열합니다. `rating`은 YouTube의 조회수 상위 결과를 좋아요 수로 정렬합니다. `channel`과 `playlist` 검색은 `relevance`나 `viewCount`를 받습니다.
* `publishedAfter`: `2026-11-01T00:00:00Z` 같은 ISO 8601 시각입니다. 이 시각 뒤에 게시된 동영상을 돌려줍니다.
* `videoDuration`: `short`(3분 미만), `medium`(3-20분), `long`(20분 초과) 중 하나입니다.
* `features`: `live`, `4k`, `hd`, `subtitles`, `creative_commons`, `360`, `vr180`, `3d`, `hdr`, `location`, `purchased` 중 원하는 값을 배열이나 쉼표로 구분한 문자열로 보냅니다.
* `exactSpelling`: `true`이면 YouTube의 맞춤법 교정 없이 입력한 그대로 검색합니다.
* `pageToken`: 이전 페이지의 `nextPageToken`입니다. `publishedAfter` 없이 `relevance`나 `viewCount`로 정렬한 동영상 검색이 이 값을 돌려주며, 각 페이지는 앞 페이지들이 돌려준 동영상을 모두 건너뜁니다.
* `regionCode`와 `languageCode`: 검색할 YouTube 지역(`US`, `KR`, `JP`)과 인터페이스 언어(`en`, `ko`, `ja`)입니다.

`comments`:

* `limit`: 선택. 정수 1-500이며 기본값은 100입니다. 답글도 개수에 포함됩니다.
* `order`: `relevance`(기본값, YouTube의 인기 댓글)나 `time`(최신순)입니다.
* `includeReplies`: 선택. 기본값은 `true`입니다.

`channel_videos`:

* `tab`: `videos`(기본값), `shorts`, `streams` 중 하나입니다.
* `sort`: `latest`(기본값), `popular`, `oldest` 중 하나입니다.
* `limit`: 선택. 정수 1-50이며 기본값은 20입니다.

`transcript`:

* `languages`: `["en", "ko"]`처럼 원하는 순서로 나열한 자막 언어입니다. 없으면 동영상의 기본 자막, 영어 자막, 첫 번째 트랙 순으로 읽습니다.
* `isGenerated`: `true`이면 자동 생성 자막만, `false`이면 업로더가 올린 자막만 읽습니다.
* `trackName`: 읽을 자막 트랙의 이름입니다.
* `translateTo`: 언어 코드입니다. YouTube가 자막을 이 언어로 번역합니다.
* `maxSegments`: 선택. 정수 1-5,000이며 기본값은 2,000입니다.

## 응답 예시

```json theme={"theme":"css-variables"}
{
  "platform": "youtube",
  "action": "search",
  "query": "wireless earbuds review",
  "order": "relevance",
  "totalResults": 4523475,
  "returnedCount": 1,
  "videos": [
    {
      "position": 1,
      "videoId": "YdJh6QdOGME",
      "url": "https://www.youtube.com/watch?v=YdJh6QdOGME",
      "title": "Earbuds Awards 2026 - Best Bluetooth Earbuds by Category!",
      "channelId": "UCZZ4ivUawsXRktLKej8d6Xw",
      "channelTitle": "Mike O'Brien",
      "channelHandle": "@MikeOBrienMedia",
      "channelIsVerified": true,
      "publishedAt": "2026-11-17T15:39:37Z",
      "publishedTimeText": "21 hours ago",
      "duration": "PT16M35S",
      "durationSeconds": 995,
      "viewCount": 62618,
      "likeCount": 957,
      "category": "Science & Technology",
      "badges": ["New"],
      "thumbnails": { "high": "https://i.ytimg.com/vi/YdJh6QdOGME/hqdefault.jpg" }
    }
  ],
  "nextPageToken": "eyJyIjpbIllkSmg2UWRPR01FIl19"
}
```

## 결과 필드

* 모든 응답은 `platform`과 `action`을 그대로 돌려줍니다. 목록에는 `returnedCount`가 있습니다.
* `search`와 `recent`는 `videos`를 돌려줍니다. 각 동영상에는 `position`, `videoId`, `url`, `title`, `description`, 채널의 `channelId`, `channelTitle`, `channelHandle`, `channelUrl`, `channelThumbnail`, `channelIsVerified`, `publishedAt`, `publishedTimeText`, `duration`(ISO 8601), `durationSeconds`, `viewCount`, `likeCount`, `category`, `thumbnails`, `richThumbnail`(움직이는 미리보기), `badges`, `isFamilySafe`가 있습니다. 영화에는 포스터, 장르, 연도, 출연진, 감독을 담은 `movie`가 더해집니다.
* 검색은 결과 페이지에 보이는 `channels`, `playlists`, `shorts`, `shelves`와 `totalResults`(YouTube의 추정치)도 돌려주고, YouTube가 검색어를 교정하면 `didYouMean`이나 `showingResultsFor`를 돌려줍니다.
* `video`는 `tags`, `commentCount`, `subscriberCount`, `hasCaptions`, `chapters`, `mostReplayed`, `music`, `descriptionLinks`, `relatedVideos`를 더합니다. 업로더가 만든 챕터가 먼저 오고, 자동 챕터에는 `autoGenerated: true`가 붙습니다.
* `comments`는 `comments`를 돌려줍니다. 각 댓글에는 `commentId`, `parentId`(최상위 댓글은 `null`), `text`, `authorDisplayName`, `authorChannelId`, `authorProfileImageUrl`, `authorIsVerified`, `authorIsChannelOwner`, `isPinned`, `isHearted`, `likeCount`, `replyCount`, `publishedAt`, `updatedAt`이 있습니다. `totalCount`는 YouTube가 보여 주는 댓글 수이고, `topLevelCount`와 `replyCount`는 `returnedCount`를 나눈 값입니다.
* `channel`은 `channelId`, `title`, `handle`, `description`, `country`, `publishedAt`, `subscriberCount`, `videoCount`, `viewCount`, `isVerified`, `keywords`, `links`, `thumbnails`, `bannerUrl`, `rssUrl`, `uploadsPlaylistId`를 돌려줍니다.
* `channel_videos`는 `sort` 순서의 `videos`와 채널의 `channelId`, `channelTitle`을 돌려줍니다.
* `transcript`는 자막 `text`, 시간이 붙은 `segments`(`start`와 `duration`, 초 단위), 읽은 `language`, `availableLanguages`를 돌려줍니다. `truncated: true`는 `maxSegments`에서 잘린 자막입니다.
* 좋아요 수를 숨긴 동영상에는 `likesHidden: true`, 댓글을 끈 동영상에는 `commentsDisabled: true`가 붙습니다. 회원 전용 동영상에는 `membersOnly: true`가 붙고 `viewCount`가 없습니다.
* 없는 동영상, 채널, 자막 트랙이나 연령 제한 동영상처럼 로그인한 시청자만 볼 수 있는 대상은 task를 `PAGE_UNAVAILABLE`로 끝냅니다. 함께 쓸 수 없는 파라미터는 task를 `BAD_PAYLOAD`로 끝냅니다. 완료된 요청만 과금합니다.

## 관련 문서

* [Instagram](https://docs.querying.ai/ko/engines/instagram.md)
* [Threads](https://docs.querying.ai/ko/engines/threads.md)
* [엔진 목록](https://docs.querying.ai/ko/engines/overview.md)
* [크레딧과 한도](https://docs.querying.ai/ko/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.