### Initialize TaskInput Examples

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/models.md

Examples showing how to instantiate TaskInput for URL-based tasks and local video files.

```python
from video_sum_core.models.tasks import TaskInput, InputType

# URL 输入
task_input = TaskInput(
    input_type=InputType.URL,
    source="https://www.bilibili.com/video/BV1234567890",
    title="视频标题",
    platform_hint="bilibili",
    options=TaskOptions(language="zh", summary_mode="llm")
)

# 本地视频文件
local_task = TaskInput(
    input_type=InputType.VIDEO_FILE,
    source="/path/to/video.mp4",
    title="本地视频",
    options=TaskOptions(language="zh")
)
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/lycohana/bilisum/blob/master/README.md

Install Python and Node.js dependencies required for the project.

```powershell
uv sync --python 3.12 --all-packages
npm install --prefix .\apps\desktop
```

--------------------------------

### Initialize Environment Configuration

Source: https://github.com/lycohana/bilisum/blob/master/README.md

Create the .env file from the provided example template.

```powershell
Copy-Item .env.example .env
```

--------------------------------

### Start Development Environment

Source: https://github.com/lycohana/bilisum/blob/master/README.md

Launch the Vite renderer, Electron shell, and Python backend simultaneously.

```powershell
npm run dev
```

--------------------------------

### Execute preflight Check

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/pipeline.md

Example usage of the preflight method with error handling.

```python
from video_sum_core.pipeline.base import PipelineContext
from video_sum_core.errors import LLMConfigurationError

runner = PipelineRunner()

try:
    runner.preflight(context)
    print("预检查通过")
except LLMConfigurationError as e:
    print(f"LLM 配置不完整: {e}")
    # 用户需要补充 LLM 设置
except Exception as e:
    print(f"预检查失败: {e}")
```

--------------------------------

### Start Backend Service

Source: https://github.com/lycohana/bilisum/blob/master/README.md

Launch the FastAPI backend service using the uv package manager.

```powershell
uv run --package video-sum-service python -m video_sum_service
```

--------------------------------

### Execute Pipeline run

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/pipeline.md

Example usage of the run method with an event logger.

```python
from video_sum_core.pipeline.base import PipelineRunner, PipelineContext

def log_event(event):
    """实时日志回调。"""
    print(f"{event.stage:15} {event.progress:3}% {event.message}")

runner = PipelineRunner()  # 实际应为 RealPipelineRunner
context = PipelineContext(task_id="123", task_input=...)

try:
    events, result = runner.run(context, on_event=log_event)
    
    # 保存结果
    print(f"摘要: {result.overview}")
    print(f"关键点: {result.key_points}")
    print(f"Token 消耗: {result.llm_total_tokens}")
    
except Exception as e:
    print(f"处理失败: {e}")
```

--------------------------------

### GET /api/v1/tasks

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/endpoints.md

Lists all existing tasks.

```APIDOC
## GET /api/v1/tasks

### Description
Retrieves a list of all tasks associated with the authenticated user.

### Method
GET

### Endpoint
/api/v1/tasks

### Response
#### Success Response (200)
- **tasks** (array) - List of task objects containing task_id, status, title, and timestamps
```

--------------------------------

### Usage examples for Pegasus analysis

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/twelvelabs.md

Demonstrates how to perform video analysis using URL sources, local files, and custom configuration parameters.

```python
from video_sum_core.twelvelabs import (
    analyze_video_with_pegasus,
    video_context_from_url,
    video_context_from_file
)

# 方案 1: 从 URL 分析
try:
    summary = analyze_video_with_pegasus(
        api_key="tlk-your-api-key",
        video={"type": "url", "url": "https://cdn.example.com/demo.mp4"},
        prompt="请总结这支教程视频中的关键步骤",
        model_name="pegasus1.5",
        timeout_seconds=300
    )
    print("Pegasus 摘要:", summary)
except Exception as e:
    print(f"Pegasus 分析失败: {e}")

# 方案 2: 从本地文件分析（<30MB）
video_context = video_context_from_file("/path/to/local/video.mp4")
if video_context:
    summary = analyze_video_with_pegasus(
        api_key="tlk-your-api-key",
        video=video_context,
        prompt="提取视频中出现的代码片段和技术细节"
    )
else:
    print("视频文件过大，跳过 Pegasus 分析")

# 方案 3: 自定义参数
summary = analyze_video_with_pegasus(
    api_key="tlk-your-api-key",
    video={"type": "url", "url": "https://example.com/video.mp4"},
    prompt="提取所有数据和数字",
    model_name="pegasus1.2",
    max_tokens=1024,
    temperature=0.1,
    timeout_seconds=600
)
```

--------------------------------

### Handle TranscriptionConfigurationError

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/errors.md

Example of catching configuration errors during audio transcription.

```python
from video_sum_core.errors import TranscriptionConfigurationError

try:
    transcript = transcribe_audio(audio_path)
except TranscriptionConfigurationError as e:
    print(f"转写服务未配置: {e}")
    # 提示用户选择和配置转写提供商
```

--------------------------------

### Implement and Use PipelineEventReporter

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/pipeline.md

Example of defining a custom event handler and passing it to the runner.

```python
from video_sum_core.pipeline.base import PipelineEvent, PipelineEventReporter

