# 유튜브 계정 정보 조회



유튜브 채널의 계정 정보와 최근 게시한 동영상 정보를 조회합니다.



인증: Authorization: Bearer $APICK_API_KEY

본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다.

인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다.



## POST /rest/crawl_youtube 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.type` (integer): 요청 타입(12, 고정) 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.result` (integer): 조회 결과 본문입니다. 서비스가 찾은 실제 데이터가 들어 있으며, 자료가 없거나 조회에 실패하면 null이거나 필드가 생략됩니다.

- `data.user` (object): 사용자(채널) 정보 하위 필드에 코드·이름·상태 같은 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다.

- `data.user.id` (string): 요청한 사용자(채널) 아이디. 대상의 고유 식별자입니다. 같은 대상을 다시 조회해도 같은 값이 옵니다.

- `data.user.channel_id` (string): 유튜브 채널의 고유 ID입니다. UC로 시작하는 24자리 문자열이며, 채널 URL보다 안정적으로 채널을 식별합니다.

- `data.user.name` (string): 대상의 표시 이름입니다. 같은 API에서도 사람·상품·채널 이름을 뜻할 수 있습니다.

- `data.user.handle` (string): 채널 핸들(@이름)입니다. 사용자가 지정한 표시용 주소이며, 변경될 수 있으므로 채널 ID와 함께 저장하세요. null 허용.

- `data.user.link` (string): 채널 페이지로 이동하는 전체 주소입니다. https://www.youtube.com/... 형식이며, 앱에서 바로 열 수 있습니다.

- `data.user.subscribe` (string): 구독자 수(읽기 쉬운 표기, 예: 1660만명). 비공개면 null 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `data.user.subscriber_count` (integer): 채널 구독자 수입니다. 비공개로 설정된 채널은 null이며, 0과 구분해 표시하세요. null 허용.

- `data.user.description` (string): 대상의 설명문입니다. 게시자·서비스가 작성한 소개문이며, 줄바꿈과 이모지가 포함될 수 있습니다. 비어 있으면 설명이 등록되지 않은 것입니다.

- `data.user.is_verified` (boolean): 채널이 유튜브 인증을 받았는지 여부입니다. true면 이름 옆 인증 배지가 표시됩니다. true = 운영처가 인증한 계정·채널인 경우, false = 인증 표시가 없는 경우입니다.

- `data.user.thumbnail` (string): 채널 프로필 이미지의 주소입니다. 크기가 다른 썸네일이 필요하면 URL의 크기 파라미터를 조정하세요.

- `data.user.posts` (array): 채널의 최근 업로드 영상 목록입니다. 최신순으로 최대 60개가 오며, 영상이 없으면 빈 배열입니다.

- `data.user.posts[].video_id` (string): 유튜브 영상의 고유 ID(11자리)입니다. https://youtu.be/<ID> 형식으로 바로 시청할 수 있습니다.

- `data.user.posts[].thumbnail_link` (string): 영상 썸네일 이미지의 주소입니다. 영상 ID로 만든 기본 썸네일과 다를 수 있습니다.

- `data.user.posts[].contents` (string): 영상의 제목입니다. 줄바꿈·이모지가 포함될 수 있으며, 길면 말줄임 없이 전체가 올 수 있습니다.

- `data.user.posts[].view_count` (string): 영상 조회수입니다. 확인할 수 없으면 null이며, 0과 구분해 표시하세요. null 허용.

- `data.user.posts[].duration` (integer): 영상 길이(초). 확인되지 않으면 null 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. null 허용.

- `data.user.posts[].thumbnail` (string): 썸네일 이미지 URL 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.success` (integer): 업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (integer): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.ms` (integer): 서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.

