TwitchTwitch 클립동영상 다운로드스트리밍API 가이드

Twitch 클립 다운로더 API: 클립 조회수, 스트리머, 동영상 파일 가져오기

SocQ의 새 Twitch Clip Downloader API는 클립 URL 하나로 제목, 조회수, 길이, 생성 시각, 스트리머, 다운로드 가능한 MP4 링크를 0.5 크레딧에 반환합니다.

SocQ2026년 11월 19일 업데이트약 5분 소요

클립은 시청자가 Twitch 방송에서 잘라 낸 짧은 하이라이트로, X, Reddit, Discord에서 공유되는 콘텐츠입니다. 인상적인 순간을 보관하거나, 클립이 얼마나 퍼졌는지 측정하거나, 다시 게시할 때 올바른 채널을 표기해야 한다면 클립 데이터와 동영상 파일을 코드에서 저장할 수 있는 형태로 받아야 합니다.

2026-11-17 SocQ는 Twitch Clip Downloader API를 기존 Twitch Profile, User Videos 엔드포인트가 있는 Twitch 플랫폼 페이지에 추가했습니다. 이 가이드에서는 반환 내용, 요청, 가격, 그리고 미리 고려해야 할 제한 사항을 다룹니다.

빠른 답변: POST https://api.socq.ai/v1/twitch/clip에 {"url": "<clip URL>"}을 보내세요. 반환된 task_id를 저장하고 status가 succeeded가 될 때까지 GET /v1/tasks/{task_id}를 폴링한 뒤 data.results.items의 레코드 1개를 읽습니다. 요청 1회당 0.5 크레딧($0.0025)입니다. 동영상 파일 링크는 약 하루 뒤에 만료되므로 빨리 다운로드하세요.

엔드포인트가 반환하는 내용

1 SocQ 크레딧 = $0.005입니다.

엔드포인트반환 내용가격
Twitch Clip Downloader API클립 1개: 제목, 조회수, 길이, 생성 시각, 아바타를 포함한 스트리머 정보, 동영상 파일, 썸네일호출 1회당 0.5 크레딧($0.0025)

레코드는 SocQ의 표준 동영상 스키마를 사용합니다. 클립에서 중요한 필드는 다음과 같습니다.

필드의미
idTwitch의 숫자형 클립 ID
shortcodeURL에 있는 클립 슬러그
url클립 URL
text클립 제목
published_at클립 생성 시각(ISO 8601)
duration_seconds클립 길이(초)
metrics.views_count클립 조회수
author스트리머: id, username, name, url, avatar_url, is_verified
media[0].url클립의 MP4 파일
media[0].thumbnail_url클립 썸네일
collected_atSocQ가 레코드를 수집한 시각

선언된 필드는 값이 없어도 레코드에 남습니다. 문서 예시에서 27초짜리 클립은 views_count: 69776을 반환하지만 metrics.likes_count, metrics.comments_count, hashtags, audio는 null입니다.

인증과 비동기 작업 흐름

모든 요청은 API 키로 인증합니다. 제출, 작업 상태 조회, 결과 조회 요청에 같은 헤더를 사용합니다.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

모든 수집은 백그라운드 작업으로 실행됩니다.

submit -> task_id -> queued -> running -> succeeded
                                   \-> failed

제출 호출은 즉시 data.task_id와 data.status를 반환합니다. 이 ID로 작업을 폴링하세요.

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

status가 succeeded가 되면 응답에 result_count, credits_amount, 그리고 data.results.items에 담긴 레코드가 포함됩니다. 실패한 작업에는 error_message가 담깁니다. 클라이언트 측 타임아웃이 작업을 취소하지는 않으므로 다시 제출하지 말고 같은 작업 ID로 조회를 이어가세요. 402는 계정의 크레딧이 부족하다는 뜻이고, 429는 키가 속도 또는 크레딧 한도에 도달했다는 뜻입니다.

대부분의 SocQ 엔드포인트와 달리 Clip Downloader 요청 본문은 url만 받으며 callback_url은 목록에 없으므로, 작업을 폴링해야 합니다.

클립 요청하기

url에 클립 URL 하나를 전달하세요. twitch.tv/<channel>/clip/<slug>와 clips.twitch.tv/<slug> 두 형식을 모두 사용할 수 있습니다. (문서)

curl -X POST "https://api.socq.ai/v1/twitch/clip" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.twitch.tv/staryuuki/clip/CloudySavageMarjoramRuleFive--ErzsYbE7UWvgCMQ"}'

요청 1회는 URL 하나를 받아 행 하나를 반환합니다. 여러 클립을 처리하려면 클립마다 작업을 하나씩 제출하고, 재시도할 때 같은 클립을 두 번 제출하지 않도록 각 task_id를 해당 URL과 함께 보관하세요.

