SuperAPI AI Directory

x-to-obsidian

General & other

View repository

Updated 10-16 08:45

About this skill

x-to-obsidian

Preserve valuable content from X into an Obsidian vault to build a searchable knowledge asset.

Positioning

X's native UI is not conducive to long-term review: threads are scattered across the timeline, Article layout is messy, links easily break, and search is weak. This skill archives high-quality long-form content from X into Obsidian in one click:

  • Full thread unroll
  • X Article fetches the full content content.blocks
  • Complete metadata (author, metrics, direct media links, created_at)
  • frontmatter topic double links, convenient for MOC aggregation
  • Multilingual recognition (zh / en / ja / ko)

Prerequisites

  • Obsidian vault (any structure)

  • Python 3, pure stdlib (no third-party dependencies, archiving a single tweet)

  • Optional:pip install telethon(only for MTProto sync)

  • Set environment variables:

    export OBSIDIAN_VAULT=~/Documents/MyVault
    # 可选:自定义归档子目录(默认 "Articles")
    export OBSIDIAN_ARTICLES="Articles"
    # 可选:段标题语言,默认 zh(中文),设 en 用英文标题
    export X_ARCHIVE_LANG=zh
    

Core API: fxtwitter

Replace x.com in the X URL with api.fxtwitter.com, then directly GET back JSON. No X API key, no login, zero cost.

Key field Purpose
tweet.text / tweet.raw_text.text Tweet body
tweet.article.title X Article title
tweet.article.content.blocks[] Article long-form blocks
tweet.replying_to_status Previous tweet (thread backtracking)
tweet.quote Quoted tweet
tweet.media[] Media (direct image/video links)
tweet.created_timestamp UNIX timestamp
tweet.views / likes / bookmarks / retweets metrics

Fallback: fxtwitter fails → cdn.syndication.twimg.com public endpoint.

Trigger words

User says Invoke
"Archive this X: URL" / "archive this: URL" archive_x.py <URL>
"Archive and translate: URL" archive_x.py <URL> + AI fills the "Chinese translation" section
"Organize this thread: URL" Same as above, force thread backtracking
"Sync my Telegram Saved Messages" + provide JSON path sync_telegram_export.py <path> --dry-run Check first, run for real after confirmation
"Sync Telegram with API" (credentials already available) sync_telegram_saved.py

Workflow (default archiving)

  1. Parse URL → handle + status_id
  2. Call script archive_x.py <URL>
  3. The script checks whether the vault has already archived it (by frontmatter url: field)
    • Exists → output SKIP, exit
    • Otherwise → fetch fxtwitter, write to vault
  4. AI then supplements: 1-sentence Chinese ## 摘要 + 1-3 topics double links + people double links
  5. The "My thoughts" section is always left blank for the user

Two Telegram sync paths

A. JSON export (recommended, zero risk)

Telegram Desktop
  → Settings → Advanced → Export Telegram data
  → 勾「私聊」+ 选 JSON 格式
  → 得到 result.json
python3 sync_telegram_export.py <result.json> --dry-run   # 看清单
python3 sync_telegram_export.py <result.json>             # 实跑

Automatically deduplicates by URL and automatically skips already-archived items. Export once a month for incremental syncing.

B. MTProto API (advanced, use with caution in mainland China)

Requires:

  • https://my.telegram.org/auth apply for api_id / api_hash
  • Run generate_telegram_session.py to get session_string
  • Residential IP (users in mainland China must use HK/JP residential ranges; datacenter IPs will definitely trigger ERROR)

⚠️ Users in mainland China should prefer option A. Creating an app at my.telegram.org in mainland China almost inevitably triggers IP risk control; repeated attempts will trigger an account-level 24-72h freeze.

File naming

<YYYY-MM-DD>-X-<handle>-<title前 50 字>.md

Example:

  • 2026-05-24-X-cyrilXBT-How-to-Organize-Your-Obsidian-Vault.md
  • 2026-05-29-X-ObsidianOtaku-保存版AIエージェントのためのObsidian活用術.md

Multiple posts by the same author on the same day → append at the end -<status_id 后 6 位>。

Output frontmatter

---
tags: [文章摘抄]
source: X
url: https://x.com/<handle>/status/<id>
author: <显示名>
handle: "@<handle>"
published_at: YYYY-MM-DD HH:mm
captured_at: YYYY-MM-DD HH:mm
language: zh / en / ja / ko
type: tweet / thread / article
topics: ["[[xxx]]", ...]   # AI 填
people: ["[[xxx]]", ...]   # AI 填
media: [...] / 0
content_complete: true
metrics:
  views: N
  likes: N
  bookmarks: N
---

Boundaries and exceptions

Scenario Handling
fxtwitter returns 404 Tweet deleted/private, suggest checking archive.org
fxtwitter 5xx Retry once; if it fails, fall back to the syndication endpoint
URL is not x.com / twitter.com Reject, suggest using Web Clipper
Tweet text is empty and there is no article and no media Warning: "Pure retweet/pure reply, may have no standalone content"
Duplicate filenames for the same author on the same day Append at the end -<status_id 后 6 位>
Video media frontmatter media[] Record the mp4 direct link, do not embed

Command-line reference

# 归档单条
python3 archive_x.py <URL>
python3 archive_x.py <URL> --force                  # 覆盖已归档
python3 archive_x.py <URL> --vault /path/to/vault   # 覆盖环境变量

# Telegram JSON 导出同步
python3 sync_telegram_export.py <result.json>
python3 sync_telegram_export.py <result.json> --dry-run
python3 sync_telegram_export.py <result.json> --since 2026-06-01
python3 sync_telegram_export.py <result.json> --limit 30

# MTProto 同步(需先 setup)
python3 generate_telegram_session.py    # 一次性
python3 sync_telegram_saved.py --dry-run
python3 sync_telegram_saved.py --days 30
python3 sync_telegram_saved.py --all