def my_event_handler(event: PipelineEvent) -> None:
    """自定义事件处理逻辑。"""
    print(f"[{event.stage}] {event.message} ({event.progress}%)")
    if event.payload.get("error"):
        print(f"  错误: {event.payload['error']}")

# 在管道调用中使用
runner.run(context, on_event=my_event_handler)
```

--------------------------------

### GET /api/v1/system/info

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/endpoints.md

Retrieves general system information including application version, platform, and hardware capabilities.

```APIDOC
## GET /api/v1/system/info

### Description
Retrieves general system information including application version, platform, and hardware capabilities.

### Method
GET

### Endpoint
/api/v1/system/info

### Response
#### Success Response (200)
- **app_name** (string) - Application name
- **app_version** (string) - Application version
- **python_version** (string) - Python runtime version
- **platform** (string) - Operating system platform
- **data_dir** (string) - Path to data directory
- **cuda_available** (boolean) - Whether CUDA is available

#### Response Example
{
  "app_name": "BiliSum",
  "app_version": "0.5.0",
  "python_version": "3.12.0",
  "platform": "linux",
  "data_dir": "/home/user/.cache/bilisum",
  "cuda_available": true
}
```

--------------------------------

### Handle PegasusConfigurationError

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/errors.md

Example of catching configuration errors when API keys or video context fields are missing.

```python
from video_sum_core.errors import PegasusConfigurationError
from video_sum_core.twelvelabs import analyze_video_with_pegasus

try:
    summary = analyze_video_with_pegasus(
        api_key="",  # 缺失将触发异常
        video={"type": "url"}  # 缺少 url 字段
    )
except PegasusConfigurationError as e:
    logger.warning(f"Pegasus 配置不完整，跳过: {e}")
    # 继续使用其他摘要方式
```

--------------------------------

### Pipeline Event Sequence Example

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/pipeline.md

A list of PipelineEvent objects representing a typical execution flow.

```python
# 输出示例
[PipelineEvent(stage="accepted", progress=0, message="Pipeline started"),
 PipelineEvent(stage="download", progress=10, message="正在下载视频..."),
 PipelineEvent(stage="transcode", progress=20, message="正在转码..."),
 PipelineEvent(stage="transcribe", progress=30, message="正在转写...", payload={"progress": "0/600s"}),
 PipelineEvent(stage="transcribe", progress=50, message="正在转写...", payload={"progress": "300/600s"}),
 PipelineEvent(stage="transcribe", progress=70, message="正在转写...", payload={"progress": "600/600s"}),
 PipelineEvent(stage="summarize", progress=75, message="正在生成摘要..."),
 PipelineEvent(stage="mindmap", progress=90, message="正在生成思维导图..."),
 PipelineEvent(stage="completed", progress=100, message="处理完成")]
```

--------------------------------

### Use openai_chat_completions_url function

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/infra-llm.md

Examples of generating OpenAI chat completion URLs with various base URL formats.

```python
from video_sum_infra.llm import openai_chat_completions_url

openai_chat_completions_url("https://api.openai.com/v1")
# 返回: "https://api.openai.com/v1/chat/completions"

openai_chat_completions_url("https://api.openai.com/v1/")
# 返回: "https://api.openai.com/v1/chat/completions"

openai_chat_completions_url("https://coding.dashscope.aliyuncs.com/v1")
# 返回: "https://coding.dashscope.aliyuncs.com/v1/chat/completions"
```

--------------------------------

### GET /api/v1/videos

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/endpoints.md

Retrieves the list of videos and folders available in the library.

```APIDOC
## GET /api/v1/videos

### Description
Retrieves a list of videos and folders from the library.

### Method
GET

### Endpoint
/api/v1/videos

### Response
#### Success Response (200)
- **videos** (array) - List of video objects
- **folders** (array) - List of folder objects

#### Response Example
{
  "videos": [
    {
      "video_id": "video_123",
      "canonical_id": "BV1234567890",
      "platform": "bilibili",
      "title": "视频标题",
      "source_url": "https://www.bilibili.com/video/BV1234567890",
      "cover_url": "https://...",
      "duration": 600,
      "pages": [
        {
          "page": 1,
          "title": "P1 标题",
          "source_url": "https://...",
          "cover_url": "https://...",
          "duration": 300
        }
      ],
      "is_favorite": false,
      "folder_id": null,
      "latest_task_id": "task_123",
      "latest_status": "completed",
      "created_at": "2024-07-11T10:30:00+00:00",
      "updated_at": "2024-07-11T10:35:00+00:00"
    }
  ],
  "folders": [
    {
      "folder_id": "folder_123",
      "parent_id": null,
      "name": "我的收藏",
      "position": 0,
      "created_at": "2024-07-11T10:30:00+00:00",
      "updated_at": "2024-07-11T10:35:00+00:00"
    }
  ]
}
```

--------------------------------

### 管理系统设置

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/endpoints.md

通过 GET 获取当前配置，或使用 PUT 更新 LLM 及其他系统参数。

```http
GET /api/v1/settings
Authorization: Bearer {ACCESS_TOKEN}
```

```http
PUT /api/v1/settings
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "llm_enabled": true,
  "llm_provider": "openai",
  "llm_api_key": "sk-...",
  "llm_base_url": "https://api.openai.com/v1",
  "llm_model": "gpt-3.5-turbo",
  "summary_mode": "llm",
  "language": "zh"
}
```

--------------------------------

### 获取视频库列表

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/endpoints.md

通过 GET 请求获取视频库中的视频列表及文件夹信息。需在 Header 中提供有效的 Authorization Bearer Token。

```http
GET /api/v1/videos
Authorization: Bearer {ACCESS_TOKEN}
```

```json
{
  "videos": [
    {
      "video_id": "video_123",
      "canonical_id": "BV1234567890",
      "platform": "bilibili",
      "title": "视频标题",
      "source_url": "https://www.bilibili.com/video/BV1234567890",
      "cover_url": "https://...",
      "duration": 600,
      "pages": [
        {
          "page": 1,
          "title": "P1 标题",
          "source_url": "https://...",
          "cover_url": "https://...",
          "duration": 300
        }
      ],
      "is_favorite": false,
      "folder_id": null,
      "latest_task_id": "task_123",
      "latest_status": "completed",
      "created_at": "2024-07-11T10:30:00+00:00",
      "updated_at": "2024-07-11T10:35:00+00:00"
    }
  ],
  "folders": [
    {
      "folder_id": "folder_123",
      "parent_id": null,
      "name": "我的收藏",
      "position": 0,
      "created_at": "2024-07-11T10:30:00+00:00",
      "updated_at": "2024-07-11T10:35:00+00:00"
    }
  ]
}
```

--------------------------------

### Handle UnsupportedInputError

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/errors.md

Example of validating input types and raising an error if the input is unsupported.

```python
from video_sum_core.errors import UnsupportedInputError
from video_sum_core.models.tasks import InputType