링크가 만료되기 전에 동영상 다운로드하기

media[0].url 링크는 서명된 링크이며 약 하루 뒤에 만료됩니다. 클립 사본이 필요하다면 작업이 성공하는 즉시 다운로드해 자체 스토리지에 저장하세요. 나중에 원본 링크가 필요할 때 클립을 다시 요청할 수 있도록 레코드의 id, shortcode, url을 파일과 함께 보관하세요.

최소한의 Python 흐름은 다음과 같습니다.

import os, time, requests

API = "https://api.socq.ai"
headers = {"Authorization": f"Bearer {os.environ['SOCQ_API_KEY']}"}
clip_url = "https://clips.twitch.tv/CloudySavageMarjoramRuleFive--ErzsYbE7UWvgCMQ"

task = requests.post(f"{API}/v1/twitch/clip", headers=headers,
                     json={"url": clip_url}).json()["data"]

while task["status"] in ("queued", "running"):
    time.sleep(3)
    task = requests.get(f"{API}/v1/tasks/{task['task_id']}",
                        headers=headers).json()["data"]

if task["status"] != "succeeded":
    raise RuntimeError(task.get("error_message"))

clip = task["results"]["items"][0]
video = requests.get(clip["media"][0]["url"], timeout=60)
with open(f"{clip['shortcode']}.mp4", "wb") as f:
    f.write(video.content)

대규모로 실행하기 전에 HTTP 상태 확인, 횟수 제한이 있는 재시도, 로깅을 추가하세요.

활용 시점

  • 하이라이트 아카이브. 원본 링크가 바뀌기 전에 내 채널이나 소속 크리에이터가 만든 클립을 제목, 생성 시각, 조회수와 함께 저장합니다.
  • 도달 범위 추적. 클립이 공유된 뒤 다시 실행해 metrics.views_count를 첫 스냅샷과 비교합니다. 확인 1회당 0.5 크레딧입니다.
  • 출처 표기. author에는 해당 장면을 방송한 스트리머의 이름과 프로필 링크가 담겨 있어, 다시 게시할 때 올바른 채널을 표기할 수 있습니다.
  • 콘텐츠 파이프라인. MP4를 편집, 자막 작업, 숏폼 재가공에 투입합니다.

비용 계획: 가격이 고정이므로 클립 100개는 50 크레딧($0.25), 클립 1,000개는 500 크레딧($2.50)입니다. 추적 중인 클립 50개의 조회수를 매주 확인하면 주당 25 크레딧($0.125)입니다.

스트리머와 클립에 등장하는 모든 사람의 권리를 존중하고, 동영상을 재사용할 때는 Twitch 약관을 따르세요.

관련 Twitch 엔드포인트

클립 레코드에서 누가 방송했는지 알 수 있습니다. 여기서 채널로 이어가려면 다음을 사용하세요.

  • Twitch Profile API는 username으로 공개 Twitch 프로필을 반환합니다.
  • Twitch User Videos API는 사용자의 공개 동영상 한 페이지를 반환하며, filter_by(archive, highlight, upload 등)와 sort_by(time 또는 views)를 지원합니다.

클립의 author.username을 둘 중 어느 쪽에든 전달하세요. 다른 플랫폼의 클립과 동영상을 같은 정규화 형식으로 받으려면 TikTok 스크래핑 가이드와 YouTube 스크래퍼 API 추천 7선을 참고하세요.

자주 묻는 질문(FAQ)

Twitch Clip Downloader API의 비용은 얼마인가요?

요청 1회당 0.5 크레딧, 즉 $0.0025입니다. 요청마다 클립 1개를 반환합니다.

어떤 클립 URL 형식을 사용할 수 있나요?

https://www.twitch.tv/<channel>/clip/<slug>와 https://clips.twitch.tv/<slug>입니다.

동영상 링크는 얼마 동안 유효한가요?

링크는 서명된 링크이며 약 하루 뒤에 만료됩니다. 사본이 필요하다면 파일을 바로 다운로드하세요.

한 번의 요청으로 여러 클립을 보낼 수 있나요?

아니요. url은 클립 URL 하나만 받습니다. 클립마다 작업을 하나씩 제출하세요.

클립의 좋아요나 댓글도 반환하나요?

레코드에는 조회수가 담깁니다. 문서 예시에서 likes_count와 comments_count는 null이므로 이 값에 의존하지 마세요.

TWITCH API

공개 Twitch URL로 워크플로를 테스트하세요

공개 데이터 입력을 제출하면 출처를 추적할 수 있는 컨텍스트가 포함된 정규화된 레코드를 받을 수 있습니다.

Twitch API 살펴보기