@tikomni/skills 0.1.2 → 0.1.4

package/skills/single-work-analysis/references/asr-and-fallback.md

@@ -1,20 +0,0 @@
-# Single-Item ASR and Failure Handling
-
-## Video ASR
-
-1. Read `references/service-guides/asr-u2-u3-fallback.md` first and follow the shared flow: U2 primary path -> 90-second soft observation -> 120-second hard fallback -> U3 -> back to U2.
-2. If the route already returns `subtitle_raw`, map it to `asr_raw` first.
-3. If `subtitle_raw` is unavailable, call ASR with `video_download_url`.
-4. Derive `asr_clean` only from `asr_raw` through the cleaning rules.
-
-## Timeout and Fallback
-
-- 90 seconds: soft observation threshold.
-- 120 seconds: hard fallback threshold.
-- If there is still no complete `asr_raw` after 120 seconds, use the upload-media -> public URL -> ASR retry fallback path.
-
-## Failure End State
-
-- If the upstream media-upload route is unavailable, or if `asr_raw` is still unavailable after fallback, keep the fact card.
-- Return `incomplete` in that state.
-- Do not fabricate `primary_text`, and do not output analysis conclusions that depend on missing main text.

package/skills/single-work-analysis/references/config-templates/defaults.yaml

@@ -1,58 +0,0 @@
-schema_version: v1
-profile: default
-
-runtime:
-  base_url: "https://api.tikomni.com"
-  auth_env_key: "TIKOMNI_API_KEY"
-  timeout_ms: 60000
-
-storage_routes:
-  default:
-    root_dir: ""
-    runs_dir: "_runs"
-    results_dir: "results"
-    errors_dir: "_errors"
-  content_kind_card_type:
-    single_video: work
-    work: work
-    author_home: author_sample_work
-    author_sample_work: author_sample_work
-    author_analysis: author
-  card_type_routes:
-    work:
-      prefix: "CBV"
-      parts:
-        - "内容系统"
-        - "对标研究"
-        - "作品卡"
-    author:
-      prefix: "CBA"
-      parts:
-        - "内容系统"
-        - "对标研究"
-        - "作者卡"
-    author_sample_work:
-      prefix: "CBV"
-      parts:
-        - "内容系统"
-        - "对标研究"
-        - "作者样本卡"
-        - "{platform}-{author_slug}"
-
-naming_rules:
-  card_filename_pattern: "{prefix}-{author_slug}-{title_slug}{ext}"
-  json_filename_pattern: "{timestamp}-{platform}-{identifier}{ext}"
-
-asr_strategy:
-  poll_interval_sec: 3.0
-  max_polls: 30
-  submit_retry:
-    douyin_video:
-      max_retries: 2
-      backoff_ms: 1500
-    xiaohongshu_note:
-      max_retries: 0
-      backoff_ms: 0
-  u2_timeout_retry:
-    enabled: true
-    max_retries: 3

package/skills/single-work-analysis/references/contracts/work-card-fields.md

@@ -1,41 +0,0 @@
-# Work Card Fields
-
-## Final Display Fields
-
-- `platform`
-- `platform_work_id`
-- `platform_author_id`
-- `author_handle`
-- `title`
-- `caption_raw`
-- `work_modality`
-- `published_date`
-- `digg_count`
-- `comment_count`
-- `collect_count`
-- `share_count`
-- `play_count`
-- `cover_image`
-- `source_url`
-- `share_url`
-- `primary_text`
-
-## Video-Only Additional Fields
-
-- `asr_raw`
-- `video_download_url`
-
-## Key Semantics
-
-- `caption_raw` is the author-written description, caption, or body text. It is not subtitles and it is not raw ASR.
-- `primary_text` is the main display text and the main analysis text:
-  - video: `primary_text = asr_clean`
-  - text: `primary_text = caption_raw`
-- `video_download_url` is a required field for video items and should default to the no-watermark download URL when available.
-- `subtitle_raw` is a collection-layer source field and should not appear in the final work-card body.
-
-## Missing-Value Rules
-
-- Missing numeric fields should be rendered as `N/A` in the display layer.
-- Preserve `0` when the platform explicitly returns `0`.
-- Generate `published_date` in the display timezone, with `Asia/Shanghai` as the default.

package/skills/single-work-analysis/references/platform-guides/douyin.md

