viralx

name	viralx
description	Call the ViralX web API from Codex to search TikTok topics, collect video evidence, run shot analysis, and return reports. Use when the user asks to invoke ViralX or analyze a TikTok/Douyin video with ViralX; do not use for generic frontend work.

ViralX

Use ViralX through its web API contract. The installed skill can probe the public site, but a complete analysis needs a local ViralX runtime because TK Note, source files, ShotLoom Core and any optional LibTV CLI login live on the user's computer.

Route the request

• For a TikTok or Douyin URL, call analyze directly. TikTok Scraper7 is not involved.
• For a search topic, call analyze with the topic. This requires RAPIDAPI_KEY for TikTok Scraper7 discovery.
• Every analysis follows one contract: TikTok Scraper7 discovery when needed, TK Note collection, provider-neutral shot evidence, evidence merge, then the selected final model API. The recommended shot strategy is auto: ShotLoom Core first, LibTV only as an auditable fallback.
• Before analyze, run ViralX locally, set VIRALX_BASE_URL=http://127.0.0.1:5001, choose VIRALX_SHOT_ENGINE, configure a compatible shot vision model, then provide MODEL_PROVIDER, MODEL_API_KEY, and MODEL_NAME. Connect LibTV from /settings only when libtv is selected or wanted as an auto fallback.
• The hosted website's Connector is a browser-only session bridge and is not an Agent credential. Never send a LibTV token or Connector session to EdgeOne.
• Use health before analysis when credential or service readiness is unknown.
• Use keywords only when the user asks for existing or suggested topics.

Run the bundled client

Resolve paths relative to this SKILL.md, then run the script with Python 3:

python scripts/viralx.py health
python scripts/viralx.py keywords
python scripts/viralx.py analyze "https://www.tiktok.com/@creator/video/123"
python scripts/viralx.py analyze "camping light" --min-likes 5000

The analyze command writes ViralX NDJSON events to stdout. Preserve shot_provider, shot_status, shot_evidence_quality, shot_block_reason, fallback_chain, evidence fields, and report content when summarizing. Treat blocked as a failed analysis even when TK Note collection succeeded; never invent a report.

Use --output <path> only when the user asks to save the NDJSON stream. Set VIRALX_BASE_URL=http://127.0.0.1:5001 to call a local ViralX web server instead of production.

Credentials and safety

• Read credentials from environment variables only. Never request that a user paste a key into chat when they can set it locally.
• Never pass secrets as CLI arguments, print request headers, or write credentials to output files.
• A direct URL skips TikTok Scraper7 but still needs TK Note, a ready shot-evidence strategy, and the selected final model API key. LibTV login is not mandatory when ShotLoom Core is ready.
• A keyword request needs those same dependencies plus RAPIDAPI_KEY.
• The EdgeOne endpoint deliberately refuses full analysis because it cannot access local evidence or CLI state. Do not claim the public interface alone completed an analysis.

Read references/runtime.md only for credential mapping, output contracts, installation, or troubleshooting.