demo
/
youtube-summarizer
1
0
Fork 0
Code Issues 8 Pull Requests 1 Packages Projects Releases Wiki Activity
youtube-summarizer/docs/EXPORT_API.md

7.9 KiB
Raw Permalink Blame History

Export API Documentation

Overview

The YouTube Summarizer Export API provides comprehensive functionality for exporting video summaries in multiple formats with customizable templates and bulk operations.

Features

🎨 Supported Export Formats

  • Markdown (.md) - Clean, formatted text for documentation
  • PDF (.pdf) - Professional documents with formatting and branding
  • HTML (.html) - Responsive web pages with embedded styles
  • JSON (.json) - Structured data with full metadata
  • Plain Text (.txt) - Simple, readable text format

🛠️ Template System

  • Jinja2 Templates - Full template engine support
  • Default Templates - Pre-configured templates for each format
  • Custom Templates - Create and manage your own templates
  • Template Variables - Access to all summary data and metadata
  • Live Preview - Preview templates with sample data

📦 Bulk Export

  • Multiple Formats - Export to multiple formats simultaneously
  • ZIP Archives - Organized folder structure in compressed archives
  • Organization Options:
    • By format (markdown/, pdf/, etc.)
    • By date (2025-01-25/, 2025-01-26/, etc.)
    • By video (separate folder per video)

API Endpoints

Single Export

POST /api/export/single

Export a single summary to the specified format.

Request Body:

{
  "summary_id": "abc123",
  "format": "markdown",
  "template": "default",
  "include_metadata": true,
  "custom_branding": {
    "company_name": "My Company",
    "primary_color": "#2563eb",
    "secondary_color": "#1e40af"
  }
}

Response:

{
  "export_id": "uuid-1234",
  "status": "completed",
  "format": "markdown",
  "download_url": "/api/export/download/uuid-1234",
  "file_size_bytes": 2048,
  "created_at": "2025-01-26T12:00:00Z",
  "completed_at": "2025-01-26T12:00:01Z"
}

Bulk Export

POST /api/export/bulk

Export multiple summaries to a ZIP archive.

Request Body:

{
  "summary_ids": ["abc123", "def456", "ghi789"],
  "formats": ["markdown", "pdf"],
  "organize_by": "format",
  "include_metadata": true,
  "template": "default"
}

Response:

{
  "export_id": "uuid-5678",
  "status": "processing",
  "created_at": "2025-01-26T12:00:00Z",
  "estimated_time_remaining": 30
}

Export Status

GET /api/export/status/{export_id}

Check the status of an export operation.

Response:

{
  "export_id": "uuid-5678",
  "status": "completed",
  "format": "zip",
  "download_url": "/api/export/download/uuid-5678",
  "file_size_bytes": 102400,
  "created_at": "2025-01-26T12:00:00Z",
  "completed_at": "2025-01-26T12:00:30Z"
}

Download Export

GET /api/export/download/{export_id}

Download the exported file.

Response: File download (appropriate MIME type)

List Exports

GET /api/export/list

List all export operations with pagination.

Query Parameters:

  • page (default: 1) - Page number
  • page_size (default: 10) - Items per page
  • status (optional) - Filter by status

Response:

{
  "exports": [...],
  "total": 42,
  "page": 1,
  "page_size": 10
}

Available Formats

GET /api/export/formats

Get list of available export formats.

Response:

{
  "formats": [
    {
      "format": "markdown",
      "name": "Markdown",
      "description": "Clean, formatted Markdown for documentation",
      "available": true
    },
    {
      "format": "pdf",
      "name": "PDF",
      "description": "Professional PDF with formatting and branding",
      "available": true,
      "requires_install": false
    }
  ]
}

Template API

List Templates

GET /api/templates/list

List all available templates.

Query Parameters:

  • template_type (optional) - Filter by type (markdown, html, text)

Response:

