Lingopal Jobs API

openapi: 3.1.0
info:
  title: Lingopal API v2 Jobs API
  description: Lingopal API for uploading media and documents, starting translation workflows, generating subtitles, translating text, and downloading generated artifacts.
  version: v2
servers:
- url: https://vod-api.lingopal-dev.com
security:
- APIKeyHeader: []
tags:
- name: Jobs
  description: Work with reusable registered jobs, their workflows, status, and outputs.
paths:
  /v2/jobs/{job_id}:
    get:
      tags:
      - Jobs
      summary: Get registered job
      description: Returns metadata for a reusable registered job.
      operationId: getJob
      security:
      - APIKeyHeader: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          description: Reusable registered job ID.
          title: Job Id
        description: Reusable registered job ID.
      responses:
        '200':
          description: Registered job metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              example:
                detail: Job Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/jobs/{job_id}/status:
    get:
      tags:
      - Jobs
      summary: Get registered job status
      description: Returns current processing status for a reusable registered job.
      operationId: getJobStatus
      security:
      - APIKeyHeader: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          description: Reusable registered job ID.
          title: Job Id
        description: Reusable registered job ID.
      responses:
        '200':
          description: Current job processing status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatusResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              example:
                detail: Job Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/jobs/{job_id}/translations:
    post:
      tags:
      - Jobs
      summary: Translate a registered job
      description: Starts translation for a reusable registered job. Video/audio files use the media translation workflow; document files use the document translation workflow.
      operationId: translateJob
      security:
      - APIKeyHeader: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          description: Reusable registered job ID.
          title: Job Id
        description: Reusable registered job ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranslateJobRequest'
      responses:
        '200':
          description: Started job translation workflow.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslationJobResponse'
        '401':
          description: Missing or invalid authentication token.
        '422':
          description: Request validation error.
  /v2/jobs/{job_id}/subtitles:
    post:
      tags:
      - Jobs
      summary: Generate subtitles for a registered job
      description: Starts translated subtitle generation for a reusable registered media file.
      operationId: generateJobSubtitles
      security:
      - APIKeyHeader: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          description: Reusable registered job ID.
          title: Job Id
        description: Reusable registered job ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranslateSubtitlesRequest'
      responses:
        '200':
          description: Started subtitle generation workflow.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslationJobResponse'
        '401':
          description: Missing or invalid authentication token.
        '422':
          description: Request validation error.
  /v2/jobs/{job_id}/outputs/transcript:
    get:
      tags:
      - Jobs
      summary: Download job transcript
      description: Downloads a transcript for a registered job as JSON, CSV, TSV, or plain text.
      operationId: downloadJobTranscript
      security:
      - APIKeyHeader: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          description: Reusable registered job ID.
          title: Job Id
        description: Reusable registered job ID.
      - name: locale
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          default: source
          title: Locale
      - name: layout
        in: query
        required: false
        schema:
          enum:
          - compact
          - detailed
          type: string
          default: compact
          title: Layout
      - name: file_format
        in: query
        required: false
        schema:
          enum:
          - json
          - csv
          - tsv
          - txt
          type: string
          default: txt
          title: File Format
      responses:
        '200':
          description: Transcript file content or JSON transcript payload.
          content:
            application/json:
              schema: {}
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              example:
                detail: Transcript Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Jobs
      summary: Export job transcript with selected columns
      description: Exports a transcript for a registered job with optional include/exclude controls.
      operationId: exportJobTranscript
      security:
      - APIKeyHeader: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          description: Reusable registered job ID.
          title: Job Id
        description: Reusable registered job ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranscriptDownloadRequest'
      responses:
        '200':
          description: Transcript file content or JSON transcript payload.
          content:
            application/json:
              schema: {}
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              example:
                detail: Transcript Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/jobs/{job_id}/outputs/subtitle:
    get:
      tags:
      - Jobs
      summary: Download job subtitle
      description: Downloads generated subtitles for a registered job as SRT or VTT.
      operationId: downloadJobSubtitle
      security:
      - APIKeyHeader: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          description: Reusable registered job ID.
          title: Job Id
        description: Reusable registered job ID.
      - name: file_type
        in: query
        required: false
        schema:
          enum:
          - srt
          - vtt
          type: string
          default: srt
          title: File Type
      - name: locale
        in: query
        required: false
        schema:
          type: string
          default: source
          title: Locale
      - name: line_length
        in: query
        required: false
        schema:
          type: integer
          default: 7
          title: Line Length
      responses:
        '200':
          description: Subtitle file content.
          content:
            application/json:
              schema: {}
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              example:
                detail: Subtitle Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    JobLanguageStatus:
      properties:
        target_language:
          type: string
          title: Target Language
          description: Target locale code.
        status:
          type: string
          enum:
          - queued
          - processing
          - completed
          - failed
          title: Status
          description: Current status for this language.
      type: object
      required:
      - target_language
      - status
      title: JobLanguageStatus
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    TranslationJobResponse:
      properties:
        workflow:
          type: string
          enum:
          - translate_media
          - translate_text
          - translate_document
          - translate_subtitles
          title: Workflow
          description: Translation workflow that was started.
        status:
          type: string
          enum:
          - queued
          - started
          - completed
          - error
          title: Status
          description: Current workflow status.
        job_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Job Id
          description: Reusable registered job ID associated with this workflow.
        target_languages:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Target Languages
          description: Target locale codes requested for this workflow.
        format:
          anyOf:
          - type: string
          - type: 'null'
          title: Format
          description: Requested output format when applicable.
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Human-readable status message.
        links:
          additionalProperties:
            type: string
          type: object
          title: Links
          description: Related API links.
      type: object
      required:
      - workflow
      - status
      title: TranslationJobResponse
    TranscriptDownloadRequest:
      properties:
        locale:
          anyOf:
          - type: string
          - type: 'null'
          title: Locale
          description: Transcript locale to export. Use `source` for the original transcript.
          default: source
          examples:
          - source
          - es
        layout:
          type: string
          enum:
          - compact
          - detailed
          title: Layout
          description: Transcript response layout for JSON-style exports.
          default: compact
        file_format:
          type: string
          enum:
          - json
          - csv
          - tsv
          - txt
          title: File Format
          description: Transcript download format.
          default: txt
        include_columns:
          anyOf:
          - items:
              type: string
              enum:
              - speaker_id
              - start_time
              - end_time
              - text
              - gender
              - emotion
            type: array
          - type: 'null'
          title: Include Columns
          description: Additional transcript columns to include in the export.
        exclude_columns:
          anyOf:
          - items:
              type: string
              enum:
              - speaker_id
              - start_time
              - end_time
              - text
              - gender
              - emotion
            type: array
          - type: 'null'
          title: Exclude Columns
          description: Transcript columns to omit from the export.
      type: object
      title: TranscriptDownloadRequest
    JobStatusResponse:
      properties:
        job_id:
          type: string
          title: Job Id
          description: Reusable registered job ID.
        job_type:
          type: string
          enum:
          - video
          - audio
          - document
          title: Job Type
          description: Registered job type.
        status:
          type: string
          enum:
          - queued
          - processing
          - completed
          - failed
          title: Status
          description: Current active workflow processing status.
        stage:
          anyOf:
          - type: string
          - type: 'null'
          title: Stage
          description: Best-effort internal processing stage.
        sub_stage:
          anyOf:
          - type: string
          - type: 'null'
          title: Sub Stage
          description: Best-effort internal processing sub-stage.
        workflows:
          additionalProperties:
            $ref: '#/components/schemas/JobWorkflowStatus'
          propertyNames:
            enum:
            - translation
            - subtitles
          type: object
          title: Workflows
          description: Current workflow statuses keyed by v2 workflow type.
        outputs:
          additionalProperties:
            type: boolean
          type: object
          title: Outputs
          description: Best-effort output availability flags.
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Processing error when the job failed.
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: Last job update timestamp.
      type: object
      required:
      - job_id
      - job_type
      - status
      title: JobStatusResponse
    JobWorkflowStatus:
      properties:
        status:
          type: string
          enum:
          - queued
          - processing
          - completed
          - failed
          title: Status
          description: Current aggregate workflow status.
        languages:
          items:
            $ref: '#/components/schemas/JobLanguageStatus'
          type: array
          title: Languages
      type: object
      required:
      - status
      title: JobWorkflowStatus
    JobResponse:
      properties:
        job_id:
          type: string
          title: Job Id
          description: Reusable registered job ID.
        name:
          type: string
          title: Name
          description: Job display name.
        job_type:
          type: string
          enum:
          - video
          - audio
          - document
          title: Job Type
          description: Registered job type.
        source_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Url
          description: Original or registered source URL.
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: Job creation timestamp.
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: Job update timestamp.
        links:
          additionalProperties:
            type: string
          type: object
          title: Links
          description: Related v2 job links.
      type: object
      required:
      - job_id
      - name
      - job_type
      title: JobResponse
    TranslateSubtitlesRequest:
      properties:
        target_languages:
          items:
            type: string
          type: array
          minItems: 1
          title: Target Languages
          description: 'Target locale codes. Use `GET /v2/languages/text` to list supported subtitle translation languages. Alias accepted: `languages`.'
          examples:
          - - es
            - fr
        format:
          type: string
          enum:
          - srt
          - vtt
          title: Format
          description: Preferred subtitle output format.
          default: srt
        reset:
          type: boolean
          title: Reset
          description: Whether to prune existing subtitle target state before starting processing.
          default: false
        burn_subtitles:
          type: boolean
          title: Burn Subtitles
          description: Whether to burn generated subtitles into media output when supported.
          default: false
        include_source_language:
          type: boolean
          title: Include Source Language
          description: Whether to include source-language subtitles in generated outputs when supported.
          default: false
        word_count_per_line:
          type: integer
          exclusiveMinimum: 0
          title: Word Count Per Line
          description: Maximum subtitle words per line.
          default: 7
      type: object
      required:
      - target_languages
      title: TranslateSubtitlesRequest
    TranslateJobRequest:
      properties:
        target_languages:
          items:
            type: string
          type: array
          minItems: 1
          title: Target Languages
          description: 'Target locale codes. Alias accepted: `languages`. The job type determines whether media or document translation is started.'
          examples:
          - - es
            - fr
        context:
          anyOf:
          - type: string
          - type: 'null'
          title: Context
          description: Optional context used for document translation.
        reset:
          type: boolean
          title: Reset
          description: Whether to prune stale target languages before starting processing; active workflow progress is always refreshed for a new run.
          default: true
        remove_background_audio:
          type: boolean
          title: Remove Background Audio
          description: Whether to remove background audio for media translation.
          default: false
        number_of_speakers:
          type: integer
          minimum: 0
          title: Number Of Speakers
          description: Optional speaker count hint for media translation. Use 0 to auto-detect.
          default: 0
        burn_subtitles_on_source:
          type: boolean
          title: Burn Subtitles On Source
          description: Whether to burn generated subtitles onto source-language media.
          default: false
        prepend_ai_warning:
          type: boolean
          title: Prepend Ai Warning
          description: Whether to prepend an AI-generated-content warning.
          default: false
        enhance:
          type: boolean
          title: Enhance
          description: Whether to enable media enhancement when supported.
          default: false
        experimental_force_accent:
          type: boolean
          title: Experimental Force Accent
          description: Whether to force accent handling for experimental workflows.
          default: false
      type: object
      required:
      - target_languages
      title: TranslateJobRequest
  securitySchemes:
    APIKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey