tweet-screenshot
================

renders an x.com / twitter.com tweet to a high-res png/jpeg/webp screenshot, or composites the tweet's video into the screenshot frame for video tweets



ROUTES:

| Method | Path         | Description                              |
| ------ | ------------ | ---------------------------------------- |
| POST   | /api/capture | screenshot a tweet (image or video mode) |
| GET    | /            | this page                                |
| GET    | /api/health  | service status                           |



POST /api/capture
=================

curl -X POST http://localhost:8270/api/capture \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://x.com/jack/status/20",
    "force": "image",
    "format": "png",
    "color_scheme": "light",
    "image_quality": 90,
    "viewport_width": 1440,
    "viewport_height": 1350,
    "device_scale_factor": 2,
    "supersample": 1.5,
    "page_zoom": 1,
    "border_size_x": 35,
    "border_size_y": 35,
    "border_color": "#ffffff",
    "delay": 0,
    "max_duration": 60
  }' \
  --output tweet.png

When force is omitted the route auto-detects whether the tweet has a <video> element and returns either an image or an mp4 with the tweet image as a backdrop. Pass force="image" or force="video" to skip the auto-detect. The video pipeline downloads via yt-dlp and composites with ffmpeg, so it is significantly slower than image mode.

REQUEST FIELDS:

| Field               | Type                       | Default   |
| ------------------- | -------------------------- | --------- |
| url                 | string                     | -         |
| force               | "image" or "video" or null | null      |
| format              | "png" or "jpeg" or "webp"  | "png"     |
| color_scheme        | "light" or "dark"          | "light"   |
| image_quality       | number                     | 90        |
| viewport_width      | number                     | 1440      |
| viewport_height     | number                     | 1350      |
| device_scale_factor | number                     | 2         |
| supersample         | number                     | 1.5       |
| page_zoom           | number                     | 1         |
| border_size_x       | number                     | 35        |
| border_size_y       | number                     | 35        |
| border_color        | string                     | "#ffffff" |
| delay               | number                     | 0         |
| max_duration        | number                     | 60        |

EXAMPLE RESPONSE:

Streams the rendered image (Content-Type: image/png, image/jpeg, or image/webp) or, in video mode, an mp4 (Content-Type: video/mp4). The X-Capture-Type response header is "image" or "video", and X-Duration-Ms reports total server time in milliseconds.

ERROR RESPONSE:

{
  "error": "Capture failed",
  "detail": "Request timeout exceeded"
}



GET /
=====

curl http://localhost:8270/

EXAMPLE RESPONSE:

Returns this plain-text helper page (Content-Type: text/plain).



GET /api/health
===============

curl http://localhost:8270/api/health

EXAMPLE RESPONSE:

{
  "name": "tweet-screenshot",
  "status": "ok",
  "port": 8270,
  "inFlight": 0,
  "maxConcurrency": 2
}