xapi-to 0.1.18 → 0.1.20

package/skills/xapi/guides/ws_gateway.md

@@ -0,0 +1,206 @@
+# WebSocket Gateway Guide
+
+Use xAPI's WebSocket Gateway for full-duplex, low-latency sessions such as OpenAI Realtime, streaming speech recognition, bidirectional text-to-speech, simultaneous interpretation, and podcast generation.
+
+The WebSocket Gateway shares the public `ai.xapi.to` host with the HTTP AI Gateway, but it is a separate protocol surface. An HTTP request continues to use the AI Gateway; a valid WebSocket Upgrade request is routed to the WebSocket Gateway.
+
+## Contents
+
+- [Choose the right interface](#choose-the-right-interface)
+- [Public URLs and routing](#public-urls-and-routing)
+- [Authentication](#authentication)
+- [OpenAI Realtime example](#openai-realtime-example)
+- [Browser connections](#browser-connections)
+- [Native protocol endpoints](#native-protocol-endpoints)
+- [Volcengine ASR options](#volcengine-asr-options)
+- [Connection behavior and billing](#connection-behavior-and-billing)
+- [Errors and reconnects](#errors-and-reconnects)
+- [Security](#security)
+
+## Choose the right interface
+
+Use:
+
+- `npx xapi-to call ai.*` for one-off CLI calls with JSON input and output;
+- the HTTP AI Gateway in `guides/ai_gateway.md` for Anthropic/OpenAI-compatible request-response APIs and SSE streaming;
+- the WebSocket Gateway for a persistent, bidirectional session with text, audio, or provider-native binary frames.
+
+Do not send a WebSocket request through `npx xapi-to call`. The CLI action envelope (`action_id` / `input`) and HTTP Gateway request bodies do not apply after a WebSocket connection is established.
+
+## Public URLs and routing
+
+Preferred unified form:
+
+```text
+wss://ai.xapi.to/<endpoint-path>
+```
+
+Current curated production paths include:
+
+| Path | Protocol | Typical use |
+|---|---|---|
+| `/v1/realtime` | OpenAI Realtime GA JSON events | Realtime text and voice |
+| `/v1/asr` | Volcengine ASR binary frames | Streaming speech recognition |
+| `/v1/tts` | Doubao bidirectional TTS binary frames | Streaming text-to-speech |
+| `/v1/ast` | Doubao AST v4 protobuf frames | Simultaneous interpretation |
+| `/v1/podcast` | Doubao podcast binary frames | Long-form podcast generation |
+
+The catalog is dynamic. Confirm the path and wire protocol shown by the current xAPI service before building against it.
+
+The unified host resolves a connection by exact path. A unique active endpoint is selected directly. If several endpoints share `/v1/realtime`, the unified route prefers the native `openai-realtime` endpoint. It does not currently use `?model=` to select another realtime provider.
+
+For a specific third-party service, use its service host when provided:
+
+```text
+wss://<service-slug>.p.xapi.to/<endpoint-path>
+```
+
+This avoids shared-path ambiguity and is required when the desired service uses a provider-native protocol that is not selected by the unified path. Console Try-It and review workflows can also address an endpoint exactly with `?endpoint=<endpoint-id>`.
+
+## Authentication
+
+Use the same xAPI key as the CLI and HTTP Gateway. Server-side clients should send one of these handshake headers:
+
+```text
+XAPI-Key: <XAPI_KEY>
+Authorization: Bearer <XAPI_KEY>
+x-api-key: <XAPI_KEY>
+```
+
+Example with `wscat`:
+
+```bash
+wscat -c "wss://ai.xapi.to/v1/realtime" \
+  -H "XAPI-Key: $XAPI_KEY"
+```
+
+The Gateway also accepts `?token=<XAPI_KEY>` or `?xapi-key=<XAPI_KEY>` for clients that cannot set headers. Avoid query authentication for long-lived keys: URLs are commonly retained in browser history, access logs, error reports, and monitoring systems.
+
+Authentication is checked before the WebSocket upgrade. Invalid handshakes therefore return an HTTP status instead of opening and immediately closing a socket.
+
+## OpenAI Realtime example
+
+The unified `/v1/realtime` route speaks the OpenAI Realtime GA JSON event protocol. It is native passthrough: send the same events you would send to the upstream Realtime API, but authenticate with the xAPI key.
+
+```javascript
+import WebSocket from "ws";
+
+const ws = new WebSocket("wss://ai.xapi.to/v1/realtime", {
+  headers: { "XAPI-Key": process.env.XAPI_KEY },
+});
+
+ws.on("message", (raw, isBinary) => {
+  if (isBinary) return;
+  const event = JSON.parse(raw.toString());
+
+  if (event.type === "session.created") {
+    ws.send(JSON.stringify({
+      type: "conversation.item.create",
+      item: {
+        type: "message",
+        role: "user",
+        content: [{ type: "input_text", text: "Say hello in one sentence." }],
+      },
+    }));
+    ws.send(JSON.stringify({ type: "response.create" }));
+  }
+
+  if (event.type === "response.done") {
+    console.log(event.response);
+    ws.close(1000, "done");
+  }
+
+  if (event.type === "error") console.error(event.error);
+});
+```
+
+Do not send the retired `OpenAI-Beta: realtime=v1` header. Session settings, audio buffers, tool calls, and response events follow the current OpenAI Realtime GA shape.
+
+## Browser connections
+
+The browser `WebSocket` API cannot set arbitrary handshake headers. The Gateway accepts an xAPI key or temporary token through a subprotocol entry:
+
+```javascript
+const temporaryToken = await getTemporaryTokenFromYourBackend();
+const ws = new WebSocket(
+  "wss://ai.xapi.to/v1/realtime",
+  [`xapi-key.${temporaryToken}`],
+);
+```
+
+Never embed a long-lived xAPI key in frontend JavaScript. Use the authenticated xAPI Console Try-It flow or your backend to obtain a short-lived token, then pass only that token to the browser. The Console's `POST /api/keys/ws-token` flow mints a temporary token for a WebSocket endpoint; it requires a logged-in entity account and an endpoint ID, and is not authenticated with a normal xAPI key.
+
+If a browser integration must use `?token=`, use only a short-lived token and avoid logging the complete URL.
+
+## Native protocol endpoints
+
+The Gateway forwards frames without translating the application protocol. The selected adapter extracts usage for billing and observability, but the client still has to speak the endpoint's native wire format.
+
+| Adapter | Client frames | Important client requirement |
+|---|---|---|
+| `openai-realtime` | UTF-8 JSON text | Use OpenAI Realtime GA events. |
+| `volcengine-asr` | Binary | Send the Volcengine ASR header/config/audio frame sequence; PCM configuration must match the audio bytes. |
+| `doubao-realtime` | Binary | Use the Doubao end-to-end realtime dialogue protocol through its service host or exact endpoint. |
+| `doubao-tts` | Binary | Use the bidirectional TTS event sequence; audio responses are provider-native frames. |
+| `doubao-ast` | Binary protobuf | Each message follows Doubao AST v4 protobuf framing. |
+| `doubao-podcast` | Binary | Use the Doubao podcast event protocol and complete input metadata. |
+
+Do not send JSON copied from the OpenAI Realtime API to a Doubao binary endpoint. The shared `ai.xapi.to` hostname does not imply a shared event schema, and the Gateway does not currently translate OpenAI Realtime events into Doubao events.
+
+For binary services, prefer the service's xAPI Try-It client or the provider protocol documentation. `wscat` can prove that a handshake succeeds, but it is not sufficient for a functional ASR, TTS, AST, or podcast test.
+
+## Volcengine ASR options
+
+The `/v1/asr` adapter exposes these per-session fields in the native config frame's `request` object:
+
+| Field | Default | Meaning |
+|---|---:|---|
+| `enable_punc` | `true` | Insert punctuation. |
+| `enable_itn` | `true` | Normalize spoken numbers, dates, and amounts. |
+| `enable_ddc` | `false` | Remove filler words and repeated speech. |
+| `show_utterances` | `false` | Return utterance boundaries and timestamps. |
+| `result_type` | `full` | Use `full` for cumulative text or `single` for incremental fragments. |
+
+Audio must be raw PCM, 16-bit, mono, at 16 kHz (default) or 8 kHz. The rate declared in the config frame must exactly match the bytes sent. The ASR `model_name` is fixed by the selected endpoint and is not a caller-selectable option.
+
+## Connection behavior and billing
+
+- Frames are forwarded as text or binary without changing their order. The maximum accepted WebSocket message payload is currently 4 MiB.
+- The default idle timeout is 120 seconds, but an endpoint can override it. Send valid application traffic and let the WebSocket library answer ping frames automatically.
+- Maximum session duration is endpoint-specific. Reconnect when the application needs a longer conversation.
+- The default per-key limits are 10 concurrent connections and 60 connection attempts per minute; an endpoint can configure lower or higher values.
+- Billing is endpoint-specific: duration, realtime token usage, or input characters. The Gateway can reserve balance at handshake and settles usage when the connection closes.
+- Unlike HTTP AI Gateway routing, a WebSocket session is pinned to one resolved endpoint and upstream. There is no transparent mid-session provider fallback.
+
+## Errors and reconnects
+
+Handshake failures:
+
+| HTTP status | Meaning |
+|---|---|
+| `400` | The selected endpoint is not a valid WebSocket endpoint or its upstream is unavailable by policy. |
+| `401` | API key is missing, invalid, or expired. |
+| `402` | Balance is insufficient for the initial reservation. |
+| `404` | No active endpoint matches the host, path, or explicit endpoint ID. |
+| `429` | Per-key concurrency or connection-rate limit was exceeded. |
+
+After upgrade, important close codes include:
+
+| Close code | Meaning |
+|---|---|
+| `1000` | Normal close, idle timeout, or configured maximum duration. |
+| `1001` | Gateway is updating or draining; reconnect after a delay. |
+| `1011` | Upstream connection, timeout, backpressure, or internal gateway failure. |
+| `4401` | The key expired or was revoked while the session was open. |
+| `4402` | Available balance was exhausted during the session. |
+
+Reconnect only for recoverable conditions such as `1001`, transient `1011`, or a failed handshake caused by rate limiting. Use exponential backoff with jitter, cap the delay, and stop retrying on authentication, balance, or endpoint errors until the underlying problem is corrected. Recreate session state after reconnect; the Gateway does not resume prior provider sessions.
+
+Use a real WebSocket client to test connectivity. A hand-written `curl` Upgrade request can be changed by an intermediary and produce a misleading HTTP response.
+
+## Security
+
+- Send xAPI credentials only to `*.xapi.to` hosts.
+- Prefer handshake headers for server-side clients and short-lived tokens for browsers.
+- Never put a long-lived key in source code, frontend bundles, query strings, screenshots, or logs.
+- Treat endpoint-specific audio, transcripts, prompts, and generated media as sensitive application data.

package/skills/xapi/guides/xiaohongshu.md

@@ -0,0 +1,315 @@
+# 小红书 (Xiaohongshu / RedNote) Guide
+
+Complete guide for Xiaohongshu (小红书) operations via xAPI — user profiles, notes, comments, search, topics, products, and creator inspiration.
+
+> **Dynamic catalog:** These are database-registered third-party APIs under the `xiaohongshu` service. Exact action IDs, HTTP methods, parameters, and response fields can change. Run `search` and `get` before calling; the current schema wins. Examples below reflect one known GET-based version and keep `"method":"GET"` in the input for compatibility.
+
+**Tip:** Many endpoints accept both a direct ID (e.g. `user_id`, `note_id`) and a `share_text` (share link). You can use either one.
+
+## Contents
+
+- [User data](#user-data)
+- [Note data](#note-data)
+- [Search](#search)
+- [Topics](#topics)
+- [Products](#products-商品)
+- [Creator inspiration](#creator-inspiration-创作灵感)
+- [Common workflows](#common-workflows)
+- [Pagination](#pagination-patterns)
+- [API reference](#api-reference)
+- [Error handling](#error-handling)
+
+## User Data
+
+### Get user info
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_get__user__info \
+  --input '{"method":"GET","params":{"user_id":"<user_id>"}}'
+```
+
+Can also pass `share_text` (share link) instead of `user_id`.
+
+### Get user's posted notes
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_get__user__posted__notes \
+  --input '{"method":"GET","params":{"user_id":"<user_id>"}}'
+```
+
+Optional parameters:
+- `cursor` — pagination cursor, leave empty for first request; pass last `note_id` from previous response
+- `share_text` — can use share link instead of `user_id`
+
+### Get user's faved notes
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_get__user__faved__notes \
+  --input '{"method":"GET","params":{"user_id":"<user_id>"}}'
+```
+
+Optional parameters:
+- `cursor` — pagination cursor, pass last `note_id` from previous response
+- `share_text` — share link alternative
+
+## Note Data
+
+### Get image note detail
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_get__image__note__detail \
+  --input '{"method":"GET","params":{"note_id":"<note_id>"}}'
+```
+
+Use this for image-type notes. Can also pass `share_text` instead of `note_id`.
+
+### Get video note detail
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_get__video__note__detail \
+  --input '{"method":"GET","params":{"note_id":"<note_id>"}}'
+```
+
+Use this for video-type notes. Can also pass `share_text` instead of `note_id`.
+
+### Get mixed note detail
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_get__mixed__note__detail \
+  --input '{"method":"GET","params":{"note_id":"<note_id>"}}'
+```
+
+Auto-detects note type (image or video) from feed. Can also pass `share_text` instead of `note_id`.
+
+**Tip:** If you don't know whether a note is image or video, use `get__mixed__note__detail` — it handles both types.
+
+### Get note comments
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_get__note__comments \
+  --input '{"method":"GET","params":{"note_id":"<note_id>","index":0}}'
+```
+
+Optional parameters:
+- `index` — comment index, pass `0` for first request
+- `cursor` — pagination cursor, leave empty for first request
+- `sort_strategy` — `default`, `latest_v2` (最新), `like_count` (最热)
+- `share_text` — share link alternative
+
+## Search
+
+### Search notes
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_search__notes \
+  --input '{"method":"GET","params":{"keyword":"咖啡推荐","page":1}}'
+```
+
+Optional parameters:
+- `page` — page number, start from 1
+- `note_type` — `不限` (all), `视频笔记` (video), `普通笔记` (image), `直播笔记` (live)
+- `sort_type` — sort type
+- `time_filter` — `不限` (all), `一天内` (1 day), `一周内` (1 week), `半年内` (6 months)
+- `ai_mode` — `0` = off, `1` = on (AI-enhanced search)
+- `search_id` — for pagination consistency
+- `search_session_id` — for pagination consistency
+
+### Search users
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_search__users \
+  --input '{"method":"GET","params":{"keyword":"美食博主","page":1}}'
+```
+
+Optional: `page`, `search_id`.
+
+### Search images
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_search__images \
+  --input '{"method":"GET","params":{"keyword":"壁纸","page":1}}'
+```
+
+Optional: `page`, `search_id`, `word_request_id`, `search_session_id`.
+
+### Search groups
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_search__groups \
+  --input '{"method":"GET","params":{"keyword":"摄影","page_no":0}}'
+```
+
+Optional parameters:
+- `page_no` — page number, start from **0** (not 1)
+- `is_recommend` — `0` = no, `1` = yes
+- `search_id` — for pagination
+
+### Search products
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_search__products \
+  --input '{"method":"GET","params":{"keyword":"面霜","page":1}}'
+```
+
+Optional: `page`, `search_id`.
+
+## Topics
+
+### Get topic info
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_get__topic__info \
+  --input '{"method":"GET","params":{"page_id":"<topic_page_id>"}}'
+```
+
+Optional: `note_id` — pass when jumping from a specific note to its topic.
+
+### Get topic feed
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_get__topic__feed \
+  --input '{"method":"GET","params":{"page_id":"<topic_page_id>","sort":"trend"}}'
+```
+
+Optional parameters:
+- `sort` — `trend` (最热), `time` (最新)
+- `cursor_score` — pagination cursor score for next page
+- `last_note_id` — last note ID from previous page
+- `last_note_ct` — last note create time from previous page
+- `session_id` — keep consistent across pagination
+- `first_load_time` — keep consistent across pagination
+
+## Products (商品)
+
+### Get product detail
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_get__product__detail \
+  --input '{"method":"GET","params":{"sku_id":"<sku_id>"}}'
+```
+
+### Get product reviews
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_get__product__reviews \
+  --input '{"method":"GET","params":{"sku_id":"<sku_id>","page":0}}'
+```
+
+Optional parameters:
+- `page` — page number, start from **0**
+- `sort_strategy_type` — `0` = general, `1` = latest
+- `share_pics_only` — `0` = all reviews, `1` = only reviews with images
+
+### Get product review overview
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_get__product__review__overview \
+  --input '{"method":"GET","params":{"sku_id":"<sku_id>"}}'
+```
+
+Optional: `tab`.
+
+### Get product recommendations
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_get__product__recommendations \
+  --input '{"method":"GET","params":{"sku_id":"<sku_id>"}}'
+```
+
+Optional: `cursor_score` for pagination, `region`.
+
+## Creator Inspiration (创作灵感)
+
+### Get creator inspiration feed
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_get__creator__inspiration__feed \
+  --input '{"method":"GET","params":{}}'
+```
+
+Optional parameters:
+- `tab` — tab type
+- `cursor` — pagination cursor
+
+### Get creator hot inspiration feed
+
+```bash
+npx xapi-to call xiaohongshu.api_v1_xiaohongshu_app__v2_get__creator__hot__inspiration__feed \
+  --input '{"method":"GET","params":{}}'
+```
+
+Optional: `cursor` for pagination.
+
+## Common Workflows
+
+### Research a Xiaohongshu user
+
+1. Get user info: `xiaohongshu...get__user__info` with `user_id` → profile, follower stats
+2. Get posted notes: `xiaohongshu...get__user__posted__notes` → browse content
+3. Get faved notes: `xiaohongshu...get__user__faved__notes` → what they like
+
+### Analyze a note
+
+1. Get note detail: `xiaohongshu...get__mixed__note__detail` with `note_id` → full note data
+2. Get comments: `xiaohongshu...get__note__comments` with `sort_strategy=like_count` → top comments
+
+### Discover content by topic
+
+1. Get topic info: `xiaohongshu...get__topic__info` with `page_id` → topic metadata
+2. Get topic feed: `xiaohongshu...get__topic__feed` with `sort=trend` → trending notes in topic
+
+### Research a product
+
+1. Get product detail: `xiaohongshu...get__product__detail` with `sku_id` → product info
+2. Get review overview: `xiaohongshu...get__product__review__overview` → rating summary
+3. Get reviews: `xiaohongshu...get__product__reviews` → detailed reviews
+4. Get recommendations: `xiaohongshu...get__product__recommendations` → similar products
+
+### Search content
+
+1. Search notes: `xiaohongshu...search__notes` with `keyword` → find relevant notes
+2. Search users: `xiaohongshu...search__users` → find creators
+3. Search products: `xiaohongshu...search__products` → find products
+
+## Pagination Patterns
+
+| Pattern | Endpoints | How to use |
+|---------|-----------|------------|
+| `cursor` (note_id) | user posted/faved notes | Pass last `note_id` from previous response |
+| `cursor` | comments, creator feed, product recommendations | Pass `cursor` from previous response |
+| `page` (from 1) | search notes/users/images/products | Increment `page` by 1 |
+| `page_no` (from 0) | search groups | Increment `page_no` by 1 |
+| `page` (from 0) | product reviews | Increment `page` by 1 |
+| `cursor_score` + `last_note_id` | topic feed | Pass both from previous response |
+
+## API Reference
+
+| API (prefix: `xiaohongshu.api_v1_xiaohongshu_app__v2_`) | Description | Key Params |
+|---|---|---|
+| `get__user__info` | User profile | `user_id` or `share_text` |
+| `get__user__posted__notes` | User's notes | `user_id`, `cursor` |
+| `get__user__faved__notes` | User's favorites | `user_id`, `cursor` |
+| `get__image__note__detail` | Image note detail | `note_id` or `share_text` |
+| `get__video__note__detail` | Video note detail | `note_id` or `share_text` |
+| `get__mixed__note__detail` | Mixed note detail (auto-detect) | `note_id` or `share_text` |
+| `get__note__comments` | Note comments | `note_id`, `index`, `cursor`, `sort_strategy` |
+| `search__notes` | Search notes | `keyword`*, `page`, `note_type`, `time_filter` |
+| `search__users` | Search users | `keyword`*, `page` |
+| `search__images` | Search images | `keyword`*, `page` |
+| `search__groups` | Search groups | `keyword`*, `page_no` |
+| `search__products` | Search products | `keyword`*, `page` |
+| `get__topic__info` | Topic info | `page_id`* |
+| `get__topic__feed` | Topic feed | `page_id`*, `sort`, `cursor_score` |
+| `get__product__detail` | Product detail | `sku_id`* |
+| `get__product__reviews` | Product reviews | `sku_id`*, `page`, `sort_strategy_type` |
+| `get__product__review__overview` | Product review overview | `sku_id`* |
+| `get__product__recommendations` | Product recommendations | `sku_id`*, `cursor_score` |
+| `get__creator__inspiration__feed` | Creator inspiration feed | `tab`, `cursor` |
+| `get__creator__hot__inspiration__feed` | Creator hot inspiration | `cursor` |
+
+## Error Handling
+
+- **Missing note_id** → Use `search__notes` to find notes, or parse `note_id` from share links
+- **Image vs Video note** → If unsure, use `get__mixed__note__detail` which auto-detects
+- **Pagination: page starts from 0 or 1** → Check endpoint docs: search notes/users/images start from `1`, search groups and product reviews start from `0`
+- **Empty results** → Verify the `user_id`, `note_id`, or `sku_id` is valid

package/skills/xapi/scripts/download_tweet_videos.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  echo "Usage: $0 <tweet-url-or-id> [output-directory]" >&2
+}
+
+die() {
+  echo "Error: $*" >&2
+  exit 1
+}
+
+for required_command in npx jq curl file mktemp; do
+  command -v "$required_command" >/dev/null 2>&1 ||
+    die "required command not found: $required_command"
+done
+
+TWEET_INPUT=${1:-}
+OUTPUT_DIR=${2:-.}
+[ -n "$TWEET_INPUT" ] || {
+  usage
+  exit 2
+}
+[ -d "$OUTPUT_DIR" ] || die "output directory does not exist: $OUTPUT_DIR"
+OUTPUT_DIR=$(cd "$OUTPUT_DIR" && pwd -P)
+
+if [[ "$TWEET_INPUT" =~ ^https://((www|mobile)\.)?(x\.com|twitter\.com)/[^/]+/status/([0-9]+) ]]; then
+  TWEET_ID=${BASH_REMATCH[4]}
+elif [[ "$TWEET_INPUT" =~ ^[0-9]+$ ]]; then
+  TWEET_ID=$TWEET_INPUT
+else
+  die "expected a numeric tweet ID or an x.com/twitter.com status URL"
+fi
+
+SCHEMA=$(npx xapi-to get twitter.tweet_detail --format json)
+printf '%s' "$SCHEMA" | jq -e '
+  .output.properties.data.properties.tweet.properties.media
+  .items.properties.video_url.type == "string"
+' >/dev/null || die "twitter.tweet_detail video_url is not deployed on this xAPI backend"
+
+INPUT=$(jq -nc --arg tweet_id "$TWEET_ID" '{tweet_id:$tweet_id}')
+RESPONSE=$(npx xapi-to call twitter.tweet_detail --input "$INPUT" --format json)
+
+DOWNLOADS=$(printf '%s' "$RESPONSE" | jq -cer '
+  def tweet_tree:
+    .,
+    (
+      (.quoted_tweet?, .retweeted_tweet?)
+      | select(type == "object")
+      | tweet_tree
+    );
+
+  if .success != true then
+    error("xAPI call failed")
+  elif (.data.tweet | type) != "object" then
+    error("tweet detail returned no main tweet")
+  else
+    [
+      .data.tweet
+      | tweet_tree
+      | .media[]?
+      | select(.type == "video" or .type == "animated_gif")
+      | select((.video_url? | type) == "string" and (.video_url | length) > 0)
+      | {url: .video_url}
+    ]
+    | unique_by(.url)
+    | if length == 0 then error("tweet has no downloadable MP4") else . end
+  end
+')
+
+COUNT=$(printf '%s' "$DOWNLOADS" | jq -r 'length')
+URLS=()
+OUTPUTS=()
+TEMP_FILES=()
+
+for ((INDEX = 0; INDEX < COUNT; INDEX++)); do
+  VIDEO_URL=$(printf '%s' "$DOWNLOADS" | jq -r --argjson index "$INDEX" '.[$index].url')
+  [[ "$VIDEO_URL" =~ ^https://video\.twimg\.com/ ]] ||
+    die "refusing unexpected media URL outside https://video.twimg.com/"
+  URLS+=("$VIDEO_URL")
+  if ((COUNT == 1)); then
+    OUTPUT="$OUTPUT_DIR/tweet-$TWEET_ID.mp4"
+  else
+    OUTPUT="$OUTPUT_DIR/tweet-$TWEET_ID-$((INDEX + 1)).mp4"
+  fi
+  [ ! -e "$OUTPUT" ] || die "output already exists: $OUTPUT"
+  OUTPUTS+=("$OUTPUT")
+done
+
+cleanup() {
+  if ((${#TEMP_FILES[@]})); then
+    for temporary_file in "${TEMP_FILES[@]}"; do
+      [ -z "$temporary_file" ] || rm -f -- "$temporary_file"
+    done
+  fi
+}
+trap cleanup EXIT
+
+for ((INDEX = 0; INDEX < COUNT; INDEX++)); do
+  OUTPUT=${OUTPUTS[$INDEX]}
+  TEMP_FILE=$(mktemp "$OUTPUT.part.XXXXXX")
+  TEMP_FILES+=("$TEMP_FILE")
+
+  curl --proto '=https' --proto-redir '=https' \
+    --fail --location --silent --show-error \
+    --output "$TEMP_FILE" "${URLS[$INDEX]}"
+
+  MIME_TYPE=$(file --brief --mime-type "$TEMP_FILE")
+  [ "$MIME_TYPE" = 'video/mp4' ] ||
+    die "downloaded content is not video/mp4 (got $MIME_TYPE)"
+
+  if command -v ffprobe >/dev/null 2>&1; then
+    ffprobe -v error "$TEMP_FILE" >/dev/null ||
+      die "ffprobe rejected the downloaded MP4"
+  fi
+done
+
+# Publish files only after every download has passed validation.
+for ((INDEX = 0; INDEX < COUNT; INDEX++)); do
+  mv -- "${TEMP_FILES[$INDEX]}" "${OUTPUTS[$INDEX]}"
+  TEMP_FILES[$INDEX]=''
+  echo "Downloaded: ${OUTPUTS[$INDEX]}"
+done
+
+trap - EXIT