- `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

## API 요청: POST /rest/crawl_youtube



### 입력

- `user_id` (string, 필수): 조회할 유튜브 채널 아이디(예: CNN)·핸들(@CNN)·채널 ID(UC…) 또는 채널 URL



### 응답 명세

```json

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "type": {
          "type": "integer",
          "description": "요청 타입(12, 고정)"
        },
        "result": {
          "type": "integer",
          "description": "조회 결과1: 성공"
        },
        "user": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "요청한 사용자(채널) 아이디"
            },
            "channel_id": {
              "type": "string",
              "description": "채널 ID(UC로 시작)"
            },
            "name": {
              "type": "string",
              "description": "채널 이름"
            },
            "handle": {
              "type": "string",
              "description": "채널 핸들(@이름). 없으면 null",
              "nullable": true
            },
            "link": {
              "type": "string",
              "description": "채널 URL"
            },
            "subscribe": {
              "type": "string",
              "description": "구독자 수(읽기 쉬운 표기, 예: 1660만명). 비공개면 null",
              "nullable": true
            },
            "subscriber_count": {
              "type": "integer",
              "description": "구독자 수(숫자). 비공개면 null",
              "nullable": true
            },
            "description": {
              "type": "string",
              "description": "채널 설명"
            },
            "is_verified": {
              "type": "boolean",
              "description": "인증 배지 여부"
            },
            "thumbnail": {
              "type": "string",
              "description": "채널 프로필 이미지 URL"
            },
            "posts": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "video_id": {
                    "type": "string",
                    "description": "영상 ID"
                  },
                  "thumbnail_link": {
                    "type": "string",
                    "description": "영상 URL"
                  },
                  "contents": {
                    "type": "string",
                    "description": "영상 제목"
                  },
                  "view_count": {
                    "type": "string",
                    "description": "조회수. 확인되지 않으면 null",
                    "nullable": true
                  },
                  "duration": {
                    "type": "integer",
                    "description": "영상 길이(초). 확인되지 않으면 null",
                    "nullable": true
                  },
                  "thumbnail": {
                    "type": "string",
                    "description": "썸네일 이미지 URL"
                  }
                }
              },
              "description": "최근 업로드 영상 목록(최대 60개, 최신순)"
            }
          },
          "description": "사용자(채널) 정보"
        },
        "success": {
          "type": "integer",
          "description": "과금 여부0: 실패1: 성공"
        }
      },
      "description": "조회 데이터"
    },
    "api": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "API 서버 정상 응답 여부"
        },
        "cost": {
          "type": "integer",
          "description": "API 호출 요금"
        },
        "ms": {
          "type": "integer",
          "description": "API 응답 시간"
        },
        "pl_id": {
          "type": "integer",
          "description": "API 결제 로그 ID"
        }
      },
      "description": "API 호출 공통 데이터"
    }
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "type": 12,
    "result": 1,
    "user": {
      "id": "CNN",
      "channel_id": "UCupvZG-5ko_eiXAupbDfxWw",
      "name": "CNN",
      "handle": "@CNN",
      "link": "https://www.youtube.com/@CNN",
      "subscribe": "1840만명",
      "subscriber_count": 18400000,
      "description": "CNN is the world leader in news and information and seeks to inform, engage and empower the world.",
      "is_verified": true,
      "thumbnail": "https://yt3.googleusercontent.com/...",
      "posts": [
        {
          "video_id": "obAFI1Anj90",
          "thumbnail_link": "https://www.youtube.com/watch?v=obAFI1Anj90",
          "contents": "Watch CNN's live coverage",
          "view_count": "4031",
          "duration": 512,
          "thumbnail": "https://i.ytimg.com/vi/obAFI1Anj90/hqdefault.jpg"
        }
      ]
    },
    "success": 1
  },
  "api": {
    "success": true,
    "cost": 40,
    "ms": 3120,
    "pl_id": 9697516
  }
}

```

### curl

```curl

curl --fail-with-body --request POST 'https://apick.app/rest/crawl_youtube' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'user_id=CNN'

```

### Node.js (서버 ESM)

```javascript

