openapi.yaml

openapi: 3.0.3
info:
  title: FFprobe API
  description: |
    A comprehensive REST API for media file analysis using FFmpeg/FFprobe.
    
    This API provides endpoints for:
    - Media file analysis and probing
    - Video quality analysis with VMAF, PSNR, SSIM metrics
    - HLS manifest analysis and validation
    - Report generation in multiple formats
    - Cloud storage integration
    - AI-powered analysis insights
    
    ## Authentication
    
    The API supports multiple authentication methods:
    - API Key authentication via `X-API-Key` header
    - JWT Bearer token authentication
    - Basic authentication for legacy systems
    
    ## Rate Limiting
    
    Rate limits are enforced per API key/user:
    - 60 requests per minute
    - 1000 requests per hour
    - 10000 requests per day
    
    ## File Upload
    
    Maximum file size: 50GB
    Supported formats: All FFmpeg supported formats
    
  version: "2.0.0"
  contact:
    name: FFprobe API Support
    url: https://github.com/rendiffdev/rendiff-probe
    email: dev@rendiff.dev
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:8080/api/v1
    description: Local development server

security:
  - ApiKeyAuth: []
  - BearerAuth: []

paths:
  /health:
    get:
      summary: Health check
      description: Check the health status of the API service
      operationId: healthCheck
      tags:
        - System
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '503':
          description: Service is unhealthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /auth/login:
    post:
      summary: Login
      description: Authenticate user and get JWT token
      operationId: login
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /probe/file:
    post:
      summary: Analyze media file
      description: Analyze a media file using FFprobe
      operationId: probeFile
      tags:
        - Analysis
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProbeFileRequest'
      responses:
        '200':
          description: Analysis started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /probe/status/{id}:
    get:
      summary: Get analysis status
      description: Get the status of a media analysis job
      operationId: getAnalysisStatus
      tags:
        - Analysis
      parameters:
        - name: id
          in: path
          required: true
          description: Analysis ID
          schema:
            type: string
      responses:
        '200':
          description: Analysis status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisStatus'
        '404':
          description: Analysis not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /probe/hls:
    post:
      summary: Analyze HLS playlist
      description: Analyze an HLS playlist and its segments
      operationId: analyzeHLS
      tags:
        - HLS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HLSAnalysisRequest'
      responses:
        '200':
          description: HLS analysis started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisResponse'

  /probe/compare:
    post:
      summary: Compare video quality
      description: Compare quality between reference and distorted videos
      operationId: compareQuality
      tags:
        - Quality
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QualityComparisonRequest'
      responses:
        '200':
          description: Quality comparison started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisResponse'

  /probe/report:
    post:
      summary: Generate analysis report
      description: Generate a report from analysis results in various formats
      operationId: generateReport
      tags:
        - Reports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportRequest'
      responses:
        '200':
          description: Report generation started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResponse'

  /storage/upload:
    post:
      summary: Upload file to storage
      description: Upload a file to configured cloud storage
      operationId: uploadFile
      tags:
        - Storage
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: File to upload
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResponse'

  /storage/download/{key}:
    get:
      summary: Download file from storage
      description: Download a file from storage by key
      operationId: downloadFile
      tags:
        - Storage
      parameters:
        - name: key
          in: path
          required: true
          description: File key in storage
          schema:
            type: string
      responses:
        '200':
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

  /ask:
    post:
      summary: Ask AI about analysis
      description: Ask AI-powered questions about analysis results
      operationId: askAI
      tags:
        - AI
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AIQuestionRequest'
      responses:
        '200':
          description: AI response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIResponse'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          enum: [healthy, unhealthy]
        service:
          type: string
        version:
          type: string
        database:
          type: string
        uptime:
          type: string
      required:
        - status
        - service
        - version

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        code:
          type: integer
        timestamp:
          type: string
          format: date-time
        request_id:
          type: string
      required:
        - error
        - message

    LoginRequest:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
      required:
        - username
        - password

    LoginResponse:
      type: object
      properties:
        token:
          type: string
        refresh_token:
          type: string
        expires_in:
          type: integer
        user:
          $ref: '#/components/schemas/User'
      required:
        - token
        - expires_in

    User:
      type: object
      properties:
        id:
          type: string
        username:
          type: string
        email:
          type: string
        role:
          type: string
        created_at:
          type: string
          format: date-time

    ProbeFileRequest:
      type: object
      properties:
        file_path:
          type: string
          description: Path to the media file
        url:
          type: string
          description: URL to the media file (alternative to file_path)
        options:
          $ref: '#/components/schemas/AnalysisOptions'
      anyOf:
        - required: [file_path]
        - required: [url]

    AnalysisOptions:
      type: object
      properties:
        include_streams:
          type: boolean
          default: true
        include_format:
          type: boolean
          default: true
        include_chapters:
          type: boolean
          default: false
        show_entries:
          type: string
          description: FFprobe show_entries parameter
        timeout:
          type: integer
          description: Analysis timeout in seconds
          default: 300

    AnalysisResponse:
      type: object
      properties:
        analysis_id:
          type: string
        status:
          type: string
          enum: [pending, processing, completed, failed]
        message:
          type: string
        created_at:
          type: string
          format: date-time
      required:
        - analysis_id
        - status

    AnalysisStatus:
      type: object
      properties:
        analysis_id:
          type: string
        status:
          type: string
          enum: [pending, processing, completed, failed]
        progress:
          type: integer
          minimum: 0
          maximum: 100
        result:
          $ref: '#/components/schemas/AnalysisResult'
        error:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - analysis_id
        - status
        - progress

    AnalysisResult:
      type: object
      properties:
        format:
          $ref: '#/components/schemas/FormatInfo'
        streams:
          type: array
          items:
            $ref: '#/components/schemas/StreamInfo'
        chapters:
          type: array
          items:
            $ref: '#/components/schemas/ChapterInfo'

    FormatInfo:
      type: object
      properties:
        filename:
          type: string
        nb_streams:
          type: integer
        nb_programs:
          type: integer
        format_name:
          type: string
        format_long_name:
          type: string
        start_time:
          type: string
        duration:
          type: string
        size:
          type: string
        bit_rate:
          type: string
        probe_score:
          type: integer
        tags:
          type: object
          additionalProperties:
            type: string

    StreamInfo:
      type: object
      properties:
        index:
          type: integer
        codec_name:
          type: string
        codec_long_name:
          type: string
        profile:
          type: string
        codec_type:
          type: string
        codec_time_base:
          type: string
        codec_tag_string:
          type: string
        codec_tag:
          type: string
        width:
          type: integer
        height:
          type: integer
        coded_width:
          type: integer
        coded_height:
          type: integer
        has_b_frames:
          type: integer
        sample_aspect_ratio:
          type: string
        display_aspect_ratio:
          type: string
        pix_fmt:
          type: string
        level:
          type: integer
        color_range:
          type: string
        color_space:
          type: string
        color_transfer:
          type: string
        color_primaries:
          type: string
        chroma_location:
          type: string
        field_order:
          type: string
        refs:
          type: integer
        r_frame_rate:
          type: string
        avg_frame_rate:
          type: string
        time_base:
          type: string
        start_pts:
          type: integer
        start_time:
          type: string
        duration_ts:
          type: integer
        duration:
          type: string
        bit_rate:
          type: string
        bits_per_raw_sample:
          type: string
        nb_frames:
          type: string
        tags:
          type: object
          additionalProperties:
            type: string

    ChapterInfo:
      type: object
      properties:
        id:
          type: integer
        time_base:
          type: string
        start:
          type: integer
        start_time:
          type: string
        end:
          type: integer
        end_time:
          type: string
        tags:
          type: object
          additionalProperties:
            type: string

    HLSAnalysisRequest:
      type: object
      properties:
        manifest_url:
          type: string
          description: URL to the HLS manifest file
        analyze_segments:
          type: boolean
          default: false
        segment_limit:
          type: integer
          description: Limit number of segments to analyze
          default: 10
      required:
        - manifest_url

    QualityComparisonRequest:
      type: object
      properties:
        reference_file:
          type: string
          description: Path to reference video file
        distorted_file:
          type: string
          description: Path to distorted video file
        metrics:
          type: array
          items:
            type: string
            enum: [vmaf, psnr, ssim, ms_ssim]
          default: [vmaf, psnr, ssim]
        model_path:
          type: string
          description: Path to VMAF model file
      required:
        - reference_file
        - distorted_file

    ReportRequest:
      type: object
      properties:
        analysis_id:
          type: string
        format:
          type: string
          enum: [json, pdf, html, csv, xml, excel, markdown, text]
          default: json
        template:
          type: string
          description: Report template name
        options:
          type: object
          description: Format-specific options
      required:
        - analysis_id

    ReportResponse:
      type: object
      properties:
        report_id:
          type: string
        status:
          type: string
          enum: [pending, processing, completed, failed]
        format:
          type: string
        download_url:
          type: string
        created_at:
          type: string
          format: date-time
      required:
        - report_id
        - status
        - format

    UploadResponse:
      type: object
      properties:
        upload_id:
          type: string
        key:
          type: string
        url:
          type: string
        size:
          type: integer
        content_type:
          type: string
        created_at:
          type: string
          format: date-time
      required:
        - upload_id
        - key
        - size

    AIQuestionRequest:
      type: object
      properties:
        analysis_id:
          type: string
        question:
          type: string
        context:
          type: string
          description: Additional context for the question
      required:
        - analysis_id
        - question

    AIResponse:
      type: object
      properties:
        answer:
          type: string
        confidence:
          type: number
          minimum: 0
          maximum: 1
        sources:
          type: array
          items:
            type: string
        timestamp:
          type: string
          format: date-time
      required:
        - answer

tags:
  - name: System
    description: System health and status endpoints
  - name: Authentication
    description: User authentication and authorization
  - name: Analysis
    description: Media file analysis and probing
  - name: HLS
    description: HLS playlist analysis and validation
  - name: Quality
    description: Video quality analysis and comparison
  - name: Reports
    description: Analysis report generation
  - name: Storage
    description: File storage and management
  - name: AI
    description: AI-powered analysis insights