Los clips son los momentos destacados que los espectadores recortan de una transmisión de Twitch, y son lo que se comparte en X, Reddit y Discord. Si archiva momentos destacados, mide cuánto se difundió un clip o necesita dar crédito al canal correcto al volver a publicarlo, necesita los datos del clip y su archivo de video en un formato que su código pueda guardar.
El 2026-11-17 SocQ añadió la Twitch Clip Downloader API a la página de la plataforma Twitch, junto a los endpoints existentes Twitch Profile y User Videos. Esta guía explica qué devuelve, cómo es la solicitud, el precio y los límites que debe tener en cuenta.
Respuesta rápida: envíe
{"url": "<clip URL>"}aPOST https://api.socq.ai/v1/twitch/clip. Guarde eltask_iddevuelto, consulteGET /v1/tasks/{task_id}hasta questatusseasucceededy luego lea el único registro endata.results.items. Cada solicitud cuesta 0.5 créditos ($0.0025). Descargue el archivo de video pronto, porque su enlace caduca al cabo de aproximadamente un día.
Qué devuelve el endpoint
1 crédito de SocQ = $0.005.
| Endpoint | Qué devuelve | Precio |
|---|---|---|
| Twitch Clip Downloader API | Un clip: título, número de vistas, duración, fecha de creación, emisor con avatar, archivo de video y miniatura | 0.5 créditos ($0.0025) por llamada |
El registro usa el esquema de video estándar de SocQ. Los campos relevantes para los clips:
| Campo | Significado |
|---|---|
id | ID numérico del clip en Twitch |
shortcode | El slug del clip en la URL |
url | La URL del clip |
text | El título del clip |
published_at | Cuándo se creó el clip (ISO 8601) |
duration_seconds | Duración del clip en segundos |
metrics.views_count | Vistas del clip |
author | El emisor: id, username, name, url, avatar_url, is_verified |
media[0].url | El archivo MP4 del clip |
media[0].thumbnail_url | La miniatura del clip |
collected_at | Cuándo SocQ recopiló el registro |
Los campos declarados permanecen en el registro aunque no tengan valor. En el ejemplo de la documentación, un clip de 27 segundos devuelve views_count: 69776, mientras que metrics.likes_count, metrics.comments_count, hashtags y audio son null.
Autenticación y flujo de tareas asíncronas
Todas las solicitudes se autentican con una clave de API. Se usa el mismo encabezado para el envío, el estado de la tarea y la obtención de resultados:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Cada recopilación se ejecuta como una tarea en segundo plano:
submit -> task_id -> queued -> running -> succeeded
\-> failed
La llamada de envío responde de inmediato con data.task_id y data.status. Consulte la tarea con ese ID:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Cuando status es succeeded, la respuesta incluye result_count, credits_amount y el registro en data.results.items. Una tarea fallida incluye error_message. Un tiempo de espera agotado en el cliente no cancela la tarea, así que reanude con el mismo ID de tarea en lugar de enviarla de nuevo. Un 402 significa que la cuenta se quedó sin créditos, y un 429 que la clave alcanzó un límite de frecuencia o de créditos.
A diferencia de la mayoría de los endpoints de SocQ, el cuerpo de la solicitud de Clip Downloader solo acepta url; no incluye callback_url, así que consulte la tarea periódicamente.
Solicitar un clip
Pase la URL de un clip en url. Funcionan ambos formatos: twitch.tv/<channel>/clip/<slug> y clips.twitch.tv/<slug>. (documentación)
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"}'
Cada solicitud acepta una URL y devuelve una fila. Para un lote, envíe una tarea por clip y guarde cada task_id junto a su URL para que un reintento no envíe el mismo clip dos veces.
Descargue el video antes de que caduque el enlace
El enlace media[0].url está firmado y caduca al cabo de aproximadamente un día. Si necesita una copia del clip, descárguela en cuanto la tarea finalice correctamente y guarde el archivo en su propio almacenamiento. Conserve id, shortcode y url del registro junto al archivo, para poder volver a solicitar el clip si alguna vez necesita el enlace de origen.
Un flujo mínimo en 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)
Añada comprobaciones de estado HTTP, reintentos limitados y registro antes de ejecutarlo a escala.
Cuándo usarlo
- Archivos de momentos destacados. Guarde los clips que producen su canal o sus talentos, con título, fecha de creación y vistas, antes de que cambie el enlace de origen.
- Seguimiento del alcance. Vuelva a consultar un clip después de que se haya compartido y compare
metrics.views_countcon la primera captura. Cada consulta cuesta 0.5 créditos. - Atribución.
authoridentifica al emisor que transmitió el momento, con un enlace al perfil, para que las republicaciones den crédito al canal correcto. - Flujos de contenido. Envíe el MP4 a procesos de edición, subtitulado o reutilización en formato corto.
Planificación de costos: el precio es fijo, así que 100 clips cuestan 50 créditos ($0.25) y 1,000 clips cuestan 500 créditos ($2.50). Una comprobación semanal de vistas en 50 clips monitorizados cuesta 25 créditos ($0.125) por semana.
Respete los derechos del emisor y de cualquier persona que aparezca en un clip, y cumpla los términos de Twitch cuando reutilice el video.
Endpoints de Twitch relacionados
El registro del clip le indica quién lo transmitió. Para pasar de ahí al canal:
- Twitch Profile API devuelve un perfil público de Twitch a partir de un
username. - Twitch User Videos API devuelve una página de los videos públicos de un usuario, con
filter_by(comoarchive,highlightoupload) ysort_by(timeoviews).
Pase el author.username de un clip a cualquiera de los dos. Para clips y videos de otras plataformas con la misma forma normalizada, consulte la guía de scraping de TikTok y Las 7 mejores API de scraper de YouTube.
Preguntas frecuentes
¿Cuánto cuesta la Twitch Clip Downloader API?
0.5 créditos por solicitud, es decir, $0.0025. Cada solicitud devuelve un clip.
¿Qué formatos de URL de clip se aceptan?
https://www.twitch.tv/<channel>/clip/<slug> y https://clips.twitch.tv/<slug>.
¿Cuánto dura el enlace del video?
El enlace está firmado y caduca al cabo de aproximadamente un día. Descargue el archivo cuanto antes si necesita una copia.
¿Puedo enviar varios clips en una sola solicitud?
No. url acepta una sola URL de clip. Envíe una tarea por clip.
¿Devuelve los me gusta o los comentarios de un clip?
El registro incluye el número de vistas. En el ejemplo de la documentación, likes_count y comments_count son null, así que no cuente con ellos.
TWITCH API
Probar el flujo de trabajo con una URL pública de Twitch
Envíe entradas públicas y reciba registros normalizados con contexto de origen rastreable.
Ver las API de Twitch