const form = new FormData();
form.append("user_id", "CNN");
const response = await fetch("https://apick.app/rest/crawl_youtube", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

```

### python

```python

import os
import requests
parts = [
    ("user_id", (None, "CNN")),
]
response = requests.request("POST", "https://apick.app/rest/crawl_youtube",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'user_id' => 'CNN',
];
$curl = curl_init('https://apick.app/rest/crawl_youtube');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

```

## 사용 예시 1. 채널 아이디로 채널 정보와 최근 영상 받기

채널 주소 끝의 이름(예: youtube.com/@CNN 의 CNN)만 알고 있을 때 가장 간단한 요청입니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/crawl_youtube' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'user_id=CNN'

```

- `data.user.name`·`data.user.subscriber_count`로 채널 이름과 구독자 수(숫자)를 표시합니다. 화면에 그대로 쓸 표기는 `data.user.subscribe`(예: 1840만명)입니다.

- `data.user.posts[]`에 최근 업로드 영상이 최신순으로 최대 60개 옵니다. `video_id`를 영상 정보·댓글 조회 API의 `url`에 그대로 넣을 수 있습니다.

- 구독자 수를 숨긴 채널은 `data.user.subscriber_count`가 null입니다. 0으로 바꿔 저장하지 마세요.

## 사용 예시 2. 채널 ID로 정확히 조회

핸들(@이름)은 채널 운영자가 바꿀 수 있으므로, 같은 채널을 계속 추적할 때는 UC로 시작하는 24자 채널 ID를 보냅니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/crawl_youtube' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'user_id=UCupvZG-5ko_eiXAupbDfxWw'

```

- `data.user.channel_id`를 내 시스템의 채널 키로 저장하면 핸들이 바뀌어도 같은 채널로 묶을 수 있습니다.

- `data.user.id`에는 요청에 보낸 값이 그대로 돌아옵니다.

## 사용 예시 3. 채널 주소를 그대로 붙여 넣기

사용자가 복사한 채널 주소를 그대로 입력하는 화면이라면 주소를 가공하지 않고 보내면 됩니다. /@핸들, /channel/UC…, /c/이름, /user/이름 형식을 받습니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/crawl_youtube' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'user_id=https://www.youtube.com/@CNN'

```

- 없는 채널이면 HTTP 404와 `data.error` 안내 문구가 오며 과금되지 않습니다.

- 영상 주소(watch?v=…)는 채널 주소가 아니므로 입력 오류(HTTP 400)가 됩니다.

## 코드·오류

### 업무 실패 응답

입력 오류·대상 없음·일시 실패는 data.error(사유)와 data.success=0으로 오며 api.cost는 0(과금 없음)입니다. HTTP 상태는 400·404·408·424 중 하나입니다. 입력 오류는 값을 고쳐 다시 요청하고, 408·424는 잠시 후 한 번 다시 시도하세요.

```json

{
  "data": {
    "error": "입력값을 확인해 주세요.",
    "success": 0
  },
  "api": {
    "success": true,
    "cost": 0,
    "ms": 5
  }
}

```

## 상세 기능·요금

사용 방법 user_id 하나로 유튜브 채널의 기본 정보(이름·핸들·구독자 수·설명·인증 여부·프로필 이미지)와 최근 업로드 영상 최대 60개를 한 번에 받습니다. user_id에는 채널 아이디(예: CNN), 핸들(@CNN), 채널 ID(UC로 시작하는 24자), 채널 주소(/@핸들·/channel/UC…·/c/이름·/user/이름) 중 하나를 보냅니다. 영상 주소는 받지 않습니다. 같은 채널을 계속 추적한다면 응답의 data.user.channel_id를 저장해 다음 요청에 쓰세요. 핸들은 운영자가 바꿀 수 있습니다. 쇼츠·라이브·재생목록 탭이나 받을 개수를 직접 고르려면 유튜브 채널 조회 API를 쓰세요. 응답까지 최대 1분 정도 걸릴 수 있습니다. 클라이언트 제한 시간은 90초 이상으로 두세요. 입력 오류·채널 없음·시간 초과 등 실패한 호출은 과금되지 않습니다. Method URL POST https://apick.app/rest/crawl_youtube

## 상세 요청

Header 이름 필수 설명 Authorization 필수 Bearer 인증키

## 상세 응답

Body 필드 타입 설명 data Object 조회 데이터 type Integer 요청 타입(12, 고정) result Integer 조회 결과1: 성공 user Object 사용자(채널) 정보 id String 요청한 사용자(채널) 아이디 channel_id String 채널 ID(UC로 시작) name String 채널 이름 handle String 채널 핸들(@이름). 없으면 null link String 채널 URL subscribe String 구독자 수(읽기 쉬운 표기, 예: 1660만명). 비공개면 null subscriber_count Integer 구독자 수(숫자). 비공개면 null description String 채널 설명 is_verified Boolean 인증 배지 여부 thumbnail String 채널 프로필 이미지 URL posts Array 최근 업로드 영상 목록(최대 60개, 최신순) {} Object 영상 정보 video_id String 영상 ID thumbnail_link String 영상 URL contents String 영상 제목 view_count String 조회수. 확인되지 않으면 null duration Integer 영상 길이(초). 확인되지 않으면 null thumbnail String 썸네일 이미지 URL success Integer 과금 여부0: 실패1: 성공 api Object API 호출 공통 데이터 success Boolean API 서버 정상 응답 여부 cost Integer API 호출 요금 ms Integer API 응답 시간 pl_id Integer API 결제 로그 ID 응답 확인 HTTP 200이고 data.result가 1이면 성공입니다. 실패 응답에는 data.error에 안내 문구가 담기며 api.cost는 0입니다. data.user.posts[]는 최신 업로드 순입니다. 영상이 없는 채널은 빈 배열입니다. data.user.subscriber_count(숫자)는 계산·정렬에, data.user.subscribe(예: 1840만명)는 화면 표시에 씁니다. 구독자 수를 숨긴 채널은 둘 다 null입니다. data.user.posts[].view_count는 문자열 숫자입니다. 계산 전에 숫자로 바꾸고, null이면 조회수가 제공되지 않은 영상입니다.

## 상세 코드·정책

오류 HTTP 상태 코드 HTTP 상황 설명 400 입력 오류 user_id가 비었거나 채널 아이디·핸들·채널 ID·채널 주소 형식이 아닙니다. 과금되지 않습니다. 404 채널 없음 없는 채널이거나 잘못된 주소·핸들입니다. 과금되지 않습니다. 408 시간 초과 처리 시간이 초과됐습니다. 잠시 후 다시 요청하세요. 과금되지 않습니다. 424 조회 실패 결과를 받지 못해 실패로 끝났습니다. 잠시 후 다시 요청하세요. 과금되지 않습니다.

## 상세 예제

요청 예시 form-data 전체 예제 보기 응답 예시 { "data": { "type": 12, "result": 1, "user": { "id": "CNN", "channel_id": "UCupvZG-5ko_eiXAupbDfxWw", "name": "CNN", "handle": "@CNN", "link": "https://www.youtube.com/@CNN", "subscribe": "1840만명", "subscriber_count": 18400000, "description": "CNN is the world leader in news and information and seeks to inform, engage and empower the world.", "is_verified": true, "thumbnail": "https://yt3.googleusercontent.com/...", "posts": [ { "video_id": "obAFI1Anj90", "thumbnail_link": "https://www.youtube.com/watch?v=obAFI1Anj90", "contents": "Watch CNN's live coverage", "view_count": "4031", "duration": 512, "thumbnail": "https://i.ytimg.com/vi/obAFI1Anj90/hqdefault.jpg" } ] }, "success": 1 }, "api": { "success": true, "cost": 40, "ms": 3120, "pl_id": 9697516 } }
