Клипы — это короткие яркие моменты, которые зрители вырезают из стрима на Twitch, и именно ими делятся в X, Reddit и Discord. Если вы архивируете запоминающиеся моменты, измеряете, как далеко разошелся клип, или должны указать правильный канал при репосте, вам нужны данные клипа и его видеофайл в виде, который ваш код может сохранить.
2026-11-17 SocQ добавил Twitch Clip Downloader API на страницу платформы Twitch рядом с уже существующими эндпоинтами Twitch Profile и User Videos. В этом руководстве описано, что он возвращает, как выглядит запрос, сколько он стоит и какие ограничения стоит учесть.
Коротко: отправьте
{"url": "<clip URL>"}наPOST https://api.socq.ai/v1/twitch/clip. Сохраните возвращенныйtask_id, опрашивайтеGET /v1/tasks/{task_id}, покаstatusне станетsucceeded, затем прочитайте единственную запись вdata.results.items. Каждый запрос стоит 0.5 кредита ($0.0025). Скачайте видеофайл быстро, потому что его ссылка истекает примерно через сутки.
Что возвращает эндпоинт
1 кредит SocQ = $0.005.
| Эндпоинт | Что возвращает | Цена |
|---|---|---|
| Twitch Clip Downloader API | Один клип: название, число просмотров, длительность, время создания, стример с аватаром, видеофайл и миниатюра | 0.5 кредита ($0.0025) за вызов |
Запись использует стандартную схему видео SocQ. Поля, важные для клипов:
| Поле | Значение |
|---|---|
id | Числовой ID клипа в Twitch |
shortcode | Слаг клипа из URL |
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_at | Когда SocQ собрал запись |
Объявленные поля остаются в записи, даже если у них нет значения. В примере из документации 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"}'
Каждый запрос принимает один 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с первым снимком. Каждая проверка стоит 0.5 кредита. - Указание авторства.
authorназывает стримера, который транслировал момент, со ссылкой на профиль, чтобы в репостах был указан правильный канал. - Контент-конвейеры. Передавайте MP4 в монтаж, создание субтитров или переработку в короткие форматы.
Планирование расходов: цена фиксированная, поэтому 100 клипов стоят 50 кредитов ($0.25), а 1,000 клипов — 500 кредитов ($2.50). Еженедельная проверка просмотров 50 отслеживаемых клипов стоит 25 кредитов ($0.125) в неделю.
Уважайте права стримера и всех, кто появляется в клипе, и соблюдайте условия Twitch при повторном использовании видео.
Связанные эндпоинты Twitch
Запись клипа сообщает, кто его транслировал. Чтобы перейти от нее к каналу:
- Twitch Profile API возвращает публичный профиль Twitch по
username. - Twitch User Videos API возвращает одну страницу публичных видео пользователя с
filter_by(например,archive,highlightилиupload) иsort_by(timeилиviews).
Передайте author.username из клипа в любой из них. Клипы и видео с других платформ в той же нормализованной структуре описаны в руководстве по парсингу TikTok и в статье 7 лучших API для парсинга YouTube.
FAQ
Сколько стоит Twitch Clip Downloader API?
0.5 кредита за запрос, то есть $0.0025. Каждый запрос возвращает один клип.
Какие форматы URL клипов принимаются?
https://www.twitch.tv/<channel>/clip/<slug> и https://clips.twitch.tv/<slug>.
Сколько действует ссылка на видео?
Ссылка подписана и истекает примерно через сутки. Если вам нужна копия, скачайте файл сразу.
Можно ли отправить несколько клипов в одном запросе?
Нет. url принимает URL одного клипа. Отправляйте по одной задаче на клип.
Возвращает ли он лайки или комментарии клипа?
Запись содержит число просмотров. В примере из документации likes_count и comments_count равны null, поэтому не рассчитывайте на них.
TWITCH API
Проверить сценарий на публичном URL Twitch
Отправляйте публичные входные данные и получайте нормализованные записи с отслеживаемым источником.
API для Twitch