openapi: 3.0.0
info:
  title: Deepdub Dubbing API
  description: Deepdub's Text-to-Speech API enables high-quality, expressive speech generation with voice cloning, accent control, and real-time streaming capabilities.
  contact:
    email: support@deepdub.ai
  version: '1.0'
servers:
- url: https://restapi.deepdub.ai/api/v1
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Dubbing
paths:
  /dubbing/job:
    post:
      summary: Submit Dubbing Job
      description: Create a new dubbing job. The source video is validated, locales are resolved, and the job is queued for processing. Returns a requestId used to track the job.
      operationId: create_dubbing_job_dubbing_job_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DubbingSubmissionRequest'
            example:
              sourceLocale: en-US
              targetLocale: es-ES
              sourceVideoPath: s3://your-bucket/input/episode-01.mp4
              exportPath: s3://your-bucket/output/episode-01.es-ES.mp4
              workflowType: AUTOMATED
              mixType: REPLACEMENT
              additionalProducts:
              - product: SRT
                assetPath: s3://your-bucket/output/episode-01.es-ES.srt
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DubbingSubmissionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Dubbing
  /dubbing/job/{request_id}:
    get:
      summary: Get Dubbing Job Status
      description: Return the current status, progress trace, export path, and additional products for a single dubbing job.
      operationId: get_dubbing_job_dubbing_job__request_id__get
      parameters:
      - required: true
        schema:
          type: string
          title: Request Id
        name: request_id
        in: path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DubbingStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Dubbing
    put:
      summary: Update Dubbing Job
      description: Update mutable fields of an existing job. Only the fields included in the request body are changed.
      operationId: update_request_handler_dubbing_job__request_id__put
      parameters:
      - required: true
        schema:
          type: string
          title: Request Id
        name: request_id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DubbingSubmissionUpdateRequest'
            example:
              needByDate: '2024-07-01T12:00:00Z'
              metadata:
                priority: high
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Dubbing
    delete:
      summary: Cancel Dubbing Job
      description: Mark a job as cancelled. Cancellation is permanent — a cancelled job cannot be revived; submit a new job instead.
      operationId: cancel_request_handler_dubbing_job__request_id__delete
      parameters:
      - required: true
        schema:
          type: string
          title: Request Id
        name: request_id
        in: path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Dubbing
    patch:
      summary: Submit Redubbing Feedback
      description: Submit quality feedback and issue reports for a completed dubbing job, triggering a resynthesis workflow.
      operationId: create_redubbing_job_handler_dubbing_job__request_id__patch
      parameters:
      - required: true
        schema:
          type: string
          title: Request Id
        name: request_id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedubbingSubmissionRequest'
            example:
              generalFeedback: Lip-sync drifts in the second act.
              issues:
              - timestampStart: 12345
                timestampEnd: 23456
                category: TIMING
                severity: MAJOR
                label: TIMING_LIPSYNC
                details: Dialogue starts roughly 300ms late.
                timestamp: '2024-06-01T15:30:00Z'
              additionalProducts:
              - product: SDH
                assetPath: s3://your-bucket/output/episode-01.sdh.srt
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedubbingSubmissionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Dubbing
  /dubbing/jobs:
    get:
      summary: List Dubbing Jobs
      description: Return a paginated list of dubbing jobs belonging to the authenticated customer. Cancelled jobs are excluded.
      operationId: list_dubbing_jobs_dubbing_jobs_get
      parameters:
      - required: false
        schema:
          type: string
          title: Next Token
        name: next_token
        in: query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DubbingStatusListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Dubbing
  /dubbing/job/{request_id}/sources:
    post:
      summary: Add Additional Source
      description: Attach an additional source asset (subtitles, audio hints, etc.) to an existing job. The new source is ingested asynchronously.
      operationId: add_source_handler_dubbing_job__request_id__sources_post
      parameters:
      - required: true
        schema:
          type: string
          title: Request Id
        name: request_id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DubbingSubmissionAdditionalSource'
            example:
              source: CC_SDH
              assetPath: s3://your-bucket/input/episode-01.captions.dfxp
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Dubbing
components:
  schemas:
    IssueLabel:
      type: string
      enum:
      - ACCENT
      - ADAPTATION
      - AUDIO_ARTIFACT
      - EMOTION
      - EMPHASIS
      - MISPRONUNCIATION
      - MISSING_AUDIO
      - MIX
      - RHYTHM
      - SPEAKER_CONSISTENCY
      - TIMING_LIPSYNC
      title: IssueLabel
      description: Specific label describing the nature of a quality issue.
    DubbingSubmissionAdditionalSource:
      properties:
        source:
          allOf:
          - $ref: '#/components/schemas/AdditionalSourcesEnum'
          description: Type of source asset (e.g., 'AUDIO_HINTS', 'CC_SDH', 'MISC', 'DFXP_SUBTITLES')
        assetPath:
          type: string
          title: Assetpath
          description: S3 path to the asset file (must start with 's3://', e.g., 's3://bucket/asset.mp4')
      type: object
      required:
      - source
      - assetPath
      title: DubbingSubmissionAdditionalSource
    DubbingSubmissionRequest:
      properties:
        sourceLocale:
          type: string
          title: Sourcelocale
          description: Locale code of the source language (e.g., 'en-US')
        targetLocale:
          type: string
          title: Targetlocale
          description: Locale code of the target language (e.g., 'es-ES')
        sourceVideoPath:
          type: string
          title: Sourcevideopath
          description: S3 or HTTPS path to the source video file (e.g., 's3://bucket/video.mp4' or 'https://example.com/video.mp4')
        exportPath:
          type: string
          title: Exportpath
          description: S3 path where the dubbed video will be exported (must start with 's3://', e.g., 's3://bucket/output.mp4')
        contentId:
          type: string
          title: Contentid
          description: Unique identifier for the content (e.g., 'content_123')
        batchId:
          type: string
          title: Batchid
          description: Identifier for the batch this submission belongs to (e.g., 'batch_001')
        batchName:
          type: string
          title: Batchname
          description: Name of the batch this submission belongs to (e.g., 'Power Rangers Season 1')
        workflowType:
          allOf:
          - $ref: '#/components/schemas/WorkflowTypeEnum'
          description: Type of workflow to use for dubbing (e.g., 'AUTOMATED', 'MANAGED')
          default: AUTOMATED
        mixType:
          allOf:
          - $ref: '#/components/schemas/MixTypeEnum'
          description: Type of audio mix to use for dubbing (e.g., 'REPLACEMENT', 'UN_STYLE')
          default: REPLACEMENT
        sourceSpeechTrackPath:
          type: string
          title: Sourcespeechtrackpath
          description: S3 path to the source speech audio track, if separate from video (must start with 's3://', e.g., 's3://bucket/audio.wav')
        sourceMAndETrackPath:
          type: string
          title: Sourcemandetrackpath
          description: S3 path to the source Music & Effects (M&E) track (must start with 's3://', e.g., 's3://bucket/me_track.wav')
        uncompressedAudioPath:
          type: string
          title: Uncompressedaudiopath
          description: S3 path to the uncompressed audio file, if available (must start with 's3://', e.g., 's3://bucket/uncompressed.wav')
        segments:
          items:
            $ref: '#/components/schemas/DubbingSegment'
          type: array
          title: Segments
          description: List of segments to be dubbed, with timing and dialogue information
        titleName:
          type: string
          title: Titlename
          description: Title of the content (e.g., 'The Great Adventure')
        genreName:
          type: string
          title: Genrename
          description: Genre of the content (e.g., 'Action', 'Comedy')
        maturityRating:
          type: string
          title: Maturityrating
          description: Maturity rating of the content (e.g., 'PG-13', 'R')
        contentType:
          type: string
          title: Contenttype
          description: Type of content (e.g., 'movie', 'series')
        priority:
          type: integer
          title: Priority
          description: Priority of the dubbing job (higher means more urgent, e.g., 10)
        needByDate:
          type: string
          format: date-time
          title: Needbydate
          description: Date by which the dubbed content is needed (e.g., '2024-07-01T12:00:00Z')
        isVideoWaterMarked:
          type: boolean
          title: Isvideowatermarked
          description: Indicates if the source video is watermarked (e.g., True, False)
          default: false
        additionalSources:
          items:
            $ref: '#/components/schemas/DubbingSubmissionAdditionalSource'
          type: array
          title: Additionalsources
          description: Additional source assets to attach as input reference material (e.g., closed captions, audio hints)
        additionalProducts:
          items:
            $ref: '#/components/schemas/DubbingSubmissionAdditionalProduct'
          type: array
          title: Additionalproducts
          description: Deliverable products to produce alongside or instead of the dubbed video (e.g., SRT subtitles, transcripts)
        metadata:
          additionalProperties:
            type: string
          type: object
          title: Metadata
          description: 'Metadata attached to the dubbing job (e.g., {''key'': ''value''})'
      type: object
      required:
      - sourceLocale
      - targetLocale
      - sourceVideoPath
      title: DubbingSubmissionRequest
    AdditionalProductStateEnum:
      type: string
      enum:
      - PENDING_DELIVERY
      - DELIVERED
      title: AdditionalProductStateEnum
      description: 'State of an additional product in the delivery lifecycle.


        None   – legacy / unknown (pre-deployment products, not shown as pending).

        PENDING_DELIVERY – explicitly awaiting delivery.

        DELIVERED        – already delivered to the customer.'
    DubbingStatusListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/DubbingStatusResponse'
          type: array
          title: Items
        nextToken:
          type: string
          title: Nexttoken
      type: object
      required:
      - items
      title: DubbingStatusListResponse
    RedubbingSubmissionRequest:
      properties:
        generalFeedback:
          type: string
          title: Generalfeedback
          description: General feedback for the redubbing submission (e.g., 'The timing was off in several places.')
        exportPath:
          type: string
          title: Exportpath
          description: S3 path to the exported video file (must start with 's3://', e.g., 's3://bucket/output.mp4') if different from the original export path
        issues:
          items:
            $ref: '#/components/schemas/RedubbingIssue'
          type: array
          title: Issues
          description: List of issues identified in the redubbing submission
          default: []
        revisionNumber:
          type: integer
          title: Revisionnumber
          description: Revision number of the redubbing submission if applicable
        additionalProducts:
          items:
            $ref: '#/components/schemas/DubbingSubmissionAdditionalProduct'
          type: array
          title: Additionalproducts
          description: Additional products to (re-)deliver with this revision (e.g., updated SDH or transcript)
      type: object
      required:
      - generalFeedback
      title: RedubbingSubmissionRequest
    RedubbingIssue:
      properties:
        timestampStart:
          type: integer
          title: Timestampstart
          description: Start timestamp of the issue in milliseconds (e.g., 12345)
        timestampEnd:
          type: integer
          title: Timestampend
          description: End timestamp of the issue in milliseconds (e.g., 23456)
        category:
          allOf:
          - $ref: '#/components/schemas/IssueCategory'
          description: Category of the issue (e.g., 'SYNTHESIS', 'TRANSLATION')
        severity:
          allOf:
          - $ref: '#/components/schemas/IssueSeverity'
          description: Severity level of the issue (e.g., 'SUGGESTION', 'MINOR', 'MAJOR', 'CRITICAL')
        label:
          allOf:
          - $ref: '#/components/schemas/IssueLabel'
          description: Label describing the type of issue (e.g., 'ACCENT', 'ADAPTATION', 'AUDIO_ARTIFACT')
        details:
          type: string
          title: Details
          description: Detailed description of the issue (e.g., 'The accent does not match the character profile.')
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp when the issue was reported (e.g., '2024-06-01T15:30:00Z')
        issueId:
          type: string
          title: Issueid
          description: Unique identifier for the issue (e.g., 'issue_001')
      type: object
      required:
      - timestampStart
      - timestampEnd
      - category
      - severity
      - label
      - details
      - timestamp
      title: RedubbingIssue
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    DubbingSegment:
      properties:
        timestampStart:
          type: integer
          title: Timestampstart
          description: Start time of the segment in milliseconds (e.g., 12345)
        timestampEnd:
          type: integer
          title: Timestampend
          description: End time of the segment in milliseconds (e.g., 23456)
        characterName:
          type: string
          title: Charactername
          description: Name of the character speaking in this segment (e.g., 'John', 'Narrator')
        characterId:
          type: string
          title: Characterid
          description: Unique identifier for the character (e.g., 'char_001')
        sourceDialogue:
          type: string
          title: Sourcedialogue
          description: Original dialogue text in the source language (e.g., 'Hello, how are you?')
        targetDialogue:
          type: string
          title: Targetdialogue
          description: Translated dialogue text in the target language (e.g., 'Hola, ¿cómo estás?')
        segmentId:
          type: string
          title: Segmentid
          description: Unique identifier for the segment (e.g., 'seg_001')
      type: object
      required:
      - timestampStart
      - timestampEnd
      - characterName
      - characterId
      - sourceDialogue
      title: DubbingSegment
    AdditionalProductsEnum:
      type: string
      enum:
      - SDH
      - SRT
      - WEBVTT
      - TRANSCRIPT
      - AS_RECORDED_SCRIPT
      - AUDIO_HINTS
      - SOURCE_VIDEO
      - SOURCE_AUDIO
      - ITT_SUBTITLES
      title: AdditionalProductsEnum
      description: Type of deliverable product that can be requested alongside (or instead of) the dubbed video.
    DubbingStatusResponse:
      properties:
        requestId:
          type: string
          title: Requestid
        status:
          $ref: '#/components/schemas/ManagedDubProgressStatusEnum'
        detailedTrace:
          type: string
          title: Detailedtrace
        exportPath:
          type: string
          title: Exportpath
        additionalProducts:
          items:
            $ref: '#/components/schemas/DubbingSubmissionAdditionalProduct'
          type: array
          title: Additionalproducts
        metadata:
          additionalProperties:
            type: string
          type: object
          title: Metadata
      type: object
      required:
      - requestId
      - status
      - detailedTrace
      - exportPath
      - additionalProducts
      - metadata
      title: DubbingStatusResponse
    DubbingSubmissionResponse:
      properties:
        requestId:
          type: string
          title: Requestid
      type: object
      required:
      - requestId
      title: DubbingSubmissionResponse
    MixTypeEnum:
      type: string
      enum:
      - UN_STYLE
      - REPLACEMENT
      title: MixTypeEnum
      description: 'Audio mixing strategy: REPLACEMENT (replace original dialogue track) or UN_STYLE (overlay dubbed audio on the original).'
    RedubbingSubmissionResponse:
      properties:
        requestId:
          type: string
          title: Requestid
          description: Unique identifier for the redubbing submission request (e.g., 'redub_req_001')
      type: object
      required:
      - requestId
      title: RedubbingSubmissionResponse
    ManagedDubProgressStatusEnum:
      type: string
      enum:
      - INTAKE_PREPROCESSING
      - INTAKE_VALIDATION
      - INTAKE_FAILED
      - INTAKE_APPROVED
      - CASTING
      - ADAPTGEN_START
      - ADAPTGEN_MIDWAY
      - READY_FOR_QC
      - QC
      - QC_IN_REVIEW
      - ADAPTGEN_QC_FIX
      - READY_FOR_DMX
      - DMX_DONE
      - READY_FOR_MIXING
      - MIXING_IN_PROGRESS
      - READY_FOR_MIX_QC
      - MIX_QC_IN_PROGRESS
      - DELIVERED_TO_CLIENT
      - CLIENT_REFIX_PROCESSING
      - CLIENT_REFIX_REJECTED
      - CLIENT_REFIX
      - FAILURE
      - READY_FOR_REDMX
      - PARKED_REQUEST
      - PARKED_REQUEST_RECEIVED
      - REDMX_DONE
      - REDELIVERED_TO_CLIENT
      title: ManagedDubProgressStatusEnum
      description: Lifecycle status of a dubbing job, from initial intake through delivery and optional client re-fixes.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DubbingSubmissionAdditionalProduct:
      properties:
        product:
          allOf:
          - $ref: '#/components/schemas/AdditionalProductsEnum'
          description: Type of product to deliver (e.g., 'SDH', 'SRT', 'WEBVTT', 'TRANSCRIPT')
        assetPath:
          type: string
          title: Assetpath
          description: S3 path to the asset file (must start with 's3://', e.g., 's3://bucket/asset.mp4')
        state:
          allOf:
          - $ref: '#/components/schemas/AdditionalProductStateEnum'
          description: 'Delivery state: None means pending delivery, DELIVERED means already delivered.'
      type: object
      required:
      - product
      - assetPath
      title: DubbingSubmissionAdditionalProduct
    AdditionalSourcesEnum:
      type: string
      enum:
      - AUDIO_HINTS
      - CC_SDH
      - MISC
      - DFXP_SUBTITLES
      title: AdditionalSourcesEnum
      description: Type of additional source asset that can be attached to a dubbing job as input reference material.
    IssueCategory:
      type: string
      enum:
      - SYNTHESIS
      - TRANSLATION
      - TIMING
      - MIX
      title: IssueCategory
      description: High-level category of a quality issue reported during redubbing review.
    WorkflowTypeEnum:
      type: string
      enum:
      - AUTOMATED
      - MANAGED
      - MANAGED_HIGH_TIER
      title: WorkflowTypeEnum
      description: 'Dubbing workflow tier: AUTOMATED (fully automated), MANAGED (human-in-the-loop QC), or MANAGED_HIGH_TIER (premium managed).'
    DubbingSubmissionUpdateRequest:
      properties:
        needByDate:
          type: string
          format: date-time
          title: Needbydate
          description: Date by which the dubbed content is needed (e.g., '2024-07-01T12:00:00Z')
        metadata:
          additionalProperties:
            type: string
          type: object
          title: Metadata
          description: 'Metadata attached to the dubbing job (e.g., {''key'': ''value''})'
      type: object
      title: DubbingSubmissionUpdateRequest
    IssueSeverity:
      type: string
      enum:
      - SUGGESTION
      - MINOR
      - MAJOR
      - CRITICAL
      title: IssueSeverity
      description: 'Severity level of a quality issue: SUGGESTION (nice-to-have) through CRITICAL (must-fix).'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. Must start with `dd-` prefix.
externalDocs:
  description: OpenAPI
  url: https://restapi.deepdub.ai/api/v1/swagger/index.html