TwitchClip di TwitchDownload videoStreamingGuida alle API

API Twitch Clip Downloader: visualizzazioni, broadcaster e file video delle clip

La nuova API Twitch Clip Downloader di SocQ trasforma l’URL di una clip in titolo, visualizzazioni, durata, data di creazione, broadcaster e link MP4 scaricabile per 0.5 crediti.

SocQAggiornato il 19 novembre 20266 min di lettura

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>"} a POST https://api.socq.ai/v1/twitch/clip. Salva il task_id restituito, interroga GET /v1/tasks/{task_id} finché status non è succeeded, poi leggi l’unico record in data.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.

EndpointCosa restituiscePrezzo
Twitch Clip Downloader APIUna clip: titolo, numero di visualizzazioni, durata, data di creazione, broadcaster con avatar, file video e miniatura0.5 crediti ($0.0025) per chiamata

Il record usa lo schema video standard di SocQ. I campi che contano per le clip:

CampoSignificato
idID numerico della clip su Twitch
shortcodeLo slug della clip presente nell’URL
urlL’URL della clip
textIl titolo della clip
published_atQuando è stata creata la clip (ISO 8601)
duration_secondsDurata della clip in secondi
metrics.views_countVisualizzazioni della clip
authorIl broadcaster: id, username, name, url, avatar_url, is_verified
media[0].urlIl file MP4 della clip
media[0].thumbnail_urlLa miniatura della clip
collected_atQuando 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.

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_count con la prima istantanea. Ogni controllo costa 0.5 crediti.
  • Attribuzione. author indica 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 (come archive, highlight o upload) e sort_by (time o views).

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>.

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