youtube/
videos

알고 있는 YouTube 동영상 또는 쇼츠 URL의 공개 메타데이터를 가져와 정규화된 제목, 채널 컨텍스트, 썸네일, 재생 시간, 공개된 참여 지표를 반환합니다.

YouTube Videos API

동영상 상세 정보
알고 있는 URL
공개 지표
결과당 0.5 크레딧
준비됨
준비됨

매개변수를 입력하고 요청을 전송하세요. 작업 상태와 정규화된 결과가 여기에 표시됩니다.

README

SocQ 작성 · 업데이트

YouTube Videos

YouTube 동영상은 제목, 설명, 채널 컨텍스트, 썸네일, 재생 시간, 게시 정보, 해시태그, 출처 분류, 공개된 참여 지표를 가진 공개 업로드입니다. 이러한 메타데이터와 성과 신호는 동영상 정보 보강, 콘텐츠 조사, 모니터링, 비교 분석에 활용할 수 있습니다.

YouTube Videos API 주요 기능

  • 알고 있는 URL 일괄 조회한 번의 요청으로 알고 있는 여러 공개 동영상 및 쇼츠 URL을 조회합니다.
  • 안정적인 동영상 식별 정보모든 결과에 대해 안정적인 동영상 ID, 정식 URL, 제목, 공개 설명, 게시 채널을 반환합니다.
  • 콘텐츠 메타데이터썸네일, 재생 시간, 해시태그, 게시일, 정규화된 콘텐츠 유형을 포함합니다.
  • 특정 시점의 참여 지표공개된 조회수·좋아요 수·댓글 수를 collected_at과 함께 수집하여 시점별 비교에 활용합니다.
  • 일관된 동영상 스키마일반 동영상과 지원되는 쇼츠 URL에 같은 정규화된 동영상 구조를 제공합니다.

YouTube Videos API 매개변수

매개변수필수설명
urls필수공개 YouTube 동영상 또는 쇼츠 URL로, 쉼표 또는 줄바꿈으로 구분합니다.

YouTube Videos API 사용 방법

링크 모음을 애플리케이션에서 조인·검색·갱신할 수 있는 레코드로 바꿔 줍니다. 요청은 비동기로 처리되므로, 접근 가능한 모든 URL의 조회가 끝날 때까지 작업 ID를 보관하세요.

  1. 공개 시청 URL 또는 쇼츠 URL을 모으고 중복을 제거합니다. 채널 URL과 검색 결과 URL은 다른 엔드포인트의 대상입니다.
  2. urls 배열을 /v1/youtube/videos로 POST하고, 반환된 task_id를 원본 배치와 함께 저장합니다.
  3. /v1/tasks/{task_id}를 폴링합니다. queued와 running은 배치가 아직 처리 중이라는 뜻입니다.
  4. 성공하면 data.results.items를 id 기준으로 색인하고, has_more가 true인 동안 next_cursor로 이어서 가져옵니다.
curl -X POST "https://api.socq.ai/v1/youtube/videos" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.youtube.com/watch?v=arj7oStGLkU"]}'

# Poll GET /v1/tasks/{task_id}
# Read GET /v1/tasks/{task_id}?limit=50

YouTube Videos API 추천 활용 사례

  • URL 목록 보강: 기존 YouTube URL 목록에 제목, 채널 정보, 썸네일, 재생 시간, 게시일, 공개 지표를 추가합니다.
  • 선택한 동영상 비교: 고른 동영상 또는 쇼츠 집합에서 공개 조회수, 좋아요 수, 댓글 수, 재생 시간, 게시 정보를 비교합니다.
  • 캠페인·경쟁사 모니터링: 알고 있는 캠페인, 크리에이터, 경쟁사 동영상의 메타데이터 스냅샷을 반복 수집합니다.
  • 콘텐츠 카탈로그: 정규화된 동영상 레코드를 내부 검색, 보고, 모더레이션, 요약, 분석 워크플로에 공급합니다.

YouTube Videos API 활용 팁

  • id를 기본 키로 삼으세요. 제목은 바뀔 수 있고, 같은 동영상이 여러 유효한 URL 형식으로 들어올 수 있습니다.
  • 외부로 나가는 링크에는 canonical_url을 쓰되, 레코드의 출처를 추적해야 할 때를 위해 input_url도 보관하세요.
  • 지표는 collected_at 시점의 페이지 상태를 나타냅니다. 스냅샷 두 개를 비교하면 유용하지만, 이전 스냅샷을 덮어쓰면 그 이력이 사라집니다.
  • 설명에 포함된 링크는 렌더링, 크롤링, 가져오기 전에 신뢰할 수 없는 외부 입력으로 취급하세요.
  • 결과가 없다고 해서 그 URL이 존재한 적이 없다는 증거는 아닙니다. 비공개·삭제·제한되었거나 일시적으로 접근할 수 없는 항목은 배치에서 빠질 수 있습니다.
  • 댓글과 스크립트 텍스트는 의도적으로 분리되어 있습니다. 워크플로에서 해당 단계에 도달한 항목에 대해서만 요청하세요.
  • 주제별 탐색은 Search로 시작하세요. 어떤 URL이 중요한지 이미 알고 있을 때 Videos를 사용하세요.

YouTube Videos API 외에 YouTube의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.

  • YouTube Channel Videos API — 채널 URL에서 쇼츠와 라이브 방송을 제외한 일반 공개 동영상을 수집합니다.
  • YouTube Comments API — 공개 댓글, 작성자, 참여도, 원본 동영상, 대화 맥락을 수집합니다.
  • YouTube Transcripts API — 제공되는 일반 텍스트 스크립트를 가져오며, 언어를 선택할 수 있습니다.
  • YouTube Channels API — 공개 채널 정보, 이미지, 인증 여부, 공개된 오디언스 통계를 가져옵니다.
  • YouTube Shorts API — 채널별로 공개 쇼츠, 썸네일, 길이, 게시 정보, 참여도를 수집합니다.
  • YouTube Related Videos API — 동영상 URL 옆에 추천되는 동영상을 나열하며, 제목, 채널, 조회수, 썸네일을 포함합니다.

다른 플랫폼 둘러보기

YouTube 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

YouTube Videos API — 자주 묻는 질문

YouTube Videos API는 알고 있는 YouTube 동영상 또는 쇼츠 URL의 공개 메타데이터를 가져옵니다. 정규화된 식별 정보, 제목, 설명, 채널 정보, 썸네일, 재생 시간, 게시일, 참여 지표, 수집 시각을 반환합니다.

urls 배열에 공개 YouTube 동영상 또는 쇼츠 URL을 하나 이상 제출합니다.

네. 공개 쇼츠 URL을 지원하며, 콘텐츠 유형을 보존한 채 같은 정규화된 동영상 구조를 사용합니다.

아니요. 지표는 수집 시점에 관측한 공개 값입니다. 과거 추이를 비교해야 한다면 collected_at을 저장하고 같은 URL을 다시 수집하세요.

동영상 결과에는 공개 댓글 수가 포함되며, 댓글 텍스트나 스크립트 텍스트는 포함되지 않습니다. 댓글 레코드는 Comments를, 이용 가능한 자막은 Transcripts를 사용하세요.

반환된 정규화 동영상 결과 1건당 0.5 크레딧이 차감됩니다.