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