Les clips sont les courts temps forts que les spectateurs extraient d’un stream Twitch, et ce sont eux qui circulent sur X, Reddit et Discord. Si vous archivez les meilleurs moments, mesurez la portée d’un clip ou devez créditer la bonne chaîne lors d’un repartage, il vous faut les données du clip et son fichier vidéo sous une forme que votre code peut stocker.
Le 2026-11-17, SocQ a ajouté l’API Twitch Clip Downloader à la page de la plateforme Twitch, à côté des endpoints existants Twitch Profile et User Videos. Ce guide présente ce qu’elle renvoie, la requête, le prix et les limites à prévoir.
Réponse rapide : envoyez
{"url": "<clip URL>"}àPOST https://api.socq.ai/v1/twitch/clip. Enregistrez letask_idrenvoyé, interrogezGET /v1/tasks/{task_id}jusqu’à ce questatusvaillesucceeded, puis lisez l’unique enregistrement dansdata.results.items. Chaque requête coûte 0,5 crédit ($0,0025). Téléchargez rapidement le fichier vidéo, car son lien expire au bout d’environ un jour.
Ce que renvoie l’endpoint
1 crédit SocQ = $0,005.
| Endpoint | Ce qu’il renvoie | Prix |
|---|---|---|
| Twitch Clip Downloader API | Un clip : titre, nombre de vues, durée, date de création, streamer avec avatar, fichier vidéo et miniature | 0,5 crédit ($0,0025) par appel |
L’enregistrement utilise le schéma vidéo standard de SocQ. Les champs utiles pour les clips :
| Champ | Signification |
|---|---|
id | L’ID numérique du clip chez Twitch |
shortcode | Le slug du clip dans l’URL |
url | L’URL du clip |
text | Le titre du clip |
published_at | La date de création du clip (ISO 8601) |
duration_seconds | La durée du clip en secondes |
metrics.views_count | Les vues du clip |
author | Le streamer : id, username, name, url, avatar_url, is_verified |
media[0].url | Le fichier MP4 du clip |
media[0].thumbnail_url | La miniature du clip |
collected_at | La date à laquelle SocQ a collecté l’enregistrement |
Les champs déclarés restent présents dans l’enregistrement même lorsqu’ils n’ont pas de valeur. Dans l’exemple de la documentation, un clip de 27 secondes renvoie views_count: 69776, tandis que metrics.likes_count, metrics.comments_count, hashtags et audio valent null.
Authentification et flux de tâches asynchrones
Toutes les requêtes s’authentifient avec une clé API. Le même en-tête sert pour l’envoi, le statut de la tâche et la récupération des résultats :
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Chaque collecte s’exécute comme une tâche en arrière-plan :
submit -> task_id -> queued -> running -> succeeded
\-> failed
L’appel d’envoi répond immédiatement avec data.task_id et data.status. Interrogez la tâche avec cet ID :
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Lorsque status vaut succeeded, la réponse contient result_count, credits_amount et l’enregistrement dans data.results.items. Une tâche en échec porte error_message. Un délai d’expiration côté client n’annule pas une tâche : reprenez avec le même ID de tâche au lieu de renvoyer la requête. Un 402 signifie que le compte n’a plus de crédits, et un 429 que la clé a atteint une limite de débit ou de crédits.
Contrairement à la plupart des endpoints SocQ, le corps de requête de Clip Downloader n’accepte que url ; il ne prévoit pas callback_url, interrogez donc la tâche.
Demander un clip
Passez une URL de clip dans url. Les deux formats fonctionnent : twitch.tv/<channel>/clip/<slug> et clips.twitch.tv/<slug>. (docs)
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"}'
Chaque requête accepte une URL et renvoie une ligne. Pour un lot, envoyez une tâche par clip et conservez chaque task_id à côté de son URL, afin qu’une nouvelle tentative ne soumette pas deux fois le même clip.
Télécharger la vidéo avant l’expiration du lien
Le lien media[0].url est signé et expire au bout d’environ un jour. Si vous avez besoin d’une copie du clip, téléchargez-la dès que la tâche réussit et stockez le fichier dans votre propre espace de stockage. Conservez id, shortcode et url de l’enregistrement avec le fichier, pour pouvoir redemander le clip si vous avez un jour besoin du lien source.
Un flux Python minimal :
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)
Ajoutez des vérifications de statut HTTP, des nouvelles tentatives bornées et de la journalisation avant de l’exécuter à grande échelle.
Quand l’utiliser
- Archives de temps forts. Sauvegardez les clips produits par votre chaîne ou vos talents, avec titre, date de création et vues, avant que le lien source ne change.
- Suivi de la portée. Relancez un clip après son partage et comparez
metrics.views_countau premier relevé. Chaque vérification coûte 0,5 crédit. - Attribution.
authordésigne le streamer qui a diffusé le moment, avec un lien vers son profil, pour que les repartages créditent la bonne chaîne. - Pipelines de contenu. Injectez le MP4 dans vos outils de montage, de sous-titrage ou de recyclage en format court.
Budget : le prix est fixe, donc 100 clips coûtent 50 crédits ($0,25) et 1 000 clips coûtent 500 crédits ($2,50). Une vérification hebdomadaire des vues sur 50 clips suivis coûte 25 crédits ($0,125) par semaine.
Respectez les droits du streamer et de toute personne apparaissant dans un clip, et suivez les conditions de Twitch lorsque vous réutilisez la vidéo.
Endpoints Twitch associés
L’enregistrement du clip indique qui l’a diffusé. Pour remonter ensuite jusqu’à la chaîne :
- L’API Twitch Profile renvoie un profil Twitch public à partir d’un
username. - L’API Twitch User Videos renvoie une page des vidéos publiques d’un utilisateur, avec
filter_by(par exemplearchive,highlightouupload) etsort_by(timeouviews).
Passez le author.username d’un clip à l’un ou l’autre. Pour des clips et des vidéos d’autres plateformes dans le même format normalisé, consultez le guide de scraping TikTok et 7 meilleures API de scraping YouTube.
FAQ
Combien coûte l’API Twitch Clip Downloader ?
0,5 crédit par requête, soit $0,0025. Chaque requête renvoie un clip.
Quels formats d’URL de clip sont acceptés ?
https://www.twitch.tv/<channel>/clip/<slug> et https://clips.twitch.tv/<slug>.
Combien de temps le lien vidéo reste-t-il valide ?
Le lien est signé et expire au bout d’environ un jour. Téléchargez rapidement le fichier si vous avez besoin d’une copie.
Puis-je envoyer plusieurs clips dans une seule requête ?
Non. url accepte une seule URL de clip. Envoyez une tâche par clip.
Renvoie-t-elle les likes ou les commentaires d’un clip ?
L’enregistrement contient le nombre de vues. Dans l’exemple de la documentation, likes_count et comments_count valent null : ne comptez donc pas dessus.
TWITCH API
Tester le workflow avec une URL publique Twitch
Envoyez des entrées publiques et recevez des enregistrements normalisés, avec un contexte de source traçable.
Découvrir les API Twitch