TwitterShots

Generate high-quality screenshots of Twitter/X posts using the TwitterShots API. Use when the user wants to: capture a tweet as an image, screenshot a tweet,...

Security Scan

The skill's code and instructions match its stated purpose (calling the TwitterShots API to render tweet screenshots) but there are metadata inconsistencies about required credentials/dependencies that should be resolved before installing.

Purpose & Capability

The name/description, SKILL.md, README, and the included Python script all consistently implement a single purpose: call https://api.twittershots.com/api/v1/screenshot/:statusId using an API key and return an image or URL. This capability is coherent with the stated purpose. However, the registry metadata at the top of the package (in the evaluation manifest) lists no required env vars or dependencies while the SKILL.md frontmatter and README declare a required TWITTERSHOTS_API_KEY and 'requests' dependency — a metadata mismatch worth noting.

Instruction Scope

SKILL.md and the Python script limit runtime actions to extracting tweet IDs, building query parameters, and making GET requests to api.twittershots.com. They do not instruct the agent to read unrelated files, other environment variables, or contact other external endpoints. The skill does not request broad discretionary access or vague 'gather context' operations.

Install Mechanism

There is no install spec (instruction-only) and the included script is runnable directly. The SKILL.md declares a Python dependency (requests) but the package has no automated install step; the top-level registry metadata omitted this dependency. This is likely sloppy metadata rather than a high-risk install mechanism, but you should ensure the runtime environment has the requests package or install it from a trusted source.

Credentials

The only credential logically required is an API key for TwitterShots (TWITTERSHOTS_API_KEY), which the SKILL.md, README, and script all reference and use appropriately. However, the registry metadata included with the skill incorrectly lists no required env vars/primary credential. That inconsistency could lead to confusion or misconfiguration; ensure the skill will be given ONLY a TwitterShots API key (not reused sensitive credentials like platform admin keys or AWS secrets).

Persistence & Privilege

The skill does not request always:true, does not modify other skills or global config, and has no install hooks. It is user-invocable and may be invoked autonomously by agents (platform default), which is expected for this type of skill.

What to consider before installing

This skill appears to do exactly what it claims: call the TwitterShots API to render tweet screenshots and return an image or URL. Before installing: (1) Confirm the skill will only be given a TwitterShots API key (TWITTERSHOTS_API_KEY) and avoid reusing highly privileged or unrelated keys; (2) note the package metadata is inconsistent — SKILL.md/README require the requests library and an API key even though the top-level registry metadata omitted them, so be sure to install requests from a trusted source (pip) if you run the script locally; (3) review the API host (https://api.twittershots.com) and the service's privacy/TOS if you will send tweet content you consider sensitive; and (4) because the skill can be invoked autonomously by agents, only enable it in agents you trust or restrict it to manual invocation if you prefer. If the metadata mismatch concerns you, ask the publisher to correct the registry fields or inspect the code yourself before use.

TwitterShots Skill

Generate high-quality screenshots of Twitter/X posts via REST API.

Prerequisites

• API key from TwitterShots Account Settings
• Store the key securely (environment variable TWITTERSHOTS_API_KEY recommended)

Extract Tweet ID

Parse tweet ID from various URL formats:

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

Extract pattern: /status/(\d+) → Tweet ID is the numeric part after /status/

API Request

Endpoint: GET https://api.twittershots.com/api/v1/screenshot/:statusId

Required Header:

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

Common Parameters

Parameter	Default	Options	Description
format	png	svg, png, html	Output format (Note: API default is svg, skill defaults to png)
theme	light	light, dark	Color theme
aspectRatio	auto	auto, 1:1, 4:5, 5:4, 16:9, 9:16	Screenshot ratio
returnType	buffer	buffer, url	Return image directly or URL
showStats	true	true, false	Show reply/retweet/like counts
showViews	true	true, false	Show view count
showTimestamp	true	true, false	Show timestamp
showMedia	true	true, false	Show images/videos
showFullText	true	true, false	Show full tweet or collapsed with "Show more"
mediaLayout	grid	grid, vertical	Media display layout
timeZoneOffset	UTC+0	UTC±N, UTC±N:M	Fixed UTC offset for timestamp formatting
logo	x	x, bluebird, none	Logo style
width	410	300-1000	Content width in pixels
height	auto	auto, numeric	Content height in pixels
containerBackground	theme default	hex, rgba, linear-gradient	Background color
backgroundImage	none	HTTPS URL	Background image URL
borderRadius	16	numeric	Border radius in pixels
containerPadding	16	numeric	Padding in pixels

Usage Examples

Basic Screenshot (SVG)

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

Dark Theme PNG

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

Instagram Ready (4:5 ratio)

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

Get URL Instead of Buffer

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

Response:

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

Minimal Style (No Stats)

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

Custom Background

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

Python Example

import requests
import os

def screenshot_tweet(
    tweet_id: str,
    format: str = "png",
    theme: str = "light",
    aspect_ratio: str = "auto",
    show_full_text: bool = True,
    media_layout: str = "grid",
    time_zone_offset: str = "UTC+0",
    height: str = "auto",
    background_image: str = None,
    **kwargs
) -> bytes:
    """Generate a screenshot of a tweet."""
    api_key = os.environ.get("TWITTERSHOTS_API_KEY")
    if not api_key:
        raise ValueError("TWITTERSHOTS_API_KEY environment variable not set")
    
    params = {
        "format": format,
        "theme": theme,
        "aspectRatio": aspect_ratio,
        "showFullText": str(show_full_text).lower(),
        "mediaLayout": media_layout,
        "timeZoneOffset": time_zone_offset,
        "height": height,
        **kwargs
    }
    
    if background_image:
        params["backgroundImage"] = background_image
    
    response = requests.get(
        f"https://api.twittershots.com/api/v1/screenshot/{tweet_id}",
        headers={
            "X-API-KEY": api_key,
            "Accept": f"image/{format}" if format != "html" else "text/html"
        },
        params=params
    )
    response.raise_for_status()
    return response.content

# Extract tweet ID from URL
def extract_tweet_id(url: str) -> str:
    import re
    match = re.search(r'/status/(\d+)', url)
    if match:
        return match.group(1)
    raise ValueError(f"Could not extract tweet ID from: {url}")

# Usage
tweet_url = "https://twitter.com/elonmusk/status/1617979122625712128"
tweet_id = extract_tweet_id(tweet_url)
image_data = screenshot_tweet(tweet_id, format="png", theme="dark")

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

Response Headers

Monitor quota via response headers:

• X-Quota-Remaining: Remaining requests
• X-Quota-Limit: Total quota for period

Error Handling

Code	Meaning
200	Success
400	Invalid parameters
401	Missing API key
403	Invalid API key
404	Tweet not found
429	Rate limit exceeded
5xx	Server error

Workflow

1. Parse input: Extract tweet ID from URL or use directly if numeric
2. Apply defaults: Use format=png and theme=light unless the user explicitly sets either value
3. Build request: Construct URL with desired parameters
4. Execute: Make GET request with API key header
5. Handle response: Save buffer to file or use returned URL
6. Report: Show quota remaining from response headers