Le clip sono i brevi momenti salienti che gli spettatori ritagliano da una live su Twitch, e sono ciò che viene condiviso su X, Reddit e Discord. Se archivi i momenti migliori, misuri quanto lontano è arrivata una clip o devi citare il canale giusto quando la ripubblichi, ti servono i dati della clip e il suo file video in una forma che il tuo codice possa salvare.
Il 2026-11-17 SocQ ha aggiunto la Twitch Clip Downloader API alla pagina della piattaforma Twitch, accanto agli endpoint già esistenti Twitch Profile e User Videos. Questa guida spiega cosa restituisce, come si fa la richiesta, quanto costa e quali limiti devi mettere in conto.
Risposta rapida: invia
{"url": "<clip URL>"}aPOST https://api.socq.ai/v1/twitch/clip. Salva iltask_idrestituito, interrogaGET /v1/tasks/{task_id}finchéstatusnon èsucceeded, poi leggi l’unico record indata.results.items. Ogni richiesta costa 0.5 crediti ($0.0025). Scarica presto il file video, perché il suo link scade dopo circa un giorno.
Cosa restituisce l’endpoint
1 credito SocQ = $0.005.
| Endpoint | Cosa restituisce | Prezzo |
|---|---|---|
| Twitch Clip Downloader API | Una clip: titolo, numero di visualizzazioni, durata, data di creazione, broadcaster con avatar, file video e miniatura | 0.5 crediti ($0.0025) per chiamata |
Il record usa lo schema video standard di SocQ. I campi che contano per le clip:
| Campo | Significato |
|---|---|
id | ID numerico della clip su Twitch |
shortcode | Lo slug della clip presente nell’URL |
url | L’URL della clip |
text | Il titolo della clip |
published_at | Quando è stata creata la clip (ISO 8601) |
duration_seconds | Durata della clip in secondi |
metrics.views_count | Visualizzazioni della clip |
author | Il broadcaster: id, username, name, url, avatar_url, is_verified |
media[0].url | Il file MP4 della clip |
media[0].thumbnail_url | La miniatura della clip |
collected_at | Quando SocQ ha raccolto il record |
I campi dichiarati restano nel record anche quando non hanno un valore. Nell’esempio della documentazione, una clip di 27 secondi restituisce views_count: 69776, mentre metrics.likes_count, metrics.comments_count, hashtags e audio sono null.
Autenticazione e flusso asincrono dei task
Tutte le richieste si autenticano con una chiave API. Lo stesso header serve per l’invio, lo stato del task e le richieste dei risultati:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Ogni raccolta viene eseguita come task in background:
submit -> task_id -> queued -> running -> succeeded
\-> failed
La chiamata di invio risponde subito con data.task_id e data.status. Interroga il task con quell’ID:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Quando status è succeeded, la risposta include result_count, credits_amount e il record in data.results.items. Un task fallito riporta error_message. Un timeout lato client non annulla il task, quindi riprendi con lo stesso ID invece di inviarlo di nuovo. Un 402 significa che l’account ha finito i crediti, un 429 che la chiave ha raggiunto un limite di frequenza o di crediti.
A differenza della maggior parte degli endpoint SocQ, il body della richiesta di Clip Downloader accetta solo url; non prevede callback_url, quindi devi interrogare il task.
Richiedere una clip
Passa un URL di clip in url. Funzionano entrambi i formati: twitch.tv/<channel>/clip/<slug> e clips.twitch.tv/<slug>. (documentazione)
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"}'
Ogni richiesta accetta un URL e restituisce una riga. Per un lotto, invia un task per clip e conserva ogni task_id accanto al suo URL, così un nuovo tentativo non invia due volte la stessa clip.
Scarica il video prima che il link scada
Il link media[0].url è firmato e scade dopo circa un giorno. Se ti serve una copia della clip, scaricala appena il task va a buon fine e salva il file nel tuo storage. Conserva id, shortcode e url del record insieme al file, così potrai richiedere di nuovo la clip se un giorno ti servirà il link originale.
Un flusso Python minimo:
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)
Aggiungi controlli sullo stato HTTP, tentativi limitati e logging prima di usarlo su larga scala.
Quando usarla
- Archivi di highlight. Salva le clip prodotte dal tuo canale o dai tuoi talent, con titolo, data di creazione e visualizzazioni, prima che il link originale cambi.
- Monitoraggio della portata. Rilancia una clip dopo che è stata condivisa e confronta
metrics.views_countcon la prima istantanea. Ogni controllo costa 0.5 crediti. - Attribuzione.
authorindica il broadcaster che ha trasmesso quel momento, con il link al profilo, così chi ripubblica può citare il canale giusto. - Pipeline di contenuti. Passa l’MP4 a montaggio, sottotitolazione o riutilizzo in formato breve.
Pianificazione dei costi: il prezzo è fisso, quindi 100 clip costano 50 crediti ($0.25) e 1,000 clip costano 500 crediti ($2.50). Un controllo settimanale delle visualizzazioni su 50 clip monitorate costa 25 crediti ($0.125) a settimana.
Rispetta i diritti del broadcaster e di chiunque compaia in una clip, e segui i termini di Twitch quando riutilizzi il video.
Endpoint Twitch correlati
Il record della clip ti dice chi l’ha trasmessa. Per passare da lì al canale:
- Twitch Profile API restituisce un profilo pubblico di Twitch a partire da uno
username. - Twitch User Videos API restituisce una pagina dei video pubblici di un utente, con
filter_by(comearchive,highlightoupload) esort_by(timeoviews).
Passa author.username di una clip a uno dei due. Per clip e video di altre piattaforme nello stesso formato normalizzato, vedi la guida allo scraping di TikTok e Le 7 migliori API scraper per YouTube.
FAQ
Quanto costa la Twitch Clip Downloader API?
0.5 crediti per richiesta, cioè $0.0025. Ogni richiesta restituisce una clip.
Quali formati di URL delle clip sono accettati?
https://www.twitch.tv/<channel>/clip/<slug> e https://clips.twitch.tv/<slug>.
Quanto dura il link al video?
Il link è firmato e scade dopo circa un giorno. Scarica subito il file se ti serve una copia.
Posso inviare più clip in una sola richiesta?
No. url accetta un solo URL di clip. Invia un task per clip.
Restituisce i like o i commenti di una clip?
Il record contiene il numero di visualizzazioni. Nell’esempio della documentazione, likes_count e comments_count sono null, quindi non contarci.
TWITCH API
Prova il flusso di lavoro con un URL pubblico di Twitch
Invia input pubblici e ricevi record normalizzati con un contesto di origine tracciabile.
Scopri le API di Twitch