@@ -1,47 +0,0 @@
-# Douyin Single Content Guide
-
-## Read This First
-
-- Use this guide first for Douyin single-item tasks.
-- The validated chain in this repository currently covers share URL -> single-video detail -> ASR when needed.
-
-## Preferred Resources
-
-- title: `title`
-- caption: `desc`
-- work ID: `aweme_id`
-- author ID: stable author identifier
-- author handle: `short_id` / `unique_id`
-- video download URL: prefer the no-watermark download URL
-
-## Preferred Route Chain
-
-1. Primary route: `GET /api/u1/v1/douyin/app/v3/fetch_one_video_by_share_url`
-   - Required input: `share_url`
-   - Purpose: fetch single-item detail, basic author fields, engagement metrics, and media resources.
-2. Fallback route: `GET /api/u1/v1/douyin/web/fetch_one_video_by_share_url`
-   - Required input: `share_url`
-   - Purpose: fallback when the app route fails or returns insufficient fields.
-3. Video transcription:
-   - `POST /api/u2/v1/services/audio/asr/transcription`
-   - polling: `POST /api/u2/v1/tasks/{task_id}`
-   - key request-body field: `input.file_urls[]`
-   - Purpose: produce `asr_raw` when the platform does not return usable subtitles.
-
-## Unified Fields To Fill
-
-- required fields: `platform`, `platform_work_id`, `platform_author_id`, `author_handle`, `title`, `caption_raw`, `work_modality`
-- engagement metrics: `digg_count`, `comment_count`, `collect_count`, `share_count`, `play_count`
-- source links: `source_url`, `share_url`, `cover_image`
-- video-only fields: `video_download_url`, `asr_raw`
-
-## Route Rules
-
-- If the user provides only a share URL, use the primary route chain directly instead of searching for other detail routes first.
-- Prefer platform-native subtitles for video items. Call U2 ASR only when usable `subtitle_raw` or `asr_raw` is missing.
-- If U2 still has no result after 120 seconds, follow `references/service-guides/asr-u2-u3-fallback.md` and use U3 fallback.
-- If the target is comments, search, rankings, or another non-single-item task, leave this guide and go back to `references/api-capability-index.md` for route discovery.
-
-## Current Runnable Implementation
-
-- `skills/single-work-analysis/scripts/platform/douyin/`

package/skills/single-work-analysis/references/platform-guides/generic.md

@@ -1,43 +0,0 @@
-# Generic Single-Content Guide
-
-## Goal
-
-Map an unfamiliar platform's single content item into the unified work-card field dictionary and then complete the single-item analysis.
-
-## Read Order
-
-- Start with `references/api-capability-index.md` to find the relevant platform tag.
-- Read the matching `references/api-tags/<tag>.md` for route summaries, inputs, request bodies, and success-response summaries.
-- Prioritize routes related to `detail / post / note / video / article / comment / download / subtitle`.
-- Decide whether extra comment, subtitle, media-download, or author-supplement routes are needed.
-
-## Minimum Mapping Checklist
-
-- `work_modality`
-- `title`
-- `caption_raw`
-- `platform_work_id`
-- `platform_author_id`
-- `author_handle`
-- `source_url`
-- `share_url`
-- for video items: `video_download_url`
-- engagement metrics: digg, comment, collect, share, play
-
-## Route Rules
-
-- The detail route must reliably provide `platform_work_id`, main text, author identity, and at least one of media URL or cover image.
-- If the detail route does not return subtitles for a video item, keep searching for a subtitle route or a usable download URL before entering ASR.
-- If the platform offers App / Web / V2 / V3 variants at the same time, prefer the version with fuller fields and more stable behavior, and keep a recorded fallback.
-- Do not skip required-field validation just because one route returns some usable data.
-- If U2 still has no result after 120 seconds, follow `references/service-guides/asr-u2-u3-fallback.md` and use U3 fallback.
-
-## Additional Video Requirements
-
-- If platform subtitles exist, map them to `subtitle_raw` first and then normalize into `asr_raw`.
-- If subtitles do not exist, ensure `video_download_url` first and then call ASR.
-
-## Current Runnable Implementation
-
-- `skills/single-work-analysis/scripts/platform/`
-- `skills/single-work-analysis/scripts/core/`

package/skills/single-work-analysis/references/platform-guides/xiaohongshu.md