try:
    # 确保输入类型被支持
    if input_type not in SUPPORTED_TYPES:
        raise UnsupportedInputError(f"暂不支持 {input_type}")
except UnsupportedInputError as e:
    print(f"输入类型不支持: {e}")
    # 提示用户选择支持的视频源
```

--------------------------------

### Usage examples for extract_youtube_video_id

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/core-utils.md

Demonstrates extracting video IDs from standard, short, and Shorts YouTube URLs.

```python
from video_sum_core.utils import extract_youtube_video_id

extract_youtube_video_id("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
# 返回: "dQw4w9WgXcQ"

extract_youtube_video_id("https://youtu.be/dQw4w9WgXcQ")
# 返回: "dQw4w9WgXcQ"

extract_youtube_video_id("https://www.youtube.com/shorts/abcd1234xyz")
# 返回: "abcd1234xyz"

extract_youtube_video_id("https://bilibili.com/video/BV1234567890")
# 返回: None
```

--------------------------------

### Usage examples for extract_bilibili_page

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/core-utils.md

Demonstrates extracting page numbers from various Bilibili URL formats and invalid inputs.

```python
from video_sum_core.utils import extract_bilibili_page

extract_bilibili_page("https://www.bilibili.com/video/BV1234567890?p=3")
# 返回: 3

extract_bilibili_page("https://b23.tv/BV1234567890?p=1")
# 返回: 1

extract_bilibili_page("https://www.bilibili.com/video/BV1234567890")
# 返回: None（没有 p 参数）

extract_bilibili_page("https://www.youtube.com/watch?v=xxx")
# 返回: None（不是 B 站链接）

extract_bilibili_page("BV1234567890?p=2")
# 返回: 2（仅 BVID 也可识别）
```

--------------------------------

### Get mindmap

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/endpoints.md

Retrieve the generated mindmap for a specific task.

```http
GET /api/v1/tasks/{task_id}/mindmap
Authorization: Bearer {ACCESS_TOKEN}
```

```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ready",
  "error_message": null,
  "updated_at": "2024-07-11T10:35:00+00:00",
  "mindmap": {
    "version": 1,
    "title": "视频标题",
    "root": "root",
    "nodes": [
      {
        "id": "root",
        "label": "视频标题",
        "type": "root",
        "summary": "",
        "children": [{"id": "theme-1", ...}],
        "time_anchor": null,
        "source_chapter_titles": [],
        "source_chapter_starts": []
      }
    ]
  }
}
```

--------------------------------

### Initialize and Run on macOS/Linux

Source: https://github.com/lycohana/bilisum/blob/master/README.md

Standard commands for setting up and running the project on Unix-based systems.

```bash
uv sync --python 3.12 --all-packages
uv run --package video-sum-service python -m video_sum_service
npm run dev
```

--------------------------------

### Get Token Status

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/endpoints.md

Check the validity of the current access token.

```http
GET /api/v1/auth/status
Authorization: Bearer {ACCESS_TOKEN}
```

--------------------------------

### Package Desktop Application

Source: https://github.com/lycohana/bilisum/blob/master/README.md

Build the application for Windows or macOS platforms.

```powershell
npm run package:win     # Windows
npm run package:mac     # macOS
```

--------------------------------

### Workflow Overview

Source: https://github.com/lycohana/bilisum/blob/master/README.md

A high-level visual representation of the BiliSum processing pipeline from video input to knowledge base integration.

```text
B 站 / YouTube / 本地视频  →  转写  →  文本笔记  →  图文笔记  →  思维导图  →  知识库
         ↓                          ↓                          ↓
    B 站扫码登录              可回溯的任务历史             AI 检索问答
```

--------------------------------

### Docker Deployment

Source: https://github.com/lycohana/bilisum/blob/master/README.md

Build and run the application using Docker.

```powershell
# 构建
npm run docker:build

