---
openapi: 3.0.1
info:
  title: MediaConvert.io API
  version: v1.0.0
  description: |
    ## Why MediaConvert.io?

    **High-performance, cost-effective media conversion API service with volume-based pricing.**

    MediaConvert.io provides a developer-first API for converting videos, audio files, and images using Intel-accelerated processing. Built for scale with transparent pricing based on data processed rather than processing time.

    ## Key Features

    - **5-10x Faster Processing** via Intel Quick Sync Video hardware acceleration
    - **50-70% Lower Costs** with volume-based pricing (€0.001-0.003 per MB vs competitors' €0.01-0.02 per minute)
    - **S3-Native Integration** with presigned URLs for secure, direct file access
    - **Real-time Progress Updates** via WebSockets and webhooks
    - **Comprehensive Format Support** for video, audio, and image conversions
    - **Developer-First Design** with comprehensive SDKs and documentation

    ## Pricing Model

    MediaConvert.io uses transparent volume-based pricing:

    - **Video Conversion**: fixed price per MB processed
    - **Audio Conversion**: fixed price per MB processed
    - **Image Conversion**: fixed price per MB processed

    See current prices [here](https://mediaconvert.io/pricing)

    Pricing is based on input + output file sizes, not processing time. This provides predictable costs and rewards efficient file handling.

    ## Quick Start

    1. **Create Account**: Sign up at [mediaconvert.io](https://mediaconvert.io)
    2. **Get API Token**: Generate token in your account dashboard
    3. **Add Credits**: Purchase credits for conversion processing
    4. **Start Converting**: Use the API endpoints below

    ## Authentication

    All API endpoints require Bearer token authentication. Include your API token in the Authorization header:

    ```
    Authorization: Bearer your-api-token-here
    ```

    ## Support

    - Documentation: [docs.mediaconvert.io](https://mediaconvert.io/docs)
    - Email: support@mediaconvert.io
    - Status Page: [status.mediaconvert.io](https://mediaconvert.io/status)
  contact:
    name: MediaConvert.io Support
    url: https://mediaconvert.io/support
    email: support@mediaconvert.io
  license:
    name: Commercial License
    url: https://mediaconvert.io/terms
  termsOfService: https://mediaconvert.io/terms
paths:
  "/api/v1/me":
    get:
      summary: Get current user information
      tags:
      - Account
      description: Retrieve information about the authenticated user and their current
        account
      operationId: getCurrentUser
      security:
      - BearerAuth: []
      responses:
        '200':
          description: User information retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: object
                    properties:
                      id:
                        type: string
                      email:
                        type: string
                        format: email
                      name:
                        type: string
                      created_at:
                        type: string
                        format: date-time
                    required:
                    - id
                    - email
                    - name
                    - created_at
                  account:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      created_at:
                        type: string
                        format: date-time
                    required:
                    - id
                    - name
                    - created_at
                  api_limits:
                    type: object
                    properties:
                      requests_per_second:
                        type: integer
                      max_concurrent_jobs:
                        type: integer
                      max_file_size_mb:
                        type: integer
                    required:
                    - requests_per_second
                    - max_concurrent_jobs
                    - max_file_size_mb
                required:
                - user
                - account
                - api_limits
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/accounts":
    get:
      summary: List accessible accounts
      tags:
      - Account
      description: Retrieve all accounts the authenticated user has access to
      operationId: listAccounts
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Accounts retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        role:
                          type: string
                          enum:
                          - owner
                          - admin
                          - member
                        current:
                          type: boolean
                          description: Whether this is the currently active account
                        created_at:
                          type: string
                          format: date-time
                      required:
                      - id
                      - name
                      - role
                      - current
                      - created_at
                required:
                - accounts
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/health":
    get:
      summary: API health check
      tags:
      - System
      description: Check API health and status
      operationId: healthCheck
      security: []
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  version:
                    type: string
                    example: v1.0.0
                  timestamp:
                    type: string
                    format: date-time
                  services:
                    type: object
                    properties:
                      database:
                        type: string
                        enum:
                        - ok
                        - degraded
                        - down
                      workers:
                        type: string
                        enum:
                        - ok
                        - degraded
                        - down
                      billing:
                        type: string
                        enum:
                        - ok
                        - degraded
                        - down
                    required:
                    - database
                    - workers
                    - billing
                required:
                - status
                - version
                - timestamp
                - services
        '503':
          description: API is unhealthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: error
                  version:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  services:
                    type: object
                    additionalProperties:
                      type: string
                  errors:
                    type: array
                    items:
                      type: string
                required:
                - status
                - version
                - timestamp
                - services
  "/api/v1/formats":
    get:
      summary: Get supported formats
      tags:
      - System
      description: Retrieve list of supported input and output formats
      operationId: getSupportedFormats
      security: []
      responses:
        '200':
          description: Supported formats retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  input_formats:
                    type: object
                    properties:
                      video:
                        type: array
                        items:
                          type: string
                        example:
                        - mp4
                        - avi
                        - mov
                        - mkv
                        - webm
                        - flv
                        - wmv
                      image:
                        type: array
                        items:
                          type: string
                        example:
                        - jpeg
                        - jpg
                        - png
                        - gif
                        - bmp
                        - tiff
                        - heic
                        - webp
                      audio:
                        type: array
                        items:
                          type: string
                        example:
                        - mp3
                        - wav
                        - aac
                        - flac
                        - ogg
                        - m4a
                    required:
                    - video
                    - image
                    - audio
                  output_formats:
                    type: object
                    properties:
                      video:
                        type: array
                        items:
                          type: string
                        example:
                        - mp4
                        - webm
                        - avi
                      image:
                        type: array
                        items:
                          type: string
                        example:
                        - jpeg
                        - png
                        - webp
                        - gif
                      audio:
                        type: array
                        items:
                          type: string
                        example:
                        - mp3
                        - aac
                        - wav
                        - ogg
                    required:
                    - video
                    - image
                    - audio
                  codecs:
                    type: object
                    properties:
                      video:
                        type: object
                        properties:
                          h264:
                            type: object
                            properties:
                              hw_accel:
                                type: boolean
                          h265:
                            type: object
                            properties:
                              hw_accel:
                                type: boolean
                          vp9:
                            type: object
                            properties:
                              hw_accel:
                                type: boolean
                          av1:
                            type: object
                            properties:
                              hw_accel:
                                type: boolean
                      audio:
                        type: object
                        properties:
                          aac:
                            type: object
                          mp3:
                            type: object
                          opus:
                            type: object
                required:
                - input_formats
                - output_formats
                - codecs
  "/api/v1/pricing":
    get:
      summary: Get current pricing information
      tags:
      - System
      description: Retrieve current pricing rates and tiers
      operationId: getPricing
      security: []
      responses:
        '200':
          description: Pricing information retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  base_rates:
                    type: object
                    properties:
                      video_conversion_cents_per_mb:
                        type: number
                        example: 0.3
                      image_conversion_cents_per_mb:
                        type: number
                        example: 0.1
                      thumbnail_only_cents_per_mb:
                        type: number
                        example: 0.05
                    required:
                    - video_conversion_cents_per_mb
                    - image_conversion_cents_per_mb
                    - thumbnail_only_cents_per_mb
                  tiers:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: starter
                        monthly_mb_included:
                          type: integer
                          example: 1000
                        rate_discount_percent:
                          type: number
                          example: 0
                        requests_per_second:
                          type: integer
                          example: 10
                        max_concurrent_jobs:
                          type: integer
                          example: 5
                      required:
                      - name
                      - monthly_mb_included
                      - rate_discount_percent
                      - requests_per_second
                      - max_concurrent_jobs
                  volume_discounts:
                    type: array
                    items:
                      type: object
                      properties:
                        min_mb_monthly:
                          type: integer
                        discount_percent:
                          type: number
                required:
                - base_rates
                - tiers
                - volume_discounts
  "/api/v1/capabilities":
    get:
      summary: Get API capabilities and service information
      tags:
      - System & Discovery
      description: Discover API capabilities, supported formats, limitations, and
        business context for LLM agents and developers
      operationId: getApiCapabilities
      security: []
      responses:
        '200':
          description: API capabilities retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  "@context":
                    type: string
                    example: https://schema.org/
                    description: JSON-LD context for semantic understanding
                  "@type":
                    type: string
                    example: SoftwareApplication
                    description: Schema.org type for AI agents
                  name:
                    type: string
                    example: MediaConvert.io API
                    description: Service name
                  version:
                    type: string
                    example: '1.0'
                    description: API version
                  description:
                    type: string
                    example: High-performance, cost-effective media conversion API
                      with Intel acceleration
                    description: Service description for AI understanding
                  capabilities:
                    type: object
                    properties:
                      input_formats:
                        type: object
                        properties:
                          video:
                            type: array
                            items:
                              type: string
                            example:
                            - mp4
                            - avi
                            - mov
                            - mkv
                            - webm
                            - flv
                            - wmv
                          image:
                            type: array
                            items:
                              type: string
                            example:
                            - jpeg
                            - png
                            - gif
                            - webp
                            - tiff
                            - bmp
                          audio:
                            type: array
                            items:
                              type: string
                            example:
                            - mp3
                            - aac
                            - wav
                            - flac
                            - ogg
                      output_formats:
                        type: object
                        properties:
                          video:
                            type: array
                            items:
                              type: string
                            example:
                            - mp4
                            - webm
                            - avi
                          image:
                            type: array
                            items:
                              type: string
                            example:
                            - jpeg
                            - png
                            - webp
                          audio:
                            type: array
                            items:
                              type: string
                            example:
                            - mp3
                            - aac
                            - wav
                      operations:
                        type: object
                        properties:
                          format_conversion:
                            type: object
                            properties:
                              description:
                                type: string
                                example: Convert media between formats with quality
                                  control
                              use_cases:
                                type: array
                                items:
                                  type: string
                                example:
                                - web streaming
                                - mobile optimization
                                - archival storage
                              performance:
                                type: string
                                example: 1-3x real-time with Intel acceleration
                              quality_levels:
                                type: array
                                items:
                                  type: string
                                example:
                                - low
                                - medium
                                - high
                                - lossless
                          thumbnail_generation:
                            type: object
                            properties:
                              description:
                                type: string
                                example: Extract representative frames from video
                              max_thumbnails:
                                type: integer
                                example: 20
                              strategies:
                                type: array
                                items:
                                  type: string
                                example:
                                - even_distribution
                                - scene_detection
                                - custom_timestamps
                          multi_output:
                            type: object
                            properties:
                              description:
                                type: string
                                example: Generate multiple outputs in single request
                              combinations:
                                type: array
                                items:
                                  type: string
                                example:
                                - video + thumbnails
                                - multiple resolutions
                                - different formats
                      limitations:
                        type: object
                        properties:
                          max_file_size_gb:
                            type: integer
                            example: 5
                          max_duration_hours:
                            type: integer
                            example: 6
                          supported_regions:
                            type: array
                            items:
                              type: string
                            example:
                            - EU
                            - US
                          concurrent_jobs_per_account:
                            type: integer
                            example: 10
                          no_live_streaming:
                            type: boolean
                            example: true
                          no_advanced_editing:
                            type: boolean
                            example: true
                      pricing:
                        type: object
                        properties:
                          "@type":
                            type: string
                            example: PayPerUse
                          unit:
                            type: string
                            example: MB processed (input + outputs)
                          rate_range:
                            type: string
                            example: "€0.001-0.003 per MB"
                          cost_factors:
                            type: array
                            items:
                              type: string
                            example:
                            - file_size
                            - output_count
                            - quality_settings
                            - processing_complexity
                          typical_savings_vs_competitors:
                            type: string
                            example: 50-70% cheaper than AWS MediaConvert
                  api_features:
                    type: object
                    properties:
                      authentication:
                        type: object
                        properties:
                          methods:
                            type: array
                            items:
                              type: string
                            example:
                            - Bearer token
                            - API keys
                          account_based:
                            type: boolean
                            example: true
                          rate_limiting:
                            type: boolean
                            example: true
                      real_time_features:
                        type: object
                        properties:
                          progress_tracking:
                            type: boolean
                            example: true
                          websocket_updates:
                            type: boolean
                            example: true
                          webhooks:
                            type: boolean
                            example: true
                      developer_experience:
                        type: object
                        properties:
                          openapi_spec:
                            type: boolean
                            example: true
                          interactive_docs:
                            type: boolean
                            example: true
                          sdks_available:
                            type: array
                            items:
                              type: string
                            example:
                            - Ruby
                            - JavaScript (planned)
                            - Python (planned)
                          sandbox_environment:
                            type: boolean
                            example: true
                  competitive_advantages:
                    type: array
                    items:
                      type: string
                    example:
                    - Infrastructure-aware processing with automatic hardware detection
                    - Volume-based pricing instead of time-based
                    - Multi-output jobs (video + thumbnails in single request)
                    - LLM-native API design with semantic metadata
                    - Self-describing capabilities for AI agent integration
                required:
                - "@context"
                - "@type"
                - name
                - version
                - capabilities
  "/api/v1/conversion_jobs":
    post:
      summary: Create a conversion job
      tags:
      - Conversion Jobs
      description: Job created successfully but with warnings about non-secure protocols
      operationId: createConversionJob
      security:
      - BearerAuth: []
      parameters: []
      responses:
        '201':
          description: Job created with validation warnings
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ConversionJob"
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '422':
          description: Validation errors
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                job_type:
                  type: string
                  enum:
                  - video
                  - image
                  - thumbnail
                  - document
                  description: |-
                    Type of conversion to perform:
                    - "video": Convert video files between formats
                    - "image": Convert image files between formats
                    - "thumbnail": Generate thumbnails from videos or images
                    - "document": Convert document formats
                  example: video
                input_url:
                  type: string
                  format: uri
                  description: URL to the input media file. Supports HTTP, HTTPS,
                    FTP, FTPS, S3, and cloud storage URLs
                  examples:
                  - https://my-bucket.s3.amazonaws.com/input.mp4?signature=abc123
                  - http://cdn.example.com/video.mp4
                  - ftp://files.example.com/media/video.avi
                  - https://storage.googleapis.com/bucket/file.mov
                  - https://myaccount.blob.core.windows.net/container/video.mp4
                output_url:
                  type: string
                  format: uri
                  description: URL where the converted file should be saved. Required
                    for video/image jobs. Optional for thumbnail jobs (which use thumbnail_urls
                    array instead).
                  examples:
                  - https://my-bucket.s3.amazonaws.com/output.mp4?signature=def456
                  - https://storage.googleapis.com/bucket/converted.webm?upload=token
                  - https://myaccount.blob.core.windows.net/container/output.webm?sas=token
                settings:
                  type: object
                  description: Conversion settings specific to the job type
                  properties:
                    format:
                      type: string
                      description: Target output format (e.g., mp4, webp, jpeg)
                    video_options:
                      type: object
                      description: Video-specific conversion options
                      properties:
                        codec:
                          type: string
                          example: h264_qsv
                        resolution:
                          type: string
                          example: 1920x1080
                        bitrate:
                          type: string
                          example: 5000k
                        fps:
                          type: integer
                          example: 30
                    image_options:
                      type: object
                      description: Image-specific conversion options
                      properties:
                        quality:
                          type: integer
                          minimum: 1
                          maximum: 100
                        resize:
                          type: string
                          example: 800x600
                    mode:
                      type: string
                      enum:
                      - single
                      - multiple
                      - smart_scenes
                      - grid
                      description: Thumbnail generation mode (required for thumbnail
                        jobs)
                    count:
                      type: integer
                      minimum: 1
                      maximum: 20
                      description: Number of thumbnails to generate (for multiple
                        mode)
                    size:
                      type: string
                      example: 640x360
                      description: Thumbnail dimensions (WIDTHxHEIGHT)
                    timestamps:
                      type: array
                      items:
                        type: string
                        example: '00:01:30'
                      description: Specific timestamps for thumbnail extraction (HH:MM:SS
                        format)
                    timestamp:
                      type: string
                      example: '00:01:30'
                      description: Single timestamp for single mode (HH:MM:SS format
                        or percentage like "50%")
                    quality:
                      type: string
                      enum:
                      - low
                      - medium
                      - high
                      description: Thumbnail quality preset
                thumbnail_urls:
                  type: array
                  items:
                    type: string
                    format: uri
                  description: |-
                    Array of presigned S3 PUT URLs for thumbnail output (required for thumbnail jobs).

                    IMPORTANT: You must generate one presigned PUT URL for EACH thumbnail.
                    - For 5 thumbnails, provide 5 URLs
                    - Each URL must be a unique S3 presigned PUT URL
                    - The array length must match settings.count
                    - URLs expire (typically 1 hour), ensure sufficient time for processing

                    Example: ["https://bucket.s3.amazonaws.com/thumb_0.jpg?X-Amz-Signature=...", ...]

                    See documentation: https://mediaconvert.io/docs/guides/thumbnail-generation
                webhook_url:
                  type: string
                  format: uri
                  description: URL to receive webhook notifications about job progress
                    and completion
              required:
              - job_type
              - input_url
              - settings
              description: 'Note: output_url is also required for video/image jobs,
                but optional for thumbnail jobs'
    get:
      summary: List conversion jobs
      tags:
      - Conversion Jobs
      description: Retrieve a list of conversion jobs for the authenticated account
      operationId: listConversionJobs
      security:
      - BearerAuth: []
      parameters:
      - name: status
        in: query
        required: false
        description: "Filter by job status:\n * `pending` \n * `processing` \n * `completed`
          \n * `failed` \n * `cancelled` \n "
        enum:
        - pending
        - processing
        - completed
        - failed
        - cancelled
        schema:
          type: string
      - name: job_type
        in: query
        required: false
        description: Filter by job type
        enum:
        - video_conversion
        - image_conversion
        - thumbnail_only
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: 'Maximum number of jobs to return (default: 50, max: 100)'
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        description: Number of jobs to skip for pagination
        schema:
          type: integer
      responses:
        '200':
          description: Jobs retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items:
                      "$ref": "#/components/schemas/ConversionJob"
                  total_count:
                    type: integer
                    description: Total number of jobs matching the criteria
                  has_more:
                    type: boolean
                    description: Whether there are more jobs available
                required:
                - jobs
                - total_count
                - has_more
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/conversion_jobs/{id}":
    parameters:
    - name: id
      in: path
      description: Conversion job ID
      required: true
      schema:
        type: string
    get:
      summary: Get conversion job details
      tags:
      - Conversion Jobs
      description: Retrieve details of a specific conversion job
      operationId: getConversionJob
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Job details retrieved successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ConversionJob"
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
    delete:
      summary: Cancel conversion job
      tags:
      - Conversion Jobs
      description: Cancel a pending or processing conversion job
      operationId: cancelConversionJob
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Job cancelled successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ConversionJob"
        '400':
          description: Cannot cancel job in current state
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/conversion_jobs/{id}/progress":
    parameters:
    - name: id
      in: path
      description: Conversion job ID
      required: true
      schema:
        type: string
    post:
      summary: Update job progress (internal use)
      tags:
      - Internal
      description: Internal endpoint for workers to report progress updates
      operationId: updateJobProgress
      security: []
      parameters: []
      responses:
        '200':
          description: Progress updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: updated
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                progress:
                  type: object
                  properties:
                    stage:
                      type: string
                      enum:
                      - downloading
                      - processing
                      - uploading
                      - completed
                      description: Current processing stage
                    percentage:
                      type: integer
                      minimum: 0
                      maximum: 100
                      description: Progress percentage for current stage
                    message:
                      type: string
                      description: Human-readable progress message
                    bytes_processed:
                      type: integer
                      description: Bytes processed so far
                    estimated_completion:
                      type: string
                      format: date-time
                      description: Estimated completion time
                  required:
                  - stage
                  - percentage
                worker_id:
                  type: string
                  description: ID of the worker reporting progress
              required:
              - progress
  "/api/v1/formats/supported":
    get:
      summary: Get supported input and output formats
      tags:
      - Format Management
      description: Retrieve comprehensive list of supported formats based on S3Tube
        format configuration
      operationId: getSupportedFormats
      security: []
      parameters:
      - name: category
        in: query
        required: false
        description: "Filter by media category:\n * `video` \n * `audio` \n * `image`
          \n * `document` \n * `archive` \n * `disk_image` \n "
        enum:
        - video
        - audio
        - image
        - document
        - archive
        - disk_image
        schema:
          type: string
      responses:
        '200':
          description: Supported formats retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  input_formats:
                    type: object
                    properties:
                      video:
                        type: object
                        properties:
                          compatible:
                            type: array
                            items:
                              type: object
                              properties:
                                format:
                                  type: string
                                  example: mp4
                                mime_type:
                                  type: string
                                  example: video/mp4
                                html5_compatible:
                                  type: boolean
                                browser_supported:
                                  type: boolean
                                needs_conversion:
                                  type: boolean
                                  example: false
                          needs_conversion:
                            type: array
                            items:
                              type: object
                              properties:
                                format:
                                  type: string
                                  example: avi
                                mime_type:
                                  type: string
                                  example: video/x-msvideo
                                convert_to:
                                  type: string
                                  example: mp4
                                html5_compatible:
                                  type: boolean
                                  example: false
                                needs_conversion:
                                  type: boolean
                                  example: true
                      audio:
                        type: object
                        properties:
                          compatible:
                            type: array
                            items:
                              type: object
                          needs_conversion:
                            type: array
                            items:
                              type: object
                      image:
                        type: object
                        properties:
                          browser_supported:
                            type: array
                            items:
                              type: object
                          needs_conversion:
                            type: array
                            items:
                              type: object
                  output_formats:
                    type: object
                    properties:
                      video:
                        type: array
                        items:
                          type: string
                        example:
                        - mp4
                        - webm
                        - avi
                      audio:
                        type: array
                        items:
                          type: string
                        example:
                        - mp3
                        - aac
                        - ogg
                      image:
                        type: array
                        items:
                          type: string
                        example:
                        - jpeg
                        - png
                        - webp
                        - gif
                  conversion_rules:
                    type: object
                    description: Default conversion targets for each input format
                    additionalProperties:
                      type: string
                  metadata:
                    type: object
                    properties:
                      total_input_formats:
                        type: integer
                      total_output_formats:
                        type: integer
                      categories_supported:
                        type: array
                        items:
                          type: string
                required:
                - input_formats
                - output_formats
                - conversion_rules
                - metadata
  "/api/v1/formats/detect":
    post:
      summary: Detect format from file URL or content
      tags:
      - Format Management
      description: Automatically detect media format from presigned URL or file metadata
      operationId: detectFormat
      security:
      - BearerAuth: []
      parameters: []
      responses:
        '200':
          description: Format detected successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  detected_format:
                    type: object
                    properties:
                      format:
                        type: string
                        example: avi
                      category:
                        type: string
                        example: video
                      mime_type:
                        type: string
                        example: video/x-msvideo
                      file_extension:
                        type: string
                        example: ".avi"
                      needs_conversion:
                        type: boolean
                      recommended_output:
                        type: string
                        example: mp4
                      html5_compatible:
                        type: boolean
                        example: false
                      browser_supported:
                        type: boolean
                        example: false
                    required:
                    - format
                    - category
                    - mime_type
                    - needs_conversion
                  file_metadata:
                    type: object
                    properties:
                      size_bytes:
                        type: integer
                      estimated_duration:
                        type: number
                        nullable: true
                      resolution:
                        type: string
                        nullable: true
                      codec_info:
                        type: object
                        properties:
                          video_codec:
                            type: string
                            nullable: true
                          audio_codec:
                            type: string
                            nullable: true
                  conversion_recommendations:
                    type: object
                    properties:
                      suggested_outputs:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              example: video
                            format:
                              type: string
                              example: mp4
                            reason:
                              type: string
                              example: HTML5 compatible, widely supported
                            estimated_size_reduction:
                              type: number
                              example: 0.4
                      include_thumbnails:
                        type: boolean
                      recommended_quality:
                        type: string
                        enum:
                        - low
                        - medium
                        - high
                        - lossless
                  detection_method:
                    type: string
                    enum:
                    - extension
                    - mime_type
                    - header_analysis
                    - deep_scan
                    description: Method used for detection
                required:
                - detected_format
                - conversion_recommendations
                - detection_method
        '422':
          description: Unable to detect format
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '400':
          description: Invalid URL or inaccessible file
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                  description: Presigned S3 URL of the file to analyze
                filename:
                  type: string
                  description: Original filename (used for extension-based detection)
                  example: vacation_video.avi
                content_type:
                  type: string
                  description: MIME type hint from upload
                  example: video/x-msvideo
                perform_deep_scan:
                  type: boolean
                  description: Whether to download file headers for detailed analysis
                  default: false
              required:
              - url
  "/api/v1/formats/validate":
    post:
      summary: Validate conversion request format compatibility
      tags:
      - Format Management
      description: Validate that input/output format combination is supported
      operationId: validateFormatCombination
      security:
      - BearerAuth: []
      parameters: []
      responses:
        '200':
          description: Validation completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                  input_analysis:
                    type: object
                    properties:
                      format:
                        type: string
                      supported:
                        type: boolean
                      category:
                        type: string
                      needs_conversion:
                        type: boolean
                  output_analysis:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                        format:
                          type: string
                        supported:
                          type: boolean
                        compatible_with_input:
                          type: boolean
                        warnings:
                          type: array
                          items:
                            type: string
                  recommendations:
                    type: object
                    properties:
                      alternative_outputs:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                            format:
                              type: string
                            reason:
                              type: string
                      optimization_suggestions:
                        type: array
                        items:
                          type: string
                required:
                - valid
                - input_analysis
                - output_analysis
        '400':
          description: Invalid format specification
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                input_format:
                  type: string
                  example: avi
                outputs:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        example: video
                      format:
                        type: string
                        example: mp4
              required:
              - input_format
              - outputs
  "/api/v1/formats/recommendations":
    post:
      summary: Get conversion recommendations
      tags:
      - Format Management
      description: Get intelligent recommendations for optimal conversion settings
      operationId: getConversionRecommendations
      security:
      - BearerAuth: []
      parameters: []
      responses:
        '200':
          description: Recommendations generated
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                input_format:
                  type: string
                use_case:
                  type: string
                  enum:
                  - web_streaming
                  - mobile_playback
                  - archive
                  - social_media
                  - broadcast
                  description: Intended use case for optimized recommendations
                target_device:
                  type: string
                  enum:
                  - desktop
                  - mobile
                  - tv
                  - any
                  default: any
                quality_priority:
                  type: string
                  enum:
                  - size
                  - quality
                  - speed
                  - balanced
                  default: balanced
                bandwidth_constraint:
                  type: string
                  enum:
                  - low
                  - medium
                  - high
                  - unlimited
                  default: medium
              required:
              - input_format
              - use_case
  "/api/v1/usage":
    get:
      summary: Get account usage statistics
      tags:
      - Usage & Billing
      description: Retrieve usage statistics for the authenticated account
      operationId: getUsageStats
      security:
      - BearerAuth: []
      parameters:
      - name: period
        in: query
        required: false
        description: "Time period for usage stats:\n * `current_month` \n * `last_month`
          \n * `last_7_days` \n * `last_30_days` \n * `all_time` \n "
        enum:
        - current_month
        - last_month
        - last_7_days
        - last_30_days
        - all_time
        schema:
          type: string
      - name: start_date
        in: query
        format: date
        required: false
        description: Start date for custom period (YYYY-MM-DD)
        schema:
          type: string
      - name: end_date
        in: query
        format: date
        required: false
        description: End date for custom period (YYYY-MM-DD)
        schema:
          type: string
      responses:
        '200':
          description: Usage statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  current_period:
                    type: object
                    properties:
                      period_name:
                        type: string
                        example: current_month
                      start_date:
                        type: string
                        format: date
                      end_date:
                        type: string
                        format: date
                      total_jobs:
                        type: integer
                        description: Total number of jobs processed
                      total_mb_processed:
                        type: number
                        description: Total MB processed (input + output)
                      total_cost_cents:
                        type: integer
                        description: Total cost in cents
                      jobs_by_type:
                        type: object
                        properties:
                          video_conversion:
                            type: integer
                          image_conversion:
                            type: integer
                          thumbnail_only:
                            type: integer
                      jobs_by_status:
                        type: object
                        properties:
                          completed:
                            type: integer
                          failed:
                            type: integer
                          cancelled:
                            type: integer
                    required:
                    - period_name
                    - start_date
                    - end_date
                    - total_jobs
                    - total_mb_processed
                    - total_cost_cents
                  daily_breakdown:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          format: date
                        jobs_count:
                          type: integer
                        mb_processed:
                          type: number
                        cost_cents:
                          type: integer
                  rate_info:
                    type: object
                    properties:
                      current_rate_per_mb_cents:
                        type: number
                        description: Current pricing rate per MB
                      account_tier:
                        type: string
                        example: growth
                      volume_discount:
                        type: number
                        description: Volume discount percentage (0-100)
                required:
                - current_period
                - daily_breakdown
                - rate_info
        '400':
          description: Invalid date parameters
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/usage/records":
    get:
      summary: Get detailed usage records
      tags:
      - Usage & Billing
      description: Retrieve detailed usage records for billing and analytics
      operationId: getUsageRecords
      security:
      - BearerAuth: []
      parameters:
      - name: limit
        in: query
        required: false
        description: 'Maximum number of records to return (default: 50, max: 1000)'
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        description: Number of records to skip for pagination
        schema:
          type: integer
      - name: job_type
        in: query
        required: false
        description: "Filter by job type:\n * `video_conversion` \n * `image_conversion`
          \n * `thumbnail_only` \n "
        enum:
        - video_conversion
        - image_conversion
        - thumbnail_only
        schema:
          type: string
      - name: start_date
        in: query
        format: date
        required: false
        description: Start date for filtering records
        schema:
          type: string
      - name: end_date
        in: query
        format: date
        required: false
        description: End date for filtering records
        schema:
          type: string
      responses:
        '200':
          description: Usage records retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  records:
                    type: array
                    items:
                      "$ref": "#/components/schemas/UsageRecord"
                  total_count:
                    type: integer
                  has_more:
                    type: boolean
                  summary:
                    type: object
                    properties:
                      total_mb_processed:
                        type: number
                      total_cost_cents:
                        type: integer
                      average_cost_per_mb_cents:
                        type: number
                required:
                - records
                - total_count
                - has_more
                - summary
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/account/credits":
    get:
      summary: Get account credit balance
      tags:
      - Usage & Billing
      description: Retrieve current credit balance and recent transactions
      operationId: getCreditBalance
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Credit balance retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  current_balance_cents:
                    type: integer
                    description: Current credit balance in cents
                  estimated_mb_remaining:
                    type: number
                    description: Estimated MB that can be processed with current balance
                  auto_refill:
                    type: object
                    properties:
                      enabled:
                        type: boolean
                      threshold_cents:
                        type: integer
                        description: Balance threshold to trigger refill
                      amount_cents:
                        type: integer
                        description: Amount to add when refilling
                      payment_method_id:
                        type: string
                        description: Stripe payment method ID
                    required:
                    - enabled
                  recent_transactions:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        transaction_type:
                          type: string
                          enum:
                          - purchase
                          - usage
                          - refund
                          - bonus
                          - auto_refill
                        amount_cents:
                          type: integer
                        mb_processed:
                          type: number
                          nullable: true
                        description:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                      required:
                      - id
                      - transaction_type
                      - amount_cents
                      - created_at
                required:
                - current_balance_cents
                - estimated_mb_remaining
                - auto_refill
                - recent_transactions
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
    post:
      summary: Purchase credits
      tags:
      - Usage & Billing
      description: Purchase additional credits for the account
      operationId: purchaseCredits
      security:
      - BearerAuth: []
      parameters: []
      responses:
        '201':
          description: Credits purchased successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  transaction_id:
                    type: string
                  amount_purchased_cents:
                    type: integer
                  new_balance_cents:
                    type: integer
                  estimated_mb_added:
                    type: number
                  stripe_payment_intent_id:
                    type: string
                required:
                - transaction_id
                - amount_purchased_cents
                - new_balance_cents
        '400':
          description: Invalid purchase parameters
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '402':
          description: Payment failed
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount_cents:
                  type: integer
                  minimum: 500
                  description: Amount to purchase in cents (minimum $5.00)
                payment_method_id:
                  type: string
                  description: Stripe payment method ID (optional if default payment
                    method exists)
                save_payment_method:
                  type: boolean
                  description: Whether to save the payment method for future use
                  default: false
              required:
              - amount_cents
  "/api/v1/account/credits/auto_refill":
    put:
      summary: Configure auto-refill settings
      tags:
      - Usage & Billing
      description: Configure automatic credit refill when balance gets low
      operationId: configureAutoRefill
      security:
      - BearerAuth: []
      parameters: []
      responses:
        '200':
          description: Auto-refill configured successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  auto_refill:
                    type: object
                    properties:
                      enabled:
                        type: boolean
                      threshold_cents:
                        type: integer
                      amount_cents:
                        type: integer
                      payment_method_id:
                        type: string
                  message:
                    type: string
                required:
                - auto_refill
                - message
        '400':
          description: Invalid configuration
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
                  description: Whether to enable auto-refill
                threshold_cents:
                  type: integer
                  minimum: 100
                  description: Balance threshold to trigger refill (minimum $1.00)
                amount_cents:
                  type: integer
                  minimum: 500
                  description: Amount to add when refilling (minimum $5.00)
                payment_method_id:
                  type: string
                  description: Stripe payment method ID to use for auto-refill
              required:
              - enabled
  "/api/v1/webhooks":
    post:
      summary: Register a webhook endpoint
      tags:
      - Webhooks
      description: Register a webhook endpoint to receive notifications about job
        events
      operationId: createWebhook
      security:
      - BearerAuth: []
      parameters: []
      responses:
        '201':
          description: Webhook created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Webhook ID
                  url:
                    type: string
                    format: uri
                  events:
                    type: array
                    items:
                      type: string
                  secret_key:
                    type: string
                    description: Generated secret key for signature verification
                  active:
                    type: boolean
                  created_at:
                    type: string
                    format: date-time
                  last_delivered_at:
                    type: string
                    format: date-time
                    nullable: true
                  failure_count:
                    type: integer
                  description:
                    type: string
                    nullable: true
                required:
                - id
                - url
                - events
                - secret_key
                - active
                - created_at
                - failure_count
        '400':
          description: Invalid webhook configuration
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '422':
          description: Validation errors
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                  description: The URL that will receive webhook notifications
                events:
                  type: array
                  items:
                    type: string
                    enum:
                    - job.created
                    - job.started
                    - job.progress
                    - job.completed
                    - job.failed
                    - job.cancelled
                    - account.low_credits
                    - account.credits_purchased
                  description: Array of events to subscribe to
                secret:
                  type: string
                  description: Optional secret for webhook signature verification
                description:
                  type: string
                  description: Optional description for the webhook
              required:
              - url
              - events
    get:
      summary: List webhooks
      tags:
      - Webhooks
      description: Retrieve all webhook endpoints for the authenticated account
      operationId: listWebhooks
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Webhooks retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        url:
                          type: string
                          format: uri
                        events:
                          type: array
                          items:
                            type: string
                        active:
                          type: boolean
                        created_at:
                          type: string
                          format: date-time
                        last_delivered_at:
                          type: string
                          format: date-time
                          nullable: true
                        failure_count:
                          type: integer
                        description:
                          type: string
                          nullable: true
                      required:
                      - id
                      - url
                      - events
                      - active
                      - created_at
                      - failure_count
                required:
                - webhooks
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/webhooks/{id}":
    parameters:
    - name: id
      in: path
      description: Webhook ID
      required: true
      schema:
        type: string
    get:
      summary: Get webhook details
      tags:
      - Webhooks
      description: Retrieve details of a specific webhook
      operationId: getWebhook
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Webhook details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  url:
                    type: string
                    format: uri
                  events:
                    type: array
                    items:
                      type: string
                  secret_key:
                    type: string
                    description: Secret key for signature verification
                  active:
                    type: boolean
                  created_at:
                    type: string
                    format: date-time
                  last_delivered_at:
                    type: string
                    format: date-time
                    nullable: true
                  failure_count:
                    type: integer
                  last_failure_reason:
                    type: string
                    nullable: true
                  description:
                    type: string
                    nullable: true
                  delivery_history:
                    type: array
                    items:
                      type: object
                      properties:
                        event_type:
                          type: string
                        delivered_at:
                          type: string
                          format: date-time
                        status_code:
                          type: integer
                        response_time_ms:
                          type: integer
                        success:
                          type: boolean
                required:
                - id
                - url
                - events
                - secret_key
                - active
                - created_at
                - failure_count
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
    put:
      summary: Update webhook
      tags:
      - Webhooks
      description: Update an existing webhook configuration
      operationId: updateWebhook
      security:
      - BearerAuth: []
      parameters: []
      responses:
        '200':
          description: Webhook updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  url:
                    type: string
                    format: uri
                  events:
                    type: array
                    items:
                      type: string
                  active:
                    type: boolean
                  updated_at:
                    type: string
                    format: date-time
                  description:
                    type: string
                    nullable: true
                required:
                - id
                - url
                - events
                - active
                - updated_at
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  items:
                    type: string
                    enum:
                    - job.created
                    - job.started
                    - job.progress
                    - job.completed
                    - job.failed
                    - job.cancelled
                    - account.low_credits
                    - account.credits_purchased
                active:
                  type: boolean
                description:
                  type: string
    delete:
      summary: Delete webhook
      tags:
      - Webhooks
      description: Delete a webhook endpoint
      operationId: deleteWebhook
      security:
      - BearerAuth: []
      responses:
        '204':
          description: Webhook deleted successfully
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/webhooks/{id}/test":
    parameters:
    - name: id
      in: path
      description: Webhook ID
      required: true
      schema:
        type: string
    post:
      summary: Test webhook delivery
      tags:
      - Webhooks
      description: Send a test event to verify webhook endpoint is working
      operationId: testWebhook
      security:
      - BearerAuth: []
      parameters: []
      responses:
        '200':
          description: Test webhook sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  test_id:
                    type: string
                  event_type:
                    type: string
                  sent_at:
                    type: string
                    format: date-time
                  delivery_result:
                    type: object
                    properties:
                      status_code:
                        type: integer
                      response_time_ms:
                        type: integer
                      success:
                        type: boolean
                      error_message:
                        type: string
                        nullable: true
                    required:
                    - status_code
                    - response_time_ms
                    - success
                required:
                - test_id
                - event_type
                - sent_at
                - delivery_result
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                event_type:
                  type: string
                  enum:
                  - job.completed
                  - job.failed
                  - account.low_credits
                  description: Type of test event to send
                  default: job.completed
  "/api/v1/workflows":
    get:
      summary: Get common workflows and usage patterns
      tags:
      - System & Discovery
      description: Discover common usage patterns, workflows, and best practices for
        efficient API usage
      operationId: getCommonWorkflows
      security: []
      parameters:
      - name: use_case
        in: query
        required: false
        enum:
        - web_streaming
        - mobile_optimization
        - social_media
        - archival
        - e_learning
        description: "Filter workflows by specific use case:\n * `web_streaming` \n
          * `mobile_optimization` \n * `social_media` \n * `archival` \n * `e_learning`
          \n "
        schema:
          type: string
      responses:
        '200':
          description: Common workflows retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  "@context":
                    type: string
                    example: https://schema.org/
                    description: JSON-LD context for semantic understanding
                  common_workflows:
                    type: object
                    properties:
                      thumbnail_generation_workflows:
                        type: object
                        properties:
                          "@type":
                            type: string
                            example: WorkflowPattern
                          name:
                            type: string
                            example: Efficient Thumbnail Generation
                          description:
                            type: string
                            example: Generate thumbnails without full video conversion
                              for massive cost savings
                          use_case:
                            type: string
                            example: Video previews, gallery displays, social media
                              cards, and content discovery
                          business_value:
                            type: string
                            example: 98% cost savings vs full conversion, faster processing,
                              reduced storage needs
                          cost_comparison:
                            type: object
                            properties:
                              full_video_conversion:
                                type: string
                                example: "€0.003/MB (typical €3.15 for 1GB video)"
                              thumbnail_only:
                                type: string
                                example: "€0.005 base + €0.001/100MB (typical €0.015
                                  for 1GB video)"
                              savings:
                                type: string
                                example: 98-99% cost reduction
                          workflow_patterns:
                            type: object
                            properties:
                              single_thumbnail_preview:
                                type: object
                                properties:
                                  name:
                                    type: string
                                    example: Single Thumbnail Preview
                                  description:
                                    type: string
                                    example: Generate one representative thumbnail
                                      for video preview
                                  use_cases:
                                    type: array
                                    items:
                                      type: string
                                  expected_results:
                                    type: object
                                    properties:
                                      processing_time:
                                        type: string
                                        example: 3-8 seconds
                                      cost:
                                        type: string
                                        example: "€0.005 (vs €0.315 for full conversion)"
                                      quality:
                                        type: string
                                        example: High-quality representative frame
                              smart_scene_detection:
                                type: object
                                properties:
                                  name:
                                    type: string
                                    example: AI-Powered Scene Detection
                                  description:
                                    type: string
                                    example: Intelligently select the most representative
                                      frames using scene analysis
                                  use_cases:
                                    type: array
                                    items:
                                      type: string
                          optimization_strategies:
                            type: object
                            properties:
                              cost_efficiency:
                                type: array
                                items:
                                  type: string
                              performance_optimization:
                                type: array
                                items:
                                  type: string
                              quality_best_practices:
                                type: array
                                items:
                                  type: string
                      web_video_optimization:
                        type: object
                        properties:
                          "@type":
                            type: string
                            example: WorkflowPattern
                          name:
                            type: string
                            example: Web Video Optimization
                          description:
                            type: string
                            example: Optimize video for web streaming with thumbnails
                          use_case:
                            type: string
                            example: Reduce bandwidth costs and improve loading speed
                          business_value:
                            type: string
                            example: Faster page loads, better SEO, reduced CDN costs
                          steps:
                            type: array
                            items:
                              type: string
                            example:
                            - Upload original video to your S3 bucket
                            - Generate presigned URLs for input and output locations
                            - Create conversion job with "web_streaming" use case
                            - Monitor progress via webhooks or polling
                            - Use optimized video and thumbnails in your application
                          example_request:
                            type: object
                            properties:
                              input:
                                type: object
                                properties:
                                  url:
                                    type: string
                                    example: s3://bucket/original.mov
                                  format:
                                    type: string
                                    example: auto
                              outputs:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    type:
                                      type: string
                                      example: video
                                    format:
                                      type: string
                                      example: mp4
                                    quality:
                                      type: string
                                      example: medium
                                    use_case:
                                      type: string
                                      example: web_streaming
                          expected_results:
                            type: object
                            properties:
                              file_size_reduction:
                                type: string
                                example: 40-60%
                              quality_retention:
                                type: string
                                example: 95%+
                              processing_time:
                                type: string
                                example: 1-2x real-time
                              cost_estimate:
                                type: string
                                example: "€0.002/MB"
                              bandwidth_savings:
                                type: string
                                example: "€15-30/month per 1000 video views"
                          common_mistakes:
                            type: array
                            items:
                              type: string
                            example:
                            - Using "high" quality for web streaming (unnecessary
                              bandwidth)
                            - Not generating thumbnails for video previews
                            - Converting already optimized MP4 files
                      social_media_conversion:
                        type: object
                        properties:
                          "@type":
                            type: string
                            example: WorkflowPattern
                          name:
                            type: string
                            example: Social Media Conversion
                          description:
                            type: string
                            example: Prepare videos for social media platforms
                          platform_requirements:
                            type: object
                            properties:
                              instagram_post:
                                type: object
                                properties:
                                  max_duration:
                                    type: integer
                                    example: 60
                                  aspect_ratio:
                                    type: string
                                    example: '1:1'
                                  max_size_mb:
                                    type: integer
                                    example: 100
                                  recommended_quality:
                                    type: string
                                    example: high
                              instagram_story:
                                type: object
                                properties:
                                  max_duration:
                                    type: integer
                                    example: 15
                                  aspect_ratio:
                                    type: string
                                    example: '9:16'
                                  max_size_mb:
                                    type: integer
                                    example: 30
                              twitter_video:
                                type: object
                                properties:
                                  max_duration:
                                    type: integer
                                    example: 140
                                  aspect_ratio:
                                    type: string
                                    example: '16:9'
                                  max_size_mb:
                                    type: integer
                                    example: 500
                              linkedin_video:
                                type: object
                                properties:
                                  max_duration:
                                    type: integer
                                    example: 600
                                  max_size_mb:
                                    type: integer
                                    example: 200
                      mobile_app_optimization:
                        type: object
                        properties:
                          "@type":
                            type: string
                            example: WorkflowPattern
                          name:
                            type: string
                            example: Mobile App Optimization
                          description:
                            type: string
                            example: Optimize video for mobile app playback
                          considerations:
                            type: array
                            items:
                              type: string
                            example:
                            - Smaller screen sizes allow lower resolutions
                            - Battery life considerations favor efficient codecs
                            - Variable network conditions require adaptive quality
                            - Storage space is limited on mobile devices
                          recommended_settings:
                            type: object
                            properties:
                              quality:
                                type: string
                                example: low
                              use_case:
                                type: string
                                example: mobile
                              max_resolution:
                                type: string
                                example: 720p
                              prefer_hardware_acceleration:
                                type: boolean
                                example: true
                      image_optimization:
                        type: object
                        properties:
                          "@type":
                            type: string
                            example: WorkflowPattern
                          name:
                            type: string
                            example: Web Image Optimization
                          description:
                            type: string
                            example: Optimize images for web performance
                          best_practices:
                            type: array
                            items:
                              type: string
                            example:
                            - Use WebP format for modern browsers with JPEG fallback
                            - Generate multiple sizes for responsive design
                            - Strip metadata for privacy and file size reduction
                            - Use progressive JPEG for better perceived loading
                  integration_patterns:
                    type: object
                    properties:
                      webhook_integration:
                        type: object
                        properties:
                          description:
                            type: string
                            example: Recommended pattern for production applications
                          benefits:
                            type: array
                            items:
                              type: string
                            example:
                            - No polling required
                            - Immediate notifications
                            - Reliable delivery
                          implementation_steps:
                            type: array
                            items:
                              type: string
                            example:
                            - Set up webhook endpoint in your application
                            - Register webhook URL via API
                            - Verify webhook signatures for security
                            - Handle webhook events and update your database
                      polling_integration:
                        type: object
                        properties:
                          description:
                            type: string
                            example: Simple pattern for development and testing
                          recommended_interval:
                            type: string
                            example: 5-10 seconds
                          stop_conditions:
                            type: array
                            items:
                              type: string
                            example:
                            - Job status is "completed"
                            - Job status is "failed"
                            - Timeout reached
                  cost_optimization_tips:
                    type: array
                    items:
                      type: string
                    example:
                    - Use thumbnail-only endpoints for previews (98% cost savings
                      vs full conversion)
                    - Use appropriate quality settings - "medium" is sufficient for
                      most web content
                    - Avoid converting already optimized files
                    - Batch similar conversions when possible
                    - Consider input file size when estimating costs
                    - Use smart scene detection instead of manual timestamp selection
                    - Generate thumbnails during upload workflow for better UX
                  performance_tips:
                    type: array
                    items:
                      type: string
                    example:
                    - Use webhooks instead of polling for better responsiveness
                    - Upload files to same region as processing workers
                    - Optimize S3 presigned URL expiration times
                    - Monitor queue depth during peak usage
                    - Consider file size and format for processing time estimates
                    - Cache thumbnail URLs and use CDN for delivery
                    - Generate thumbnails during upload process for immediate availability
                required:
                - "@context"
                - common_workflows
                - integration_patterns
servers:
- url: https://mediaconvert.io/api
  description: Production API
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: API token authentication. Get your token from the dashboard.
  schemas:
    ApiCapabilities:
      type: object
      description: Comprehensive API capabilities and service information for LLM
        agents
      properties:
        "@context":
          type: string
          example: https://schema.org/
        "@type":
          type: string
          example: SoftwareApplication
        name:
          type: string
          example: MediaConvert.io API
        version:
          type: string
          example: '1.0'
        capabilities:
          type: object
          properties:
            input_formats:
              type: object
            output_formats:
              type: object
            operations:
              type: object
            limitations:
              type: object
            pricing:
              type: object
      required:
      - "@context"
      - "@type"
      - name
      - version
      - capabilities
    WorkflowGuide:
      type: object
      description: Common workflows and integration patterns for developers and AI
        agents
      properties:
        "@context":
          type: string
          example: https://schema.org/
        common_workflows:
          type: object
          description: Predefined workflows for common use cases
        integration_patterns:
          type: object
          description: Technical integration approaches
        cost_optimization_tips:
          type: array
          items:
            type: string
          description: Best practices for cost efficiency
        performance_tips:
          type: array
          items:
            type: string
          description: Best practices for optimal performance
      required:
      - "@context"
      - common_workflows
      - integration_patterns
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
        errors:
          type: object
          description: Detailed validation errors
          additionalProperties:
            type: array
            items:
              type: string
        code:
          type: string
          description: Error code for programmatic handling
      required:
      - error
    ConversionJob:
      type: object
      properties:
        id:
          type: string
          description: Unique job identifier
          example: conv_abc123def456
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          - cancelled
          description: Current job status
        input:
          type: object
          properties:
            url:
              type: string
              format: uri
            format:
              type: string
              description: Detected or specified format
            detected_mime:
              type: string
            size_bytes:
              type: integer
            metadata:
              type: object
              properties:
                duration_seconds:
                  type: number
                resolution:
                  type: string
                codec:
                  type: string
                fps:
                  type: number
          required:
          - url
          - format
        outputs:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - video
                - audio
                - image
                - thumbnails
              format:
                type: string
              url:
                type: string
                format: uri
              status:
                type: string
                enum:
                - pending
                - processing
                - completed
                - failed
              progress_percentage:
                type: integer
                minimum: 0
                maximum: 100
              size_bytes:
                type: integer
                nullable: true
              quality_preset:
                type: string
                enum:
                - low
                - medium
                - high
                - lossless
                - custom
                description: Quality preset used for this output
              use_case:
                type: string
                enum:
                - web_streaming
                - mobile
                - social_media
                - archive
                - broadcast
                description: Use case that influenced settings
              resolved_settings:
                type: object
                description: Technical settings resolved from quality preset or custom
                  advanced settings
                properties:
                  video:
                    type: object
                    properties:
                      codec:
                        type: string
                        example: h264
                      resolution:
                        type: string
                        example: 1920x1080
                      bitrate:
                        type: string
                        example: 5000k
                      fps:
                        type: integer
                        example: 30
                      prefer_hardware_acceleration:
                        type: boolean
                  audio:
                    type: object
                    properties:
                      codec:
                        type: string
                        example: aac
                      bitrate:
                        type: string
                        example: 192k
                      sample_rate:
                        type: integer
                        example: 48000
                      channels:
                        type: integer
                        example: 2
                  image:
                    type: object
                    properties:
                      quality:
                        type: integer
                        minimum: 1
                        maximum: 100
                      resize:
                        type: string
                        example: 1200x800
                      optimize:
                        type: boolean
                      strip_metadata:
                        type: boolean
                  thumbnails:
                    type: object
                    properties:
                      count:
                        type: integer
                        example: 3
                      size:
                        type: string
                        example: 320x180
                      timestamps:
                        type: array
                        items:
                          type: string
                      strategy:
                        type: string
                        example: even_distribution
              files:
                type: array
                description: For thumbnail outputs, array of generated files
                items:
                  type: object
                  properties:
                    url:
                      type: string
                    timestamp:
                      type: string
                    size_bytes:
                      type: integer
              metadata:
                type: object
                properties:
                  codec:
                    type: string
                  resolution:
                    type: string
                  bitrate:
                    type: string
                  duration_seconds:
                    type: number
            required:
            - type
            - format
            - url
            - status
        cost_breakdown:
          type: object
          properties:
            input_mb:
              type: number
            output_mb:
              type: number
            thumbnail_mb:
              type: number
            total_mb:
              type: number
            cost_cents:
              type: integer
            cost_explanation:
              type: string
              description: Human-readable cost breakdown
              example: Input 50MB + Output 30.2MB + Thumbnails 0.13MB at €0.003/MB
            vs_competitors:
              type: string
              description: Cost comparison with competitors
              example: "~70% cheaper than AWS MediaConvert"
        business_context:
          type: object
          description: Business impact and optimization metrics for LLM understanding
          properties:
            optimization_achieved:
              type: object
              properties:
                file_size_reduction:
                  type: string
                  example: 42%
                bandwidth_savings:
                  type: string
                  example: "€12.50/month for 1000 views"
                loading_speed_improvement:
                  type: string
                  example: 65% faster
                quality_retention:
                  type: string
                  example: 95%+
            cost_analysis:
              type: object
              properties:
                processing_cost_cents:
                  type: integer
                  example: 241
                vs_aws_mediaconvert:
                  type: string
                  example: 68% cheaper
                carbon_footprint_kg:
                  type: number
                  example: 0.0015
                intel_acceleration_savings:
                  type: string
                  example: 5x faster processing
            quality_metrics:
              type: object
              properties:
                visual_quality_score:
                  type: number
                  example: 0.95
                  minimum: 0
                  maximum: 1
                compression_efficiency:
                  type: string
                  example: excellent
                hardware_acceleration_used:
                  type: boolean
                  example: false
                processing_speed_ratio:
                  type: string
                  example: 2.1x real-time
        performance_metrics:
          type: object
          description: Technical performance data
          properties:
            processing_duration_seconds:
              type: number
              example: 25.4
            queue_wait_time_seconds:
              type: number
              example: 1.2
            intel_acceleration_used:
              type: boolean
              example: true
            worker_region:
              type: string
              example: eu-central-1
            throughput_mbps:
              type: number
              example: 45.2
        progress:
          type: object
          properties:
            overall_percentage:
              type: integer
              minimum: 0
              maximum: 100
            current_stage:
              type: string
            estimated_completion:
              type: string
              format: date-time
        webhook_url:
          type: string
          format: uri
          description: URL for completion webhook
          nullable: true
        created_at:
          type: string
          format: date-time
          description: Job creation timestamp
        started_at:
          type: string
          format: date-time
          description: Processing start timestamp
          nullable: true
        completed_at:
          type: string
          format: date-time
          description: Completion timestamp
          nullable: true
        error_message:
          type: string
          description: Error message if job failed
          nullable: true
      required:
      - id
      - status
      - input
      - outputs
      - created_at
    FormatInfo:
      type: object
      properties:
        format:
          type: string
          example: mp4
        category:
          type: string
          enum:
          - video
          - audio
          - image
          - document
          - archive
        mime_type:
          type: string
          example: video/mp4
        needs_conversion:
          type: boolean
        html5_compatible:
          type: boolean
        browser_supported:
          type: boolean
        recommended_output:
          type: string
          nullable: true
      required:
      - format
      - category
      - mime_type
      - needs_conversion
    UsageRecord:
      type: object
      properties:
        id:
          type: string
          description: Usage record identifier
        total_mb_processed:
          type: number
          description: Total MB processed (input + output)
        cost_cents:
          type: integer
          description: Cost for this usage in cents
        job_type:
          type: string
          description: Type of conversion
        processed_at:
          type: string
          format: date-time
          description: When the processing occurred
      required:
      - id
      - total_mb_processed
      - cost_cents
      - job_type
      - processed_at
    QualityPresets:
      type: object
      description: Available quality presets and their technical settings
      properties:
        presets:
          type: object
          properties:
            video:
              type: object
              properties:
                low:
                  type: object
                  properties:
                    description:
                      type: string
                      example: Fast encoding, mobile-friendly
                    use_cases:
                      type: array
                      items:
                        type: string
                    resolved_settings:
                      type: object
                      properties:
                        codec:
                          type: string
                          example: h264
                        resolution:
                          type: string
                          example: 720p (maintains aspect ratio)
                        bitrate:
                          type: string
                          example: 1500k
                        audio_bitrate:
                          type: string
                          example: 128k
                    estimated_file_size:
                      type: string
                      example: "~40% of original"
                    processing_speed:
                      type: string
                      example: 2-3x real-time
                medium:
                  type: object
                  properties:
                    description:
                      type: string
                      example: Balanced quality and size, web streaming
                    use_cases:
                      type: array
                      items:
                        type: string
                    resolved_settings:
                      type: object
                      properties:
                        codec:
                          type: string
                          example: h264
                        resolution:
                          type: string
                          example: 1080p (maintains aspect ratio)
                        bitrate:
                          type: string
                          example: 3500k
                        audio_bitrate:
                          type: string
                          example: 192k
                    estimated_file_size:
                      type: string
                      example: "~65% of original"
                    processing_speed:
                      type: string
                      example: 1.5-2x real-time
                high:
                  type: object
                  properties:
                    description:
                      type: string
                      example: High quality, archival use
                    resolved_settings:
                      type: object
                lossless:
                  type: object
                  properties:
                    description:
                      type: string
                      example: Maximum quality, professional use
                    resolved_settings:
                      type: object
            image:
              type: object
              properties:
                low:
                  type: object
                medium:
                  type: object
                high:
                  type: object
                lossless:
                  type: object
            thumbnails:
              type: object
              properties:
                low:
                  type: object
                medium:
                  type: object
                high:
                  type: object
        use_case_recommendations:
          type: object
          properties:
            web_streaming:
              type: object
              properties:
                recommended_quality:
                  type: string
                  example: medium
                formats:
                  type: array
                  items:
                    type: string
                description:
                  type: string
            mobile:
              type: object
            social_media:
              type: object
            archive:
              type: object
            broadcast:
              type: object
      required:
      - presets
      - use_case_recommendations
security:
- BearerAuth: []