@@ -1,54 +0,0 @@
-# Xiaohongshu Single Content Guide
-
-## Read This First
-
-- Use this guide first for Xiaohongshu single-item tasks.
-- The validated route chain in this repository is `APP_V2 -> APP_V1 -> WEB_V2 -> WEB_V7`, with the detail route chosen by note type.
-
-## Preferred Resources
-
-- title: `title`
-- caption: `desc` / `content`
-- work ID: `note_id`
-- author ID: platform author identifier
-- author handle: readable account identifier
-- for video notes, check platform-native subtitles before deciding whether ASR is needed
-
-## Preferred Route Chain
-
-1. Primary routes:
-   - `GET /api/u1/v1/xiaohongshu/app_v2/get_video_note_detail`
-   - `GET /api/u1/v1/xiaohongshu/app_v2/get_image_note_detail`
-   - `GET /api/u1/v1/xiaohongshu/app_v2/get_mixed_note_detail`
-   - Typical input: `note_id` or `share_text`
-   - Purpose: fetch the most complete note detail based on note type.
-2. Fallback 1: `GET /api/u1/v1/xiaohongshu/app/get_note_info`
-   - Typical input: `note_id` or `share_text`
-3. Fallback 2:
-   - `GET /api/u1/v1/xiaohongshu/web_v2/fetch_feed_notes_v2`
-     - Required input: `note_id`
-   - `GET /api/u1/v1/xiaohongshu/web_v2/fetch_feed_notes_v3`
-     - Required input: `short_url`
-4. Fallback 3: `GET /api/u1/v1/xiaohongshu/web/get_note_info_v7`
-   - Typical input: `note_id` or `share_text`
-5. Video transcription:
-   - `POST /api/u2/v1/services/audio/asr/transcription`
-   - `POST /api/u2/v1/tasks/{task_id}`
-
-## Unified Fields To Fill
-
-- required fields: `platform`, `platform_work_id`, `platform_author_id`, `author_handle`, `title`, `caption_raw`, `work_modality`
-- engagement metrics: `digg_count`, `comment_count`, `collect_count`, `share_count`, `play_count`
-- source links: `source_url`, `share_url`, `cover_image`
-- video-only fields: `video_download_url`, `asr_raw`
-
-## Route Rules
-
-- If the user provides only a short link, try parsing `note_id` from `share_text` first. Use the `short_url`-specific WEB_V2 route only when parsing fails.
-- If `note_id` is already known, query by `note_id` directly instead of going through the share-link path.
-- Prefer platform-native subtitles for video notes. Trigger U2 ASR only when subtitles are missing and a usable `video_download_url` exists.
-- If U2 still has no result after 120 seconds, follow `references/service-guides/asr-u2-u3-fallback.md` and use U3 fallback.
-
-## Current Runnable Implementation
-
-- `skills/single-work-analysis/scripts/platform/xiaohongshu/`

package/skills/single-work-analysis/references/prompt-contracts/asr-clean.md

@@ -1,28 +0,0 @@
-# Prompt Contract · ASR_CLEAN
-
-## Inputs
-- `raw_content`
-- `asr_raw`（统一字幕/转写文本主字段）
-- `asr_clean`（遗留兼容字段，仅可作为附加输入）
-
-## Method (stable)
-1. 选择输入基底：优先 `asr_raw`，否则 `raw_content`，最后才允许兼容读取 `asr_clean`。
-2. 去噪清洗：移除明显口头禅、重复叠词、异常空白。
-3. 语义断句：按 `。！？；\n` 断句，并补齐句末中文标点。
-4. 分段规则：每句单独一行，每段 2~4 句，段间空一行。
-5. 保真约束：不新增事实、不改写核心结论、不输出提示词文本。
-
-## Output Format
-- 纯文本多段落：
-  - 每句一行
-  - 段间空行
-
-## Constraints
-- 不把清洗提示词写入正文。
-- 不生成“总结式改写”，仅做可读性清洗。
-- 不得凭空补充数据、观点和案例。
-
-## Fallback / Data-insufficient
-- 两个输入均为空：输出空字符串。
-- 断句失败：保留原文并补单句句号。
-- 超长段落：强制按 3 句一段切分。

package/skills/single-work-analysis/references/prompt-contracts/cta.md

