twitter-downloader · diff
v1.0.0 to v2.0.0
97 added, 37 removed. Audit A to A.
---
name: twitter-downloader
- version: 1.0.0
- description: "Download text, images, GIFs, and videos from Twitter/X posts via fxtwitter API. Trigger when users share any twitter.com or x.com link, or ask to download or see media from a tweet (e.g., '下载推特视频', '把这条推文的图存下来', 'what's in this tweet')."
+ version: 2.0.0
+ description: "Download Twitter/X tweet text, images, GIFs, and videos via fxtwitter/vxtwitter, then return a tweet summary plus Markdown-formatted Minis links. Trigger when users share twitter.com/x.com links or ask to download/summarize tweet media."
---
# Twitter Downloader Skill
- A compact, reliable workflow to parse Twitter/X URLs, fetch structured JSON via the public fxtwitter API (no auth), summarize the tweet, and download media files to Minis for easy sharing.
+ Download and summarize Twitter/X posts, save media into Minis, and return chat-ready Markdown.
## When to Use
- - User provides a twitter.com or x.com URL
- - User asks to download video/images/GIF from a tweet
- - User asks “这条推文里有什么/what’s in this tweet” and you may also need media links/files
+ - User provides a twitter.com or x.com status URL.
+ - User asks to download Twitter/X images, GIFs, or videos.
+ - User asks what a tweet says/contains.
+ - User wants downloaded media inserted/displayed in chat as Markdown.
## What It Does
- 1. Parse username and status ID from any Twitter/X URL variant
- 2. Fetch tweet JSON from api.fxtwitter.com (fallback api.vxtwitter.com)
- 3. Produce a short summary (author, handle, created time, text, sensitive flag)
- 4. Extract direct media URLs (best bitrate for videos when available)
- 5. Optionally download photos, thumbnails, and videos to a local folder and return Minis links
+ 1. Parses username and tweet/status ID from Twitter/X URL variants.
+ 2. Fetches structured JSON from `api.fxtwitter.com`, with fallback to `api.vxtwitter.com`.
+ 3. Generates a short summary:
+ - author
+ - text
+ - created time if available
+ - sensitive flag
+ - original media URLs
+ 4. Downloads images, video thumbnails, GIF/video files by default.
+ 5. Returns Markdown containing:
+ - `## 推文摘要`
+ - summary/raw JSON links
+ - inline media syntax for images/thumbnails/videos/GIFs: ``
## Dependencies
- - curl
- - jq
+ - `curl`
+ - `jq`
+ - `python3`
- The helper script auto-installs missing packages: `apk add --no-cache curl jq`.
+ The helper script auto-installs missing packages with `apk add --no-cache`.
## Helper Script
- Path: /var/minis/skills/twitter-downloader/scripts/twitter_downloader.sh
+ Path:
+ `/var/minis/skills/twitter-downloader/scripts/twitter_downloader.sh`
Usage:
- - Summarize only
- /var/minis/skills/twitter-downloader/scripts/twitter_downloader.sh "<URL>"
- - Download images and/or video to a directory
- /var/minis/skills/twitter-downloader/scripts/twitter_downloader.sh "<URL>" --dir "/var/minis/workspace/tweet_media" --images --video
+ ```sh
+ /var/minis/skills/twitter-downloader/scripts/twitter_downloader.sh "<tweet_url>"
+ ```
- Outputs:
- - JSON: DIR/<tweet_id>.json
- - Summary: DIR/<tweet_id>_summary.txt
- - Media (if downloaded): DIR/<tweet_id>/...
+ Options:
+ ```sh
+ --dir DIR Output directory, default /var/minis/workspace/tweet_media
+ --images Download images/thumbnails only in addition to summary
+ --video Download videos/GIFs only in addition to summary
+ --all Download images/thumbnails and videos/GIFs; default when no media flag is provided
+ --no-download Only fetch summary/JSON and return Markdown links for those files
+ --json-only Fetch and print raw tweet JSON only; no Markdown output
+ ```
+ Examples:
+ ```sh
+ # Default: download all available media and output Markdown
+ /var/minis/skills/twitter-downloader/scripts/twitter_downloader.sh "https://x.com/user/status/123"
+
+ # Summary only, no media downloads
+ /var/minis/skills/twitter-downloader/scripts/twitter_downloader.sh "https://x.com/user/status/123" --no-download
+
+ # Custom output directory
+ /var/minis/skills/twitter-downloader/scripts/twitter_downloader.sh "https://x.com/user/status/123" --dir "/var/minis/workspace/tweet_media"
+ ```
+
+ Generated files:
+ ```text
+ /var/minis/workspace/tweet_media/<tweet_id>.json
+ /var/minis/workspace/tweet_media/<tweet_id>_summary.txt
+ /var/minis/workspace/tweet_media/<tweet_id>/<media files>
+ ```
+
## Agent Workflow
- 1) Normalize input URL (accept any twitter.com or x.com format).
- 2) Run the helper script without downloads to get summary + links.
- 3) If the user wants files in chat, re-run with --images/--video and show Minis links:
- - Example: [tweet_media/<id>.json](minis://workspace/tweet_media/<id>.json)
- - Example folder: [tweet_media/<id>/](minis://workspace/tweet_media/<id>/)
- 4) If analysis is requested, pass downloaded image/thumbnail files to vision and describe content.
+ 1. Run the helper script with the tweet URL.
+ 2. Paste stdout directly into chat.
+ 3. Do not merely mention the folder path; include generated Markdown links.
+ 4. Keep images, thumbnails, videos, and GIFs as inline media syntax:
+ ``
+ 5. Keep JSON/text summary files as normal links:
+ `[filename](minis://...)`
+ 6. If `Sensitive: True`, preserve that field and avoid adding explicit extra descriptions unless the user asks.
- ## Error Handling
- - If URL parsing fails: ask for a valid twitter.com/x.com status URL
- - If fxtwitter fails: auto-retry with vxtwitter; if both fail, report outage and suggest trying later
- - If the tweet is deleted/private: explain that media/text may be unavailable
+ ## Output Format
+ The helper outputs Markdown similar to:
- ## Safety
- - Respect `possibly_sensitive`; don’t auto-render explicit content; describe neutrally if asked
+ ```md
+ ## 推文摘要
+ - Author: ...
+ - Text: ...
+ - Created: ...
+ - Sensitive: false
+ - Media:
+ - photo https://...
+ - Downloaded images: 1, videos: 1
+
+ ## 文件链接
+
+ - [summary.txt](minis://workspace/...)
+ - [raw.json](minis://workspace/...)
+
+ ## 媒体
+
+ 
+
+ 
+ ```
+
+ ## Error Handling
+ - If URL parsing fails, ask for a valid `twitter.com`/`x.com` status URL.
+ - If both APIs fail, report that the tweet may be private/deleted or the API may be temporarily unavailable.
+ - If no media is found, still return the tweet summary and JSON/summary links.
+
## Notes
- - Videos may include multiple variants; the script picks the highest bitrate when available
- - Thumbnails (JPEG) are downloaded for video/GIF if `--images` is set (useful for quick vision analysis)
+ - Video/GIF downloads choose the best bitrate variant when available.
+ - Video/GIF thumbnails are downloaded when image download is enabled.
+ - Minis URLs are percent-encoded by the helper.