# 运行
docker run --rm -p 3838:3838 \
  -v bilisum-data:/data \
  -e VIDEO_SUM_ACCESS_TOKEN=your-token \
  -e VIDEO_SUM_LLM_ENABLED=true \
  -e VIDEO_SUM_LLM_BASE_URL=https://coding.dashscope.aliyuncs.com/v1 \
  -e VIDEO_SUM_LLM_MODEL=qwen3.5-plus \
  -e VIDEO_SUM_LLM_API_KEY=your-key \
  -e VIDEO_SUM_SILICONFLOW_ASR_API_KEY=your-key \
  lycohana/bilisum:latest
```

```powershell
docker pull lycohana/bilisum:latest
```

--------------------------------

### GET /api/v1/tasks/{task_id}/mindmap

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/endpoints.md

Retrieves the generated mindmap for a task.

```APIDOC
## GET /api/v1/tasks/{task_id}/mindmap

### Description
Fetches the mindmap data for a completed task.

### Method
GET

### Endpoint
/api/v1/tasks/{task_id}/mindmap

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The unique ID of the task

### Response
#### Success Response (200)
- **status** (string) - Status of the mindmap (idle, generating, ready, failed)
- **mindmap** (object) - The mindmap structure
```

--------------------------------

### GET /api/v1/tasks/{task_id}

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/endpoints.md

Retrieves detailed information for a specific task.

```APIDOC
## GET /api/v1/tasks/{task_id}

### Description
Fetches the full details and results of a specific task.

### Method
GET

### Endpoint
/api/v1/tasks/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The unique ID of the task

### Response
#### Success Response (200)
- **task_id** (string) - Task ID
- **status** (string) - Task status
- **result** (object) - Detailed result data including overview, notes, and artifacts
```

--------------------------------

### Configure Development Environment

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/configuration.md

Minimal configuration for local development using CPU-based transcription.

```env
VIDEO_SUM_HOST=127.0.0.1
VIDEO_SUM_PORT=3838
VIDEO_SUM_ACCESS_TOKEN=dev-token-12345

VIDEO_SUM_TRANSCRIPTION_PROVIDER=local
VIDEO_SUM_WHISPER_MODEL=base
VIDEO_SUM_WHISPER_DEVICE=cpu

VIDEO_SUM_LLM_ENABLED=false

VIDEO_SUM_KNOWLEDGE_ENABLED=false
```

--------------------------------

### Import Infrastructure Configuration and LLM Utilities

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/README.md

Imports for service settings and LLM provider integration utilities.

```python
from video_sum_infra.config import ServiceSettings

from video_sum_infra.llm import (
    normalize_llm_provider, is_anthropic_llm, anthropic_messages_url,
    openai_chat_completions_url, extract_text_from_content_blocks,
    build_anthropic_messages_payload
)
```

--------------------------------

### Initialize TaskMindMap instance

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/models.md

Demonstrates how to instantiate a TaskMindMap with nested MindMapNode objects.

```python
from video_sum_core.models.tasks import TaskMindMap, MindMapNode

mindmap = TaskMindMap(
    version=1,
    title="Python 基础",
    root="root",
    nodes=[
        MindMapNode(
            id="root",
            label="Python 基础",
            type="root",
            summary="",
            children=[
                {"id": "theme-1", "label": "基本语法", "type": "theme"}
            ]
        ),
        MindMapNode(
            id="theme-1",
            label="基本语法",
            type="theme",
            summary="Python 变量、数据类型、运算符基础",
            children=[]
        )
    ]
)
```

--------------------------------

### Configure Production Environment

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/configuration.md

Full configuration for production deployment including external ASR, LLM, and knowledge base services.

```env
VIDEO_SUM_HOST=0.0.0.0
VIDEO_SUM_PORT=3838
VIDEO_SUM_ACCESS_TOKEN=$(openssl rand -hex 32)

# 转写
VIDEO_SUM_TRANSCRIPTION_PROVIDER=siliconflow
VIDEO_SUM_SILICONFLOW_ASR_API_KEY=sk-...
VIDEO_SUM_SILICONFLOW_ASR_CONCURRENCY=4

# LLM 摘要
VIDEO_SUM_LLM_ENABLED=true
VIDEO_SUM_LLM_PROVIDER=openai-compatible
VIDEO_SUM_LLM_BASE_URL=https://coding.dashscope.aliyuncs.com/v1
VIDEO_SUM_LLM_MODEL=qwen3.5-plus
VIDEO_SUM_LLM_API_KEY=sk-...

# 知识库
VIDEO_SUM_KNOWLEDGE_ENABLED=true
VIDEO_SUM_KNOWLEDGE_EMBEDDING_PROVIDER=local_huggingface

# 并发
VIDEO_SUM_TASK_CONCURRENCY=4
VIDEO_SUM_MINDMAP_CONCURRENCY=2
```

--------------------------------

### PipelineRunner.preflight()

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/pipeline.md

Performs pre-execution checks such as validating context configuration, checking dependencies, and preparing resources.

```APIDOC
## preflight(context, on_event=None)

### Description
Performs pre-execution checks including context validation, dependency verification, and resource preparation.

### Parameters
- **context** (PipelineContext) - Required - The execution context containing task configuration.
- **on_event** (PipelineEventReporter) - Optional - A callback function to handle progress events.