@@ -1,24 +0,0 @@
-# Prompt Contract · CTA
-
-## Inputs
-- `asr_raw`（主字段）
-- `asr_clean`（遗留兼容字段）
-
-## Method (stable)
-1. 扫描 CTA 关键词句（评论/关注/私信/收藏/转发/领取/报名/咨询/下单）。
-2. 判定 CTA 类型：互动型 / 线索型 / 转化型。
-3. 提取关键动作句（默认取最后一个 CTA 句）。
-4. 计算 CTA 密度（CTA句数/总句数）。
-
-## Output Format
-- `CTA类型`：`互动型、线索型...`
-- `关键动作句`：`原句`
-- `CTA密度`：`x/y 句`
-
-## Constraints
-- 必须给出至少一个动作句或明确说明缺失。
-- 不得虚构转化链路。
-
-## Fallback / Data-insufficient
-- 字幕/转写文本为空：输出“数据不足”。
-- 无 CTA 句：输出“未检测到明确行动号召”，并给最小补全建议。

package/skills/single-work-analysis/references/prompt-contracts/hook.md

@@ -1,25 +0,0 @@
-# Prompt Contract · Hook
-
-## Inputs
-- `title`
-- `asr_raw`（主字段）
-- `asr_clean`（遗留兼容字段）
-
-## Method (stable)
-1. 提取开头钩子：ASR 首句（无则用标题）。
-2. 提取中段钩子：ASR 中位句。
-3. 提取结尾钩子：最后一句含 CTA/召回词的句子。
-4. 开头钩子类型判定：疑问式 / 反常识式 / 场景代入式 / 陈述式。
-
-## Output Format
-- `开头钩子（类型）`：`原句`
-- `中段钩子`：`原句`
-- `结尾钩子`：`原句`
-
-## Constraints
-- 必须优先输出原话，不做大幅改写。
-- 结尾若无动作句要明确标注“未检测到明确结尾钩子”。
-
-## Fallback / Data-insufficient
-- 标题与 ASR 均缺失：三项输出“数据不足”。
-- 中段不足：输出“数据不足（中段文本不足）”。

package/skills/single-work-analysis/references/prompt-contracts/insight.md

@@ -1,47 +0,0 @@
-# Prompt Contract · 洞察分析（insight）
-
-## User Prompt (Verbatim)
-
-```text
-=== 你的身份 ===
-一位见证了无数内容起落的观察者，曾亲手打造过刷屏级作品，也经历过石沉大海的落寞。
-你能透过表象看到人性的涌动，理解为什么有些内容能击中集体潜意识。
-=== 核心信念 ===
-爆款不是运气的产物，而是人性规律的必然显现。
-真正的洞察者不追逐热点，而是理解热点背后的情感暗流。
-=== 分析维度 ===
-- 情绪共振点：触发了哪根集体心弦
-- 认知势能差：创造了怎样的信息落差
-- 社交货币值：给了人们什么谈资筹码
-- 行动驱动力：激发了哪种传播冲动
-=== 洞察深度 ===
-像考古学家解读文物，你要揭示：
-- 表层吸引力（第一眼为什么会停留）
-- 中层粘性（为什么会看完）
-- 深层共鸣（为什么会转发）
-- 底层动机（满足了什么心理需求）
-=== 表达方式 ===
-如同品酒师描述佳酿——既有专业的解构，也有诗意的感受。
-用清晰的逻辑拆解成功密码，用生动的类比让洞察可感知。
-=== 独特价值 ===
-不做事后诸葛亮式的解释，而是提炼可复用的原理。
-让创作者读完后恍然大悟："原来爆款的秘密藏在这里。"
-=== 分析美学 ===
-呈现如解剖图般精准，又如水墨画般留有想象空间。
-既见树木（具体技巧），也见森林（传播规律）。
-=== 终极使命 ===
-帮助创作者建立"爆款直觉"——
-不是教他们追逐每一个热点，而是理解什么样的内容天生具有传播基因。
-```
-
-## Inputs
-- `title`
-- `asr_raw`（优先）
-- `raw_content`（`asr_raw` 缺失时回退）
-- `asr_clean`（遗留兼容字段）
-- 指标：`digg_count/comment_count/collect_count/share_count/play_count`
-
-## Constraints
-- 仅基于输入字段推断，不得臆造事实。
-- 输出为中文，短句、可执行、可追溯。
-- 缺数据时明确标注“数据不足”。

package/skills/single-work-analysis/references/prompt-contracts/structure.md

