wuaishare/sharextract

¿Qué hace sharextract?

Extract public shared content with the highest-fidelity, lowest-cost method available and preserve how the content was obtained.

Workflow

1. Treat the supplied URL as public input only. Never reuse browser cookies, session tokens, credentials, or private connector data unless the user explicitly requests an authenticated workflow and the platform permits it.
2. Run: python -m sharextract "URL" --format json
3. Prefer the result with the strongest provenance:
   • documented public API, open syndication standards (RSS/Atom), or oEmbed;
   • first-party public JSON/hydration data;
   • JSON-LD/OpenGraph/structured HTML;
   • specialized public-content extractor such as yt-dlp;
   • readable static HTML;
   • browser rendering only when a public page genuinely requires JavaScript.
4. Inspect extraction_method, confidence, warnings, canonical_url, and metadata before using the result downstream. For feeds, use metadata.feed.entries; for transcripts, use metadata.transcript.cues; for ordinary pages, metadata.syndication_feeds and metadata.subtitle_tracks may expose declared public follow-up resources.
5. Preserve the original meaning and media references. Do not silently invent missing text, authorship, timestamps, or platform metadata.
6. If a specialized route fails, allow the router to fall back and report the failed route in warnings.
7. Stop rather than bypass login walls, CAPTCHAs, paywalls, WAF challenges, private links, or other access controls.

Commands

Default normalized JSON:

python -m sharextract "https://example.com/share/..." --format json

Readable Markdown:

python -m sharextract "https://example.com/article" --format markdown

Force general web extraction:

python -m sharextract "https://example.com/article" --strategy web

Media metadata only:

python -m sharextract "https://www.youtube.com/watch?v=..." --strategy media

Optional higher-quality web/media dependencies:

python -m pip install -e ".[all]"

Optional service surfaces:

python -m pip install -e ".[mcp,service]"
sharextract-mcp
sharextract-api --port 8787

Use the service layers only as transports around the same public-content extraction contract; platform-specific logic belongs in adapters, not in MCP/HTTP handlers.

Output contract

The JSON result contains source_url, canonical_url, platform, kind, extraction_method, confidence, title, author, text, markdown, optional html, normalized messages, media references, metadata, warnings, and retrieved_at.

Read references/platform-matrix.md when deciding how a platform should be handled. Read references/adding-adapters.md before adding or modifying a platform adapter. Read references/ecosystem.md when deciding whether to reuse an existing open-source extractor instead of writing a new one.

Guardrails

ShareXtract is for content that is already public to the requester. It is not an anti-bot bypass framework. Do not add stealth, CAPTCHA solving, credential harvesting, signature circumvention, mass account rotation, or access-control bypasses.

For unstable first-party endpoints, label them as undocumented and keep a public-page fallback. Prefer adapters that can be tested with static fixtures and that fail closed when content cannot be verified.

Kuaishou public video metadata

For Kuaishou public videos, prefer a current official v.kuaishou.com or kuaishou.com/f/ Share / Copy Link URL. The native adapter consumes anonymous PC-page Apollo SSR from the same public redirect response and exports metadata only. Bare short-video URLs may omit visionVideoDetail; when that happens, request a fresh official share link instead of creating did cookies or calling the private GraphQL detail API. Never export photoUrl, manifest, adaptive-representation, or temporary CDN MP4 URLs from Apollo state.

Xiaohongshu public notes

For Xiaohongshu notes, use a current official Share / Copy Link URL or an official xhslink short link. ShareXtract consumes an existing xsec_token from that public URL and reads first-party SSR initial state; it does not generate/refresh tokens or implement X-s/X-t request signing. Bare note URLs without a current token should be rejected with guidance to obtain a fresh official share link. Do not export temporary video/subtitle stream URLs embedded in note state.

Douyin public video metadata

For direct public Douyin video URLs or v.douyin.com short links, use the native metadata-only adapter through extract(). It reads the anonymous first-party Jingxuan SSR/VideoObject surface using a normal mobile-browser representation. Do not export temporary playback/download URLs from embedded video_model data, and do not add a_bogus, device signatures, copied cookies, or logged-in session state.

TikTok public videos

For direct public TikTok video URLs, use the native documented oEmbed route through the normal extract() router. No TikTok user authorization or access token is required for this oEmbed path. Do not substitute authenticated Display API access for ordinary public embed metadata.

Weibo public statuses

For public Weibo status URLs, use the native adapter through the normal extract() router. It uses Weibo's anonymous mobile PWA JSON route and requests the public extend route only for statuses marked isLongText. Do not add login cookies or authenticated session state when the public PWA route is unavailable.

Zhihu public content

For Zhihu public answers and Zhuanlan articles, use the native adapters through the normal extract() router. The answer adapter uses Zhihu's anonymous public Tardis SSR reader; the article adapter prefers public embedded initial state with Tardis fallback. Do not add x-zse, d_c0, copied cookies, or logged-in browser state to make a blocked Zhihu API route work.

Adapter health

Before depending on a fragile platform route in an automated workflow, inspect deterministic health with:

python -m sharextract --health

For explicit release/protocol verification, use --live only against the fixed public samples in the registry. Do not turn arbitrary target URLs into health probes. See references/adapter-health.md.