### Raises
- **ValidationError** - Configuration check failed.
- **LLMConfigurationError** - LLM configuration is incomplete.
- **TranscriptionConfigurationError** - Transcription configuration is incomplete.
```

--------------------------------

### GET /api/v1/knowledge/network

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/endpoints.md

Retrieves the knowledge network graph data including nodes and links.

```APIDOC
## GET /api/v1/knowledge/network

### Description
Retrieves the knowledge network graph data including nodes and links.

### Method
GET

### Endpoint
/api/v1/knowledge/network

### Response
#### Success Response (200)
- **nodes** (array) - 网络节点列表
- **links** (array) - 节点间的连接关系

#### Response Example
{
  "nodes": [
    {
      "id": "tag_1",
      "label": "Python",
      "type": "tag",
      "size": 10,
      "color": "#FF6B6B"
    }
  ],
  "links": [
    {
      "source": "tag_1",
      "target": "tag_2",
      "strength": 0.8
    }
  ]
}
```

--------------------------------

### 配置数据存储路径

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/configuration.md

定义数据、缓存、任务目录以及数据库连接字符串。

```env
# 数据存储目录
VIDEO_SUM_DATA_DIR=/path/to/data

# 缓存目录
VIDEO_SUM_CACHE_DIR=/path/to/cache

# 任务工作目录
VIDEO_SUM_TASKS_DIR=/path/to/tasks

# 数据库 URL
VIDEO_SUM_DATABASE_URL=sqlite:////path/to/data/bilisum.db
```

--------------------------------

### Get task details

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/endpoints.md

Fetch the full details and results of a specific task by its ID.

```http
GET /api/v1/tasks/{task_id}
Authorization: Bearer {ACCESS_TOKEN}
```

```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "result": {
    "overview": "核心概览文本...",
    "knowledge_note_markdown": "# 知识笔记\n...",
    "transcript_text": "转写全文...",
    "segments": [...],
    "segment_summaries": [...],
    "key_points": [...],
    "timeline": [...],
    "chapter_groups": [...],
    "artifacts": {
      "summary_path": "/path/to/summary.json",
      "mindmap_path": "/path/to/mindmap.json"
    },
    "llm_prompt_tokens": 1000,
    "llm_completion_tokens": 500,
    "llm_total_tokens": 1500,
    "mindmap_status": "idle",
    "visual_note_status": "idle"
  }
}
```

--------------------------------

### Create a new task

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/endpoints.md

Submit a video URL or file for processing. The request requires a JSON body specifying the input source and processing options.

```http
POST /api/v1/tasks
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "input_type": "url",
  "source": "https://www.bilibili.com/video/BV1234567890",
  "title": "视频标题",
  "platform_hint": "bilibili",
  "video_id": "optional_video_id",
  "options": {
    "language": "zh",
    "summary_mode": "llm",
    "prompt_preset_id": null,
    "prefer_subtitles": true,
    "export_formats": ["md", "json"],
    "visual_note_mode": null
  }
}
```

```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "video_id": "video_123",
  "status": "queued",
  "title": "视频标题",
  "input_type": "url",
  "source": "https://www.bilibili.com/video/BV1234567890",
  "page_number": null,
  "page_title": null,
  "result": null,
  "error_code": null,
  "error_message": null,
  "created_at": "2024-07-11T10:30:00+00:00",
  "updated_at": "2024-07-11T10:30:00+00:00"
}
```

--------------------------------

### Handle PegasusAuthenticationError

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/errors.md

Example of catching authentication errors caused by invalid or expired API keys.

```python
from video_sum_core.errors import PegasusAuthenticationError
from video_sum_core.twelvelabs import analyze_video_with_pegasus

try:
    summary = analyze_video_with_pegasus(
        api_key="invalid-key",
        video={"type": "url", "url": "https://..."}
    )
except PegasusAuthenticationError as e:
    logger.error(f"Pegasus API Key 无效: {e}")
    # 设置 settings.twelvelabs_summary_enabled = False
    # 或提示用户重新配置 API Key
```

--------------------------------

### Ensure Directory Existence in Python

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/core-utils.md

Creates a directory and any necessary parent directories if they do not exist. Requires a pathlib.Path object as input.

```python
def ensure_directory(path: Path) -> Path:
    """
    确保目录存在，不存在则创建。
    
    Args:
        path: 路径对象
        
    Returns:
        创建或已存在的路径对象
    """
```

```python
from pathlib import Path
from video_sum_core.utils import ensure_directory

output_dir = ensure_directory(Path("/workspace/output/tasks"))
# 创建 /workspace/output/tasks 及所有父目录
# 返回: PosixPath('/workspace/output/tasks')
```

--------------------------------

### Handle TranscriptionAuthenticationError

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/errors.md

Example of catching authentication errors when using a transcription provider like SiliconFlow.

```python
from video_sum_core.errors import TranscriptionAuthenticationError

try:
    transcript = transcribe_with_siliconflow(audio)
except TranscriptionAuthenticationError as e:
    logger.error(f"转写服务认证失败: {e}")
    # 显示错误，建议用户检查 API Key
```

--------------------------------

### 实现自定义 PipelineRunner

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/pipeline.md

通过继承 PipelineRunner 类并实现 preflight 和 run 方法来定义处理逻辑。需注意在 run 方法中处理异常并上报 PipelineEvent。

```python
from video_sum_core.pipeline.base import (
    PipelineRunner,
    PipelineContext,
    PipelineEvent,
    PipelineEventReporter
)
from video_sum_core.models.tasks import TaskResult
from video_sum_core.errors import VideoSumError