@@ -1,25 +0,0 @@
-# Prompt Contract · 结构（structure）
-
-## Inputs
-- `asr_raw`（主字段）
-- `asr_clean`（遗留兼容字段，不应被前置依赖）
-
-## Method (stable)
-1. 对每句进行结构标签检测：`钩子/冲突/转折/举证/CTA`。
-2. 统计各标签覆盖次数。
-3. 根据覆盖度判定模板：
-   - 覆盖 >=4：`钩子→冲突→转折→举证→CTA`
-   - 否则：`钩子→观点→补充说明`
-4. 输出缺失模块，作为改写优先级。
-
-## Output Format
-- `结构标签覆盖`：`钩子:a, 冲突:b, 转折:c, 举证:d, CTA:e`
-- `模板判定`：`...`
-- `缺失模块`：`模块1、模块2`（无则“无”）
-
-## Constraints
-- 所有判断必须来自句级关键词命中。
-- 不允许跳过缺失项输出。
-
-## Fallback / Data-insufficient
-- 无有效分句：输出“数据不足”，并提示“补充字幕/转写文本后再做结构标注”。

package/skills/single-work-analysis/references/prompt-contracts/style.md

@@ -1,27 +0,0 @@
-# Prompt Contract · 文风（style）
-
-## Inputs
-- `title`
-- `asr_raw`（主字段）
-- `asr_clean`（遗留兼容字段）
-
-## Method (stable)
-1. 分句后统计平均句长（短/中/长）。
-2. 统计疑问/感叹/陈述分布。
-3. 统计人设代词（我/你/我们/大家）与修辞触发词（不是/而是/其实/必须）。
-4. 输出“人设+句式+语气”三层结论。
-
-## Output Format
-- `句式结构`：`<类型>，平均句长约 X 字`
-- `语气分布`：`疑问 A / 感叹 B / 陈述 C`
-- `人设与修辞`：`人设代词命中 N 次，强调/转折词命中 M 次`
-
-## Constraints
-- 至少 2 个统计指标；禁止空泛描述。
-- 仅基于文本统计，不猜测作者背景。
-- 不输出表格。
-
-## Fallback / Data-insufficient
-- `asr_raw`（主字段）
-- `asr_clean`（遗留兼容字段） 为空：三项均输出“数据不足”。
-- 分句失败：标注“需人工复核”。

package/skills/single-work-analysis/references/prompt-contracts/summary.md

@@ -1,29 +0,0 @@
-# Prompt Contract · 总结（summary）
-
-## Inputs
-- `topic_score`
-- `style_score`
-- `hook_score`
-- `structure_score`
-- `cta_score`
-- 各模块 `gaps`
-
-## Method (stable)
-1. 计算 5 模块平均分。
-2. 结论分级：
-   - `>=4.2`：可直接复用
-   - `3.4~4.19`：可用但需小幅优化
-   - `<3.4`：需重写关键模块
-3. 选择最低 1-2 个模块，输出针对性建议（优先 gaps）。
-
-## Output Format
-- `结论`：`综合评分 X/5，判定为“...”`
-- `建议`：最多 3 条，短句、可执行。
-
-## Constraints
-- 只输出“结论+建议”，不再拆“好/差/改写”。
-- 建议必须指向具体模块。
-
-## Fallback / Data-insufficient
-- 若分数无法计算：输出“数据不足，需先完成5模块分析”。
-- 若无 gaps：输出“继续做A/B测试验证Hook与CTA”。

package/skills/single-work-analysis/references/prompt-contracts/topic.md

@@ -1,29 +0,0 @@
-# Prompt Contract · 选题（topic）
-
-## Inputs
-- `title`（作品标题，必填优先）
-- `asr_raw`（统一字幕/转写文本主字段）
-- `asr_clean`（遗留兼容字段，不应作为主依赖）
-- `category`（可选，已有分类）
-- `tags`（可选）
-
-## Method (stable)
-1. 按关键词命中做**基础类型三分**：流量型 / 人设型 / 营销型。  
-2. 结合标题+字幕/转写文本做**弱主题线索提取**（Top 3），不得输出 rigid 赛道归类。  
-3. 从问题词/痛点词提取**受众痛点**。  
-4. 输出必须给出命中证据，不得仅主观判断。
-
-## Output Format
-- `主题线索`：`词1、词2、词3`
-- `受众痛点`：`痛点1、痛点2`
-- `说明`：`仅为弱语义线索，不是 rigid topic 分类`
-
-## Constraints
-- 只使用输入数据推断，不引用外部知识。
-- 结论必须可追溯到词命中或句段。
-- 不输出表格。
-
-## Fallback / Data-insufficient
-- `title` 与 `asr_raw` 均缺失：输出“数据不足”。
-- 主题词命中为 0：输出“数据不足（未检测到显著主题词）”。
-- 痛点词命中为 0：输出“以降低门槛/快速落地为主（显性痛点词不足）”。