[
  {
    "id": "markdown_default",
    "name": "default",
    "description": "Default Markdown template",
    "type": "markdown",
    "variables": ["video_metadata", "summary", "key_points"],
    "is_default": true,
    "preview_available": true
  }
]

Get Template

GET /api/templates/{template_type}/{template_name}

Get a specific template with details.

Query Parameters:

  • include_preview (default: false) - Include preview with sample data

Response:

{
  "id": "markdown_custom",
  "name": "custom",
  "description": "Custom Markdown template",
  "type": "markdown",
  "variables": ["video_metadata", "summary"],
  "is_default": false,
  "content": "# {{ video_metadata.title }}\n\n{{ summary }}",
  "preview": "# Sample Video Title\n\nThis is a sample summary..."
}

Create Template

POST /api/templates/create

Create a new custom template.

Request Body:

{
  "name": "my-template",
  "type": "markdown",
  "content": "# {{ video_metadata.title }}\n\n{{ summary }}",
  "description": "My custom template"
}

Update Template

PUT /api/templates/{template_type}/{template_name}

Update an existing template.

Request Body:

{
  "content": "# Updated: {{ video_metadata.title }}",
  "description": "Updated description"
}

Delete Template

DELETE /api/templates/{template_type}/{template_name}

Delete a custom template.

Validate Template

POST /api/templates/validate

Validate template syntax without saving.

Request Body:

{
  "content": "# {{ video_metadata.title }}",
  "template_type": "markdown"
}

Response:

{
  "valid": true,
  "variables": ["video_metadata"],
  "message": "Template syntax is valid"
}

Frontend Components

ExportDialog Component

Single export dialog with format selection and options.

import { ExportDialog } from '@/components/ExportDialog'

<ExportDialog
  summaryId="abc123"
  videoTitle="My Video"
  trigger={<Button>Export</Button>}
/>

BulkExportDialog Component

Bulk export dialog for multiple summaries.

import { BulkExportDialog } from '@/components/BulkExportDialog'

<BulkExportDialog
  summaryIds={["abc123", "def456"]}
  trigger={<Button>Bulk Export</Button>}
/>

Template Variables

Templates have access to the following variables:

video_metadata

  • title - Video title
  • channel_name - Channel name
  • duration - Video duration
  • published_at - Publication date
  • view_count - View count
  • like_count - Like count
  • thumbnail_url - Thumbnail URL

summary_data

  • summary - Main summary text
  • key_points - Array of key points
  • main_themes - Array of main themes
  • actionable_insights - Array of actionable insights
  • confidence_score - AI confidence score
  • quality_score - Quality assessment score

export_metadata

  • exported_at - Export timestamp
  • exporter_version - Exporter version
  • youtube_summarizer_version - App version

processing_metadata

  • model - AI model used
  • processing_time_seconds - Processing duration
  • tokens_used - Token count
  • timestamp - Processing timestamp

Error Handling

All API endpoints return standardized error responses:

{
  "detail": "Error message",
  "status_code": 400,
  "error_code": "INVALID_FORMAT"
}

Common error codes:

  • INVALID_FORMAT - Unsupported export format
  • TEMPLATE_NOT_FOUND - Template doesn't exist
  • EXPORT_NOT_FOUND - Export ID not found
  • EXPORT_FAILED - Export process failed
  • TEMPLATE_SYNTAX_ERROR - Invalid template syntax

Rate Limiting

Export operations are rate-limited to prevent abuse:

  • Single exports: 60 per minute
  • Bulk exports: 10 per minute
  • Template operations: 100 per minute

File Size Limits

  • Single export: Maximum 10MB per file
  • Bulk export: Maximum 100MB per ZIP archive
  • Template size: Maximum 100KB

Cache Duration

  • Export files: Cached for 24 hours
  • Export status: Cached for 1 hour
  • Template previews: Cached for 5 minutes

Security

  • All downloads require valid export IDs
  • Export IDs expire after 24 hours
  • Templates are sanitized to prevent XSS
  • File paths are validated to prevent directory traversal

Last updated: 2025-08-26