class CustomPipelineRunner(PipelineRunner):
    """自定义处理管道实现。"""
    
    def preflight(
        self,
        context: PipelineContext,
        on_event: PipelineEventReporter | None = None,
    ) -> None:
        """预检查实现。"""
        # 验证输入
        if not context.task_input.source:
            raise ValueError("source 不能为空")
        
        # 验证配置
        if context.task_input.options.language not in ["zh", "en"]:
            raise ValueError("不支持的语言")
        
        # 发出事件
        if on_event:
            on_event(PipelineEvent(
                stage="preflight",
                progress=0,
                message="预检查通过"
            ))
    
    def run(
        self,
        context: PipelineContext,
        on_event: PipelineEventReporter | None = None,
    ) -> tuple[list[PipelineEvent], TaskResult]:
        """管道实现。"""
        events = []
        result = TaskResult()
        
        try:
            # 预检查
            self.preflight(context, on_event)
            
            # 各处理阶段
            events.append(PipelineEvent(stage="accepted", progress=0, message="开始处理"))
            
            # 下载阶段
            for evt in self._run_download(context):
                events.append(evt)
                if on_event:
                    on_event(evt)
            
            # 转写阶段
            for evt, partial_result in self._run_transcribe(context):
                events.append(evt)
                if on_event:
                    on_event(evt)
            
            # 最终结果
            events.append(PipelineEvent(stage="completed", progress=100, message="处理完成"))
            
            return events, result
            
        except VideoSumError as e:
            events.append(PipelineEvent(stage="failed", progress=0, message=str(e)))
            if on_event:
                on_event(events[-1])
            raise
```

--------------------------------

### GET /api/v1/auth/status

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/endpoints.md

Retrieves the current status of the provided Access Token to verify if it is authenticated and valid.

```APIDOC
## GET /api/v1/auth/status

### Description
Checks the status of the provided Access Token to confirm authentication status.

### Method
GET

### Endpoint
/api/v1/auth/status

### Response
#### Success Response (200)
- **authenticated** (boolean) - Indicates if the user is authenticated.
- **token_valid** (boolean) - Indicates if the token is currently valid.

#### Response Example
{
  "authenticated": true,
  "token_valid": true
}
```

--------------------------------

### Configure LLM Summarization

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/configuration.md

General configuration for enabling LLM summarization and setting the provider, model, and API credentials.

```env
VIDEO_SUM_LLM_ENABLED=true
VIDEO_SUM_LLM_PROVIDER=openai-compatible
# openai、anthropic、openai-compatible
VIDEO_SUM_LLM_BASE_URL=https://coding.dashscope.aliyuncs.com/v1
VIDEO_SUM_LLM_MODEL=qwen3.5-plus
VIDEO_SUM_LLM_API_KEY=your-api-key
```

```env
VIDEO_SUM_LLM_PROVIDER=openai
VIDEO_SUM_LLM_BASE_URL=https://api.openai.com/v1
VIDEO_SUM_LLM_MODEL=gpt-3.5-turbo
VIDEO_SUM_LLM_API_KEY=sk-...
```

```env
VIDEO_SUM_LLM_PROVIDER=anthropic
VIDEO_SUM_LLM_BASE_URL=https://api.anthropic.com/v1
VIDEO_SUM_LLM_MODEL=claude-3-haiku
VIDEO_SUM_LLM_API_KEY=sk-ant-...
```

```env
VIDEO_SUM_LLM_PROVIDER=openai-compatible
VIDEO_SUM_LLM_BASE_URL=https://coding.dashscope.aliyuncs.com/v1
VIDEO_SUM_LLM_MODEL=qwen3.5-plus
VIDEO_SUM_LLM_API_KEY=your-key
```

--------------------------------

### List all tasks

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/endpoints.md

Retrieve a list of all existing tasks.

```http
GET /api/v1/tasks
Authorization: Bearer {ACCESS_TOKEN}
```

```json
[
  {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "video_id": "video_123",
    "status": "completed",
    "title": "视频标题",
    "created_at": "2024-07-11T10:30:00+00:00",
    "updated_at": "2024-07-11T10:35:00+00:00"
  }
]
```

--------------------------------

### Use anthropic_messages_url function

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/infra-llm.md

Examples of generating Anthropic message URLs with various base URL formats.

```python
from video_sum_infra.llm import anthropic_messages_url

anthropic_messages_url("https://api.anthropic.com/v1")
# 返回: "https://api.anthropic.com/v1/messages"

anthropic_messages_url("https://api.anthropic.com/v1/")
# 返回: "https://api.anthropic.com/v1/messages"

anthropic_messages_url("https://api.anthropic.com/v1/messages")
# 返回: "https://api.anthropic.com/v1/messages"
```

--------------------------------

### Configure Docker Environment

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/configuration.md

Configuration template for containerized deployments with persistent data directory mapping.

```env
VIDEO_SUM_HOST=0.0.0.0
VIDEO_SUM_PORT=3838
VIDEO_SUM_DATA_DIR=/data
VIDEO_SUM_ACCESS_TOKEN=your-secure-token

VIDEO_SUM_LLM_ENABLED=true
VIDEO_SUM_LLM_PROVIDER=openai-compatible
VIDEO_SUM_LLM_BASE_URL=https://api.openai.com/v1
VIDEO_SUM_LLM_MODEL=gpt-3.5-turbo
VIDEO_SUM_LLM_API_KEY=sk-...