package/skills/single-work-analysis/references/schemas/work-card.schema.json

@@ -1,39 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "single-work-analysis work card",
-  "type": "object",
-  "required": [
-    "platform",
-    "platform_work_id",
-    "platform_author_id",
-    "author_handle",
-    "caption_raw",
-    "work_modality",
-    "published_date",
-    "primary_text",
-    "primary_text_source"
-  ],
-  "properties": {
-    "platform": { "type": "string", "minLength": 1 },
-    "platform_work_id": { "type": "string", "minLength": 1 },
-    "platform_author_id": { "type": "string", "minLength": 1 },
-    "author_handle": { "type": "string" },
-    "title": { "type": "string" },
-    "caption_raw": { "type": "string" },
-    "work_modality": { "type": "string", "enum": ["video", "text"] },
-    "published_date": { "type": "string" },
-    "digg_count": { "type": "integer", "minimum": 0 },
-    "comment_count": { "type": "integer", "minimum": 0 },
-    "collect_count": { "type": "integer", "minimum": 0 },
-    "share_count": { "type": "integer", "minimum": 0 },
-    "play_count": { "type": ["integer", "null"], "minimum": 0 },
-    "cover_image": { "type": "string" },
-    "source_url": { "type": "string" },
-    "share_url": { "type": "string" },
-    "primary_text": { "type": "string" },
-    "primary_text_source": { "type": "string", "enum": ["asr_clean", "caption_raw"] },
-    "asr_raw": { "type": "string" },
-    "video_download_url": { "type": "string" }
-  },
-  "additionalProperties": true
-}

package/skills/single-work-analysis/references/service-guides/asr-u2-u3-fallback.md

