swagger: '2.0'
info:
  title: '@eyevinn/auto-subtitles'
  description: Transcribe Service API
  version: v1
definitions: {}
paths:
  /:
    get:
      description: healthcheck
      responses:
        '200':
          description: The magical words!
          schema:
            description: The magical words!
            type: string
  /health:
    get:
      description: Detailed health check with worker status
      responses:
        '200':
          description: Service health and worker status
          schema:
            type: object
            properties:
              status:
                type: string
              title:
                type: string
              workers:
                type: object
                properties:
                  total:
                    type: number
                  active:
                    type: number
                  idle:
                    type: number
                  inactive:
                    type: number
  /metrics:
    get:
      description: Prometheus-compatible metrics endpoint
      responses:
        '200':
          description: Prometheus text exposition format
          schema:
            type: string
  /transcribe:
    post:
      description: Transcribe a remote file
      parameters:
        - name: body
          in: body
          schema:
            type: object
            properties:
              url:
                type: string
              callbackUrl:
                type: string
                description: Optional callback URL to receive subtitling status
              externalId:
                type: string
                description: Optional external ID for tracking the subtitling job
              language:
                type: string
              prompt:
                type: string
                description:
                  Optional prompt to guide the transcription process. This can be
                  used to provide context or specific instructions for the
                  transcription.
              format:
                type: string
                enum:
                  - srt
                  - vtt
              model:
                type: string
                enum:
                  - whisper-1
                  - gpt-4o-transcribe
                  - gpt-4o-mini-transcribe
                  - gpt-4o-mini-transcribe-2025-12-15
                  - gpt-4o-transcribe-diarize
                description:
                  'Transcription model to use. Default: whisper-1. Note:
                  gpt-4o-transcribe-diarize supports speaker identification.'
              speakerNames:
                type: array
                items:
                  type: string
                maxItems: 4
                description:
                  Known speaker names for diarization (max 4). Only used with
                  gpt-4o-transcribe-diarize model.
            required:
              - url
      responses:
        '200':
          description: Default Response
          schema:
            type: object
            properties:
              workerId:
                type: string
              result:
                type: string
        '400':
          description: Validation Error
          schema:
            type: object
            properties:
              error:
                type: string
              code:
                type: string
        '500':
          description: Default Response
          schema:
            type: object
            properties:
              workerId:
                type: string
              error:
                type: string
  /transcribe/s3:
    post:
      description: Transcribe a remote file and upload to S3
      parameters:
        - name: body
          in: body
          schema:
            type: object
            properties:
              url:
                type: string
              callbackUrl:
                type: string
              externalId:
                type: string
                description: Optional external ID for tracking the subtitling job
              language:
                type: string
              prompt:
                type: string
                description:
                  Optional prompt to guide the transcription process. This can be
                  used to provide context or specific instructions for the
                  transcription.
              format:
                type: string
                enum:
                  - srt
                  - vtt
              model:
                type: string
                enum:
                  - whisper-1
                  - gpt-4o-transcribe
                  - gpt-4o-mini-transcribe
                  - gpt-4o-mini-transcribe-2025-12-15
                  - gpt-4o-transcribe-diarize
                description:
                  'Transcription model to use. Default: whisper-1. Note:
                  gpt-4o-transcribe-diarize supports speaker identification.'
              speakerNames:
                type: array
                items:
                  type: string
                maxItems: 4
                description:
                  Known speaker names for diarization (max 4). Only used with
                  gpt-4o-transcribe-diarize model.
              bucket:
                type: string
              key:
                type: string
              region:
                type: string
              endpoint:
                type: string
            required:
              - url
              - bucket
              - key
      responses:
        '200':
          description: Default Response
          schema:
            type: object
            properties:
              workerId:
                type: string
        '400':
          description: Validation Error
          schema:
            type: object
            properties:
              error:
                type: string
              code:
                type: string
        '500':
          description: Default Response
          schema:
            type: object
            properties:
              workerId:
                type: string
              error:
                type: string