Deepdub Dubbing API
The Dubbing API from Deepdub — 4 operation(s) for dubbing.
OpenAPI Specification
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