VIDEO_SUM_SILICONFLOW_ASR_API_KEY=your-key
```

--------------------------------

### Environment Variable Configuration

Source: https://github.com/lycohana/bilisum/blob/master/README.md

Configure API keys and service settings in the .env file.

```env
VIDEO_SUM_HOST=127.0.0.1
VIDEO_SUM_PORT=3838
VIDEO_SUM_ACCESS_TOKEN=replace-with-a-long-random-token

# 转写（SiliconFlow）
VIDEO_SUM_TRANSCRIPTION_PROVIDER=siliconflow
VIDEO_SUM_SILICONFLOW_ASR_BASE_URL=https://api.siliconflow.cn/v1
VIDEO_SUM_SILICONFLOW_ASR_MODEL=TeleAI/TeleSpeechASR
VIDEO_SUM_SILICONFLOW_ASR_API_KEY=your-key

# LLM 摘要
VIDEO_SUM_LLM_ENABLED=true
VIDEO_SUM_LLM_PROVIDER=openai-compatible
VIDEO_SUM_LLM_BASE_URL=https://coding.dashscope.aliyuncs.com/v1
VIDEO_SUM_LLM_MODEL=qwen3.5-plus
VIDEO_SUM_LLM_API_KEY=your-key

# B 站 Cookies（遇到风控时配置）
VIDEO_SUM_YTDLP_COOKIES_FILE=
```

--------------------------------

### PipelineRunner.run()

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/pipeline.md

Executes the full video processing pipeline and returns the event history and final task results.

```APIDOC
## run(context, on_event=None)

### Description
Executes the complete processing pipeline, triggering events throughout the lifecycle and returning the final output.

### Parameters
- **context** (PipelineContext) - Required - The execution context.
- **on_event** (PipelineEventReporter) - Optional - A callback function for real-time progress updates.

### Returns
- **tuple[list[PipelineEvent], TaskResult]** - A tuple containing the list of all events emitted during execution and the final TaskResult object.

### Raises
- **VideoSumError** - Errors encountered during the processing pipeline.
```

--------------------------------

### 创建任务对象

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/INDEX.md

使用 TaskInput 和 TaskOptions 定义视频处理任务的输入参数。

```python
from video_sum_core.models.tasks import TaskInput, InputType, TaskOptions

task_input = TaskInput(
    input_type=InputType.URL,
    source="https://www.bilibili.com/video/BV1234567890",
    title="视频标题",
    options=TaskOptions(language="zh", summary_mode="llm")
)
```

--------------------------------

### PipelineRunner preflight Method Definition

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/pipeline.md

Signature and documentation for the preflight check method.

```python
def preflight(
    self,
    context: PipelineContext,
    on_event: PipelineEventReporter | None = None,
) -> None:
    """
    验证上下文配置、检查依赖、准备资源等。
    
    Args:
        context: 执行上下文
        on_event: 事件回调（可选）
        
    Raises:
        ValidationError: 配置检查失败
        LLMConfigurationError: LLM 配置不完整
        TranscriptionConfigurationError: 转写配置不完整
    """
```

--------------------------------

### Verify Source Paths

Source: https://github.com/lycohana/bilisum/blob/master/README.md

Check if the imported modules are pointing to the local repository source files to troubleshoot stale logic.

```powershell
uv run --package video-sum-service python -c "import video_sum_core, video_sum_service; print(video_sum_core.__file__); print(video_sum_service.__file__)"
```

--------------------------------

### Configure Visual Note Generation

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/configuration.md

Settings to enable visual note modes and multimodal processing.

```env
VIDEO_SUM_VISUAL_NOTE_MODE=vlm_integrated
# text（禁用）、frame_insert（仅插入截图）、vlm_integrated（VLM 理解型）
VIDEO_SUM_VISUAL_EVIDENCE_ENABLED=true
VIDEO_SUM_VISUAL_MULTIMODAL_ENABLED=true
```

--------------------------------

### PipelineRunner run Method Definition

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/pipeline.md

Signature and documentation for the run method.

```python
def run(
    self,
    context: PipelineContext,
    on_event: PipelineEventReporter | None = None,
) -> tuple[list[PipelineEvent], TaskResult]:
    """
    执行完整处理管道。
    
    Args:
        context: 执行上下文
        on_event: 事件回调（可选，用于前端实时更新）
        
    Returns:
        (events_list, result)：
        - events_list: 所有过程中发出的事件列表
        - result: TaskResult 对象，包含所有输出
        
    Raises:
        VideoSumError: 处理过程中的各种错误
    """
```

--------------------------------

### POST /api/v1/tasks

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/endpoints.md

Creates a new video summarization task.

```APIDOC
## POST /api/v1/tasks

### Description
Creates a new video summarization task based on the provided input source.

### Method
POST

### Endpoint
/api/v1/tasks

### Parameters
#### Request Body
- **input_type** (string) - Required - url, video_file, audio_file, or transcript_text
- **source** (string) - Required - URL, file path, or text content
- **title** (string) - Optional - Video title
- **platform_hint** (string) - Optional - bilibili, youtube, or unknown
- **video_id** (string) - Optional - Associated video ID
- **options** (object) - Optional - Task execution options