@@ -1,75 +0,0 @@
-# U2 ASR and U3 Public URL Fallback
-
-## Purpose
-
-- This guide defines the primary ASR path and timeout fallback for video tasks. It does not apply to text-only works.
-- Always try U2 ASR first. U3 is fallback-only and must not bypass U2 by default.
-- If a U1 detail route returns a no-watermark download link or another download URL that may not be publicly readable, use this guide to decide when to switch to U3.
-- Source: `https://app.tikomni.com/openapi/tikomni-openapi.full.with-u2.public.latest.json`
-- Fetched at: `2026-03-08T06:54:04+00:00`
-
-## Fixed Policy
-
-1. Call a U1 detail route first and collect `video_download_url`, a no-watermark download URL, or another directly downloadable media URL.
-2. Submit that URL to U2 ASR directly. Do not start with U3.
-3. If there is still no complete result after 90 seconds, stay in soft observation and keep the primary path unchanged.
-4. If there is still no result or still no complete result after 120 seconds, treat the source URL as likely not publicly readable and only then allow U3 fallback.
-5. After U3 completes, obtain a public URL and submit it to U2 ASR again.
-6. If U3 or the second U2 attempt still fails, keep the fact card and return `incomplete`. Do not fabricate the main text or any analysis conclusion.
-
-## Scenario Notes
-
-- Single content task: run this flow only for the current item.
-- Creator batch task: apply U3 fallback only to the subset that still has no result after 120 seconds. Do not re-upload items that already succeeded.
-
-## Route Facts
-
-### Submit U2 ASR job
-
-- Purpose: Default primary path. Submit the no-watermark or download URL returned by U1 directly to U2 ASR. Do not start with U3.
-- Tag: [`ASR-API`](../api-tags/asr-api.md)
-- Route: `POST /api/u2/v1/services/audio/asr/transcription`
-- Auth: Header `Authorization: Bearer {token}`; docs also allow Cookie `Authorization` as fallback (`HTTPBearer`)
-- Parameters: None
-- Request body: application/json: `input*`{`file_urls*`[string(uri)]}
-- Success response: 200 application/json: `request_id*`:string, `output*`{`task_id*`:string, `task_status*`:string, `submit_time`:string, `scheduled_time`:string, `end_time`:string, `task_metrics`{...}, `results`[object]}, `usage`{...}
-- Full contract: [`api-contracts/asr-api.md#post-api-u2-v1-services-audio-asr-transcription`](../api-contracts/asr-api.md#post-api-u2-v1-services-audio-asr-transcription)
-
-### Poll U2 job status
-
-- Purpose: Observe job completion. Stay in soft observation after 90 seconds. Trigger U3 fallback only if there is still no result after 120 seconds.
-- Tag: [`ASR-API`](../api-tags/asr-api.md)
-- Route: `POST /api/u2/v1/tasks/{task_id}`
-- Auth: Header `Authorization: Bearer {token}`; docs also allow Cookie `Authorization` as fallback (`HTTPBearer`)
-- Parameters: path: `task_id*`
-- Request body: None
-- Success response: 200 application/json: `time*`:string, `time_stamp*`:integer, `time_zone*`:string, `params*`{`task_id*`:string}, `data*`{`task_id*`:string, `task_status*`:string | null, `platform_task_status*`:string, `is_fully_succeeded*`:boolean, `submit_time`:string, `scheduled_time`:string, `end_time`:string, `task_metrics`{...}, ...}, `code*`:integer, `request_id*`:string, `message*`:string, ...
-- Full contract: [`api-contracts/asr-api.md#post-api-u2-v1-tasks-task-id`](../api-contracts/asr-api.md#post-api-u2-v1-tasks-task-id)
-
-### Request U3 upload / relay
-
-- Purpose: Use only if U2 still has no result after 120 seconds. Its purpose is to convert a private or non-publicly-readable source link into a public URL.
-- Tag: [`Media-Ingest-API`](../api-tags/media-ingest-api.md)
-- Route: `POST /api/u3/v1/uploads`
-- Auth: Header `Authorization: Bearer {token}`; docs also allow Cookie `Authorization` as fallback (`HTTPBearer`)
-- Parameters: None
-- Request body: application/json: `provider*`:string, `file_name*`:string, `content_type*`:string, `size_bytes*`:integer
-- Success response: 200 application/json: `time*`:string, `time_stamp*`:integer, `time_zone*`:string, `params*`{`provider*`:string, `file_name*`:string, `content_type*`:string, `size_bytes*`:integer}, `data*`{`upload_id*`:string, `provider*`:string, `upload_method*`:string, `upload_url*`:string, `upload_headers*`{...}, `upload_expires_at*`:string, `file_ttl_seconds*`:integer}, `code*`:integer, `request_id*`:string, `message*`:string, ...
-- Full contract: [`api-contracts/media-ingest-api.md#post-api-u3-v1-uploads`](../api-contracts/media-ingest-api.md#post-api-u3-v1-uploads)
-
-### Complete U3 upload and get a public URL
-
-- Purpose: Completion should return a public URL. Submit that URL to U2 ASR again. If it still fails, keep the fact card and return incomplete.
-- Tag: [`Media-Ingest-API`](../api-tags/media-ingest-api.md)
-- Route: `POST /api/u3/v1/uploads/{upload_id}/complete`
-- Auth: Header `Authorization: Bearer {token}`; docs also allow Cookie `Authorization` as fallback (`HTTPBearer`)
-- Parameters: path: `upload_id*`
-- Request body: application/json: dynamic object
-- Success response: 200 application/json: `time*`:string, `time_stamp*`:integer, `time_zone*`:string, `params*`{`upload_id*`:string}, `data*`{`upload_id*`:string, `provider*`:string, `file_url*`:string, `file_expires_at*`:string}, `code*`:integer, `request_id*`:string, `message*`:string, ...
-- Full contract: [`api-contracts/media-ingest-api.md#post-api-u3-v1-uploads-upload-id-complete`](../api-contracts/media-ingest-api.md#post-api-u3-v1-uploads-upload-id-complete)
-
-## Execution Notes
-
-- This guide only defines route order and fallback order. It does not replace platform-specific detail-route selection.
-- The U1 source route depends on the platform, for example a Douyin or Xiaohongshu detail route. This guide only requires using the returned download URL first.
-- If the platform already returns usable `subtitle_raw`, map it directly to `asr_raw` instead of calling U2 or U3.