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 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