### Response
#### Success Response (201)
- **task_id** (string) - Unique identifier for the task
- **status** (string) - Current status of the task
- **created_at** (string) - Creation timestamp
```

--------------------------------

### Configure Knowledge Base Embedding

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/configuration.md

General settings for enabling the knowledge base and selecting an embedding provider.

```env
VIDEO_SUM_KNOWLEDGE_ENABLED=true
VIDEO_SUM_KNOWLEDGE_EMBEDDING_PROVIDER=local_huggingface
# local_huggingface、local_modelscope、siliconflow、online
VIDEO_SUM_KNOWLEDGE_EMBEDDING_MODEL=BAAI/bge-small-zh-v1.5
```

--------------------------------

### 捕获 VideoSumError 异常

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/errors.md

在执行 BiliSum 相关操作时捕获所有业务异常。

```python
from video_sum_core.errors import VideoSumError

try:
    # 任何 BiliSum 操作
    result = process_video(...)
except VideoSumError as e:
    logger.error(f"视频处理失败: {e}")
```

--------------------------------

### Import Core Models and Utilities

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/README.md

Imports for task management, input handling, and utility functions within the core package.

```python
from video_sum_core.models.tasks import (
    TaskStatus, InputType, TaskInput, TaskOptions, TaskResult,
    MindMapNode, TaskMindMap
)

from video_sum_core.utils import (
    normalize_video_url, extract_bilibili_page, extract_youtube_video_id,
    sanitize_filename, ensure_directory, format_timestamp
)

from video_sum_core.errors import (
    VideoSumError, LLMConfigurationError, LLMAuthenticationError,
    TranscriptionConfigurationError, TranscriptionAuthenticationError,
    UnsupportedInputError, PegasusConfigurationError, PegasusAuthenticationError
)

from video_sum_core.twelvelabs import (
    video_context_from_url, video_context_from_file, analyze_video_with_pegasus
)

from video_sum_core.pipeline.base import (
    PipelineRunner, PipelineContext, PipelineEvent, PipelineEventReporter
)
```

--------------------------------

### 实现自定义处理管道

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/INDEX.md

通过继承 PipelineRunner 类实现自定义的预检查和处理逻辑。

```python
from video_sum_core.pipeline.base import PipelineRunner, PipelineContext

class MyPipeline(PipelineRunner):
    def preflight(self, context, on_event=None):
        # 预检查
        pass
    
    def run(self, context, on_event=None):
        # 执行处理
        pass
```

--------------------------------

### 选择转写提供商

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/configuration.md

指定当前使用的转写服务提供商。

```env
# 转写提供商
VIDEO_SUM_TRANSCRIPTION_PROVIDER=siliconflow
# 可选: siliconflow、local、funasr、multimodal
```

--------------------------------

### Log Pipeline Events to Database

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/pipeline.md

Demonstrates how to persist pipeline events to a database using a callback function during execution.

```python
def save_event_to_db(task_id: str, event: PipelineEvent):
    """将事件保存到数据库。"""
    repository.create_task_event(
        task_id=task_id,
        stage=event.stage,
        progress=event.progress,
        message=event.message,
        payload=event.payload
    )

def run_with_event_logging(
    runner: PipelineRunner,
    context: PipelineContext,
    task_id: str
):
    """执行并保存所有事件。"""
    def log_event(event):
        save_event_to_db(task_id, event)
    
    events, result = runner.run(context, on_event=log_event)
    return result
```

--------------------------------

### video_context_from_url(url: str)

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/twelvelabs.md

Constructs a Pegasus video source object from a direct media URL. This is used to prepare the video context for analysis.

```APIDOC
## video_context_from_url(url: str)

### Description
Constructs a Pegasus video source object from a direct media URL (e.g., CDN link).

### Parameters
- **url** (str) - Required - The direct URL of the video.

### Returns
- **dict[str, str]** - A dictionary containing the video source: {"type": "url", "url": "..."}

### Example
```python
video_context = video_context_from_url("https://cdn.example.com/video.mp4")
# Returns: {"type": "url", "url": "https://cdn.example.com/video.mp4"}
```
```

--------------------------------

### GET/PUT /api/v1/settings

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/endpoints.md

Retrieves or updates the application configuration settings.

```APIDOC
## GET /api/v1/settings

### Description
Retrieves the current application settings.

### Method
GET

### Endpoint
/api/v1/settings

## PUT /api/v1/settings

### Description
Updates the application configuration settings.

### Method
PUT

### Endpoint
/api/v1/settings

### Request Body
- **llm_enabled** (boolean) - Whether LLM summary is enabled
- **llm_provider** (string) - LLM provider (openai, anthropic, openai-compatible)
- **llm_api_key** (string) - LLM API Key
- **llm_base_url** (string) - LLM base URL
- **llm_model** (string) - LLM model name
- **summary_mode** (string) - Summary mode
- **language** (string) - Language setting
```

--------------------------------

### ensure_directory(path: Path) -> Path

Source: https://github.com/lycohana/bilisum/blob/master/_autodocs/api-reference/core-utils.md

Ensures that a directory exists, creating it and any necessary parent directories if they do not exist.

```APIDOC
## ensure_directory(path: Path) -> Path

### Description
Checks if a directory exists at the specified path. If the directory does not exist, it creates the directory and all required parent directories.

### Parameters
- **path** (Path) - Required - A pathlib.Path object representing the target directory.

### Returns
- **Path** - The Path object of the created or existing directory.
```