twitter-screenshot
==================

auto-crops a twitter/x post screenshot and returns a static png or composited mp4 depending on whether the tweet contains a video



ROUTES:

Method | Path         | Description
------ | ------------ | -----------------------------------
POST   | /api/capture | crop screenshot and render video when needed
GET    | /api/health  | service status
GET    | /            | usage reference



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

curl -X POST http://localhost:8270/api/capture \
  -F image=@screenshot.png \
  --output tweet.png

curl -X POST http://localhost:8270/api/capture \
  -F image=@screenshot.png \
  -F url='https://x.com/user/status/123' \
  --output capture.bin

accepts the screenshot as multipart form-data under the image field, or as the raw request body
the tweet url is optional; omit it to crop only and skip video detection and yt-dlp entirely
when a url is provided, video tweets are detected from player controls in the screenshot (duration badge and mute icon), with a yt-dlp probe as fallback when a media rectangle is present but controls are not visible
quoted embedded videos are composited on the exact quoted-media bounds, with a square top edge and rounded bottom corners so they stay inside the quote card
returns image/png for text-only tweets, image tweets, and other non-video posts
returns video/mp4 when a video is detected and successfully composited
if video rendering fails (for example yt-dlp finds no video), the api silently falls back to the cropped image/png instead of returning an error
the X-Capture-Mode response header is image or video
add the debug query parameter to return detection details as json instead of the output file
supported input formats are png, jpeg, bmp, tiff, and gif

REQUEST FIELDS:

Field | Type    | Default
----- | ------- | -------
image | File    | -
url   | string  | null
debug | boolean | false

EXAMPLE RESPONSE:

returns image/png or video/mp4 depending on tweet content; with the debug query parameter, returns json describing the chosen mode and detection signals instead

ERROR RESPONSE:

"error": "No image provided. Send a screenshot as multipart form-data under the 'image' field, or as the raw request body."