TwitchTwitch 剪辑视频下载直播API 指南

Twitch 剪辑下载 API:获取剪辑播放量、主播和视频文件

SocQ 新上线的 Twitch 剪辑下载 API 把剪辑 URL 转成标题、播放量、时长、创建时间、主播和可下载的 MP4 链接,每次 0.5 credits。

SocQ更新于 2026年11月19日阅读约 4 分钟

剪辑(Clip)是观众从 Twitch 直播中截下的精彩片段,也是在 X、Reddit 和 Discord 上被转发的内容。如果你要归档高光时刻、衡量一个剪辑传播了多远,或在转发时注明正确的频道,就需要以代码能存储的形式拿到剪辑数据和视频文件。

2026-11-17,SocQ 在 Twitch 平台页 新增了 Twitch 剪辑下载 API,与已有的 Twitch 主页和用户视频接口并列。本文说明它返回什么、请求怎么写、价格多少,以及需要提前规划的限制。

快速回答: 把 {"url": "<剪辑 URL>"} 发送到 POST https://api.socq.ai/v1/twitch/clip。保存返回的 task_id,轮询 GET /v1/tasks/{task_id} 直到 status 为 succeeded,再读取 data.results.items 中的那一条记录。每次请求 0.5 credits($0.0025)。视频链接大约一天后过期,请尽快下载。

接口返回什么

1 SocQ credit = $0.005。

接口返回内容价格
Twitch 剪辑下载 API一个剪辑:标题、播放量、时长、创建时间、主播及头像、视频文件和缩略图每次调用 0.5 credits($0.0025)

记录使用 SocQ 的标准视频结构。对剪辑最重要的字段:

字段含义
idTwitch 的数字剪辑 ID
shortcodeURL 中的剪辑 slug
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_atSocQ 采集该记录的时间

已声明的字段即使没有值也会保留在记录中。在文档示例中,一个 27 秒的剪辑返回 views_count: 69776,而 metrics.likes_count、metrics.comments_count、hashtags 和 audio 为 null。

认证与异步任务流程

所有请求都用 API key 认证。提交、查询任务状态和读取结果使用同一个请求头:

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 表示 key 触发了频率或额度限制。

与大多数 SocQ 接口不同,剪辑下载的请求体只接收 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 credits。
  • 署名。 author 给出直播该片段的主播及主页链接,转发时可以注明正确的频道。
  • 内容流水线。 把 MP4 交给剪辑、加字幕或短视频二次创作流程。

成本规划: 价格按次固定,100 个剪辑 50 credits($0.25),1,000 个剪辑 500 credits($2.50)。每周对 50 个追踪中的剪辑检查一次播放量,每周 25 credits($0.125)。

请尊重主播和剪辑中出现的任何人的权利,复用视频时遵守 Twitch 的条款。

相关 Twitch 接口

剪辑记录告诉你是谁直播的。要从这里找到频道:

  • Twitch 主页 API 根据 username 返回公开的 Twitch 主页。
  • Twitch 用户视频 API 返回用户公开视频的一页,支持 filter_by(如 archive、highlight 或 upload)和 sort_by(time 或 views)。

把剪辑中的 author.username 传给任一接口即可。其他平台以相同标准化结构返回的剪辑和视频,见 TikTok 采集指南 和 7 个最佳 YouTube Scraper API。

常见问题

Twitch 剪辑下载 API 多少钱?

每次请求 0.5 credits,即 $0.0025。每次请求返回一个剪辑。

支持哪些剪辑 URL 格式?

https://www.twitch.tv/<channel>/clip/<slug> 和 https://clips.twitch.tv/<slug>。

视频链接能用多久?

链接是签名的,大约一天后过期。如果需要保留,请尽快下载文件。

可以一次请求多个剪辑吗?

不可以。url 只接收一个剪辑 URL。每个剪辑提交一个任务。

会返回剪辑的点赞或评论吗?

记录包含播放量。在文档示例中,likes_count 和 comments_count 为 null,请不要依赖它们。

TWITCH API

使用公开的 Twitch 输入测试工作流

提交公开输入,获取带有可追溯来源上下文的标准化记录。

查看 Twitch API