TwitterShots 技能

通过 REST API 生成 Twitter/X 帖子的高质量截图。

前提条件

• - 从 TwitterShots 账户设置 获取 API 密钥
• 安全存储密钥（建议使用环境变量 TWITTERSHOTSAPI_KEY）

提取推文 ID

从各种 URL 格式中解析推文 ID：

https://twitter.com/username/status/1617979122625712128
https://x.com/username/status/1617979122625712128
https://twitter.com/username/status/1617979122625712128?s=20

提取模式：/status/(\d+) → 推文 ID 是 /status/ 后的数字部分

API 请求

端点： GET https://api.twittershots.com/api/v1/screenshot/:statusId

必需请求头：

X-API-KEY: YOURAPIKEY
Accept: image/svg+xml, image/png, text/html

常用参数

参数	默认值	选项	描述
format	png	svg, png, html	输出格式（注意：API 默认是 svg，技能默认是 png）
theme

light | light, dark | 颜色主题 | | aspectRatio | auto | auto, 1:1, 4:5, 5:4, 16:9, 9:16 | 截图比例 | | returnType | buffer | buffer, url | 直接返回图片或返回 URL | | showStats | true | true, false | 显示回复/转发/点赞数 | | showViews | true | true, false | 显示浏览数 | | showTimestamp | true | true, false | 显示时间戳 | | showMedia | true | true, false | 显示图片/视频 | | showFullText | true | true, false | 显示完整推文或折叠显示显示更多 | | mediaLayout | grid | grid, vertical | 媒体显示布局 | | timeZoneOffset | UTC+0 | UTC±N, UTC±N:M | 时间戳格式化的固定 UTC 偏移 | | logo | x | x, bluebird, none | 标志样式 | | width | 410 | 300-1000 | 内容宽度（像素） | | height | auto | auto, numeric | 内容高度（像素） | | containerBackground | 主题默认 | hex, rgba, linear-gradient | 背景颜色 | | backgroundImage | none | HTTPS URL | 背景图片 URL | | borderRadius | 16 | numeric | 边框圆角（像素） | | containerPadding | 16 | numeric | 内边距（像素） |

使用示例

基础截图（SVG）

bash
curl -X GET https://api.twittershots.com/api/v1/screenshot/1617979122625712128?format=svg&theme=light \
-H X-API-KEY: YOURAPIKEY \
-H Accept: image/svg+xml \
-o tweet.svg

深色主题 PNG

bash
curl -X GET https://api.twittershots.com/api/v1/screenshot/1617979122625712128?format=png&theme=dark \
-H X-API-KEY: YOURAPIKEY \
-H Accept: image/png \
-o tweet.png

Instagram 适配（4:5 比例）

bash
curl -X GET https://api.twittershots.com/api/v1/screenshot/1617979122625712128?format=png&aspectRatio=4:5&theme=light \
-H X-API-KEY: YOURAPIKEY \
-H Accept: image/png \
-o tweet-instagram.png

获取 URL 而非缓冲区

bash
curl -X GET https://api.twittershots.com/api/v1/screenshot/1617979122625712128?returnType=url&format=svg \
-H X-API-KEY: YOURAPIKEY

响应：
json
{
url: https://i.twittershots.com/twitter-screenshots/2025/12/15/tweet-1617979122625712128-xxx.svg,
format: svg,
tweetId: 1617979122625712128
}

极简样式（无统计数据）

bash
curl -X GET https://api.twittershots.com/api/v1/screenshot/1617979122625712128?format=png&showStats=false&showViews=false&showTimestamp=false \
-H X-API-KEY: YOURAPIKEY \
-H Accept: image/png \
-o tweet-minimal.png

自定义背景

bash

渐变背景

curl -X GET https://api.twittershots.com/api/v1/screenshot/1617979122625712128?format=png&containerBackground=linear-gradient(90deg,%23003f5b,%232b4b7d,%235f5195) \
-H X-API-KEY: YOURAPIKEY \
-H Accept: image/png \
-o tweet-gradient.png

Python 示例

python
import requests
import os

def screenshot_tweet(
tweet_id: str,
format: str = png,
theme: str = light,
aspect_ratio: str = auto,
showfulltext: bool = True,
media_layout: str = grid,
timezoneoffset: str = UTC+0,
height: str = auto,
background_image: str = None,
kwargs
) -> bytes:
生成推文截图。
apikey = os.environ.get(TWITTERSHOTSAPI_KEY)
if not api_key:
raise ValueError(未设置 TWITTERSHOTSAPIKEY 环境变量)

params = {
format: format,
theme: theme,
aspectRatio: aspect_ratio,
showFullText: str(showfulltext).lower(),
mediaLayout: media_layout,
timeZoneOffset: timezoneoffset,
height: height,
kwargs
}

if background_image:
params[backgroundImage] = background_image

response = requests.get(
fhttps://api.twittershots.com/api/v1/screenshot/{tweet_id},
headers={
X-API-KEY: api_key,
Accept: fimage/{format} if format != html else text/html
},
params=params
)
response.raiseforstatus()
return response.content

从 URL 提取推文 ID

def extracttweetid(url: str) -> str: import re match = re.search(r/status/(\d+), url) if match: return match.group(1) raise ValueError(f无法从 URL 提取推文 ID：{url})

使用示例

tweet_url = https://twitter.com/elonmusk/status/1617979122625712128 tweetid = extracttweetid(tweeturl) imagedata = screenshottweet(tweet_id, format=png, theme=dark)

with open(tweet.png, wb) as f:
f.write(image_data)

响应头

通过响应头监控配额：

• - X-Quota-Remaining：剩余请求数
• X-Quota-Limit：周期内总配额

错误处理

状态码	含义
200	成功
400

无效参数 | | 401 | 缺少 API 密钥 | | 403 | 无效 API 密钥 | | 404 | 推文未找到 | | 429 | 超出速率限制 | | 5xx | 服务器错误 |

工作流程

1. 1. 解析输入：从 URL 提取推文 ID，如果输入为数字则直接使用
2. 应用默认值：除非用户明确设置，否则使用 format=png 和 theme=light
3. 构建请求：使用所需参数构建 URL
4. 执行：使用 API 密钥请求头发送 GET 请求
5. 处理响应：将缓冲区保存到文件或使用返回的 URL
6. 报告：从响应头显示剩余配额