剪辑(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 的标准视频结构。对剪辑最重要的字段:
| 字段 | 含义 |
|---|---|
id | Twitch 的数字剪辑 ID |
shortcode | URL 中的剪辑 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_at | SocQ 采集该记录的时间 |
已声明的字段即使没有值也会保留在记录中。在文档示例中,一个 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,请不要依赖它们。