openapi: 3.0.0
info:
  title: Deepdub Dubbing Voice 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: Voice
paths:
  /voice:
    get:
      operationId: getVoicePrompts
      description: Retrieve all private voice prompts associated with the authenticated customer's account. Results can be limited using the `limit` query parameter.
      tags:
      - Voice
      summary: Get voice prompts
      parameters:
      - description: API Key
        name: x-api-key
        in: header
        required: true
        schema:
          type: string
          default: dd-00000000000000000000000065c9cbfe
        example: dd-00000000000000000000000065c9cbfe
      - description: Maximum number of voice prompts to return
        name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 100
          minimum: 1
      responses:
        '200':
          description: List of voice prompts
          content:
            application/json:
              schema:
                type: object
                properties:
                  voicePrompts:
                    type: array
                    items:
                      $ref: '#/components/schemas/model.VoicePrompt'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: Invalid request parameters
        '401':
          description: Unauthorized — invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: 'Unauthorized: invalid or missing API key'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: Internal server error
    post:
      operationId: createVoicePrompt
      description: Upload a voice sample to create a new voice prompt in the voice bank. The audio data must be base64-encoded. Maximum file size is 20 MB.
      tags:
      - Voice
      summary: Upload a voice sample
      parameters:
      - description: API Key
        name: x-api-key
        in: header
        required: true
        schema:
          type: string
          default: dd-00000000000000000000000065c9cbfe
        example: dd-00000000000000000000000065c9cbfe
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/model.VoiceBankAPIRequest'
        description: Voice upload request. Audio data must be base64-encoded and not exceed 20 MB.
        required: true
      responses:
        '200':
          description: Voice prompt created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    $ref: '#/components/schemas/model.VoiceBankAPIResponse'
        '400':
          description: Bad request — invalid audio data, missing fields, or file exceeds 20 MB limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: Audio data exceeds 20 MB limit
        '401':
          description: Unauthorized — invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: 'Unauthorized: invalid or missing API key'
        '403':
          description: Forbidden — voice prompt limit reached for your account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: Voice prompt limit reached for your account
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: Internal server error
    put:
      operationId: updateVoicePrompt
      description: Update metadata for an existing voice prompt. Only non-empty fields are updated — omit fields you don't want to change.
      tags:
      - Voice
      summary: Update a voice prompt
      parameters:
      - description: API Key
        name: x-api-key
        in: header
        required: true
        schema:
          type: string
          default: dd-00000000000000000000000065c9cbfe
        example: dd-00000000000000000000000065c9cbfe
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/model.VoiceBankAPIUpdateRequest'
        description: Voice update request. Only non-empty fields will be updated.
        required: true
      responses:
        '200':
          description: Voice prompt updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  prompt:
                    $ref: '#/components/schemas/model.VoicePrompt'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: 'Invalid request: voice prompt ID is required'
        '401':
          description: Unauthorized — invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: 'Unauthorized: invalid or missing API key'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: Internal server error
  /voice/{prompt_id}:
    get:
      operationId: getVoicePromptById
      description: Retrieve a specific voice prompt by its unique identifier.
      tags:
      - Voice
      summary: Get a voice prompt by ID
      parameters:
      - description: API Key
        name: x-api-key
        in: header
        required: true
        schema:
          type: string
          default: dd-00000000000000000000000065c9cbfe
        example: dd-00000000000000000000000065c9cbfe
      - description: Voice Prompt ID
        name: prompt_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Voice prompt details
          content:
            application/json:
              schema:
                type: object
                properties:
                  prompt:
                    $ref: '#/components/schemas/model.VoicePrompt'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: Invalid voice prompt ID format
        '401':
          description: Unauthorized — invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: 'Unauthorized: invalid or missing API key'
        '404':
          description: Voice prompt not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: Voice prompt not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: Internal server error
    delete:
      operationId: deleteVoicePrompt
      description: Permanently delete a voice prompt by its unique identifier.
      tags:
      - Voice
      summary: Delete a voice prompt
      parameters:
      - description: API Key
        name: x-api-key
        in: header
        required: true
        schema:
          type: string
          default: dd-00000000000000000000000065c9cbfe
        example: dd-00000000000000000000000065c9cbfe
      - description: Voice Prompt ID
        name: prompt_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Voice prompt deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.Response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: Invalid voice prompt ID
        '401':
          description: Unauthorized — invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: 'Unauthorized: invalid or missing API key'
        '404':
          description: Voice prompt not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: Voice prompt not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/model.APIError'
              example:
                success: false
                message: Internal server error
components:
  schemas:
    model.VoiceBankAPIResponse:
      description: Response after creating or deleting a voice prompt
      type: object
      properties:
        voice_prompt_id:
          description: Unique identifier of the created/affected voice prompt
          type: string
          example: vp_12345abcde
    model.VoiceBankAPIUpdateRequest:
      description: Request to update a voice prompt's metadata
      type: object
      required:
      - id
      properties:
        id:
          description: Unique identifier for the voice prompt to update
          type: string
          example: vp_12345abcde
        name:
          description: New display name for the voice prompt
          type: string
          example: Professional Female Voice
        locale:
          description: Language locale code
          type: string
          example: en-US
        gender:
          description: Gender of the speaker
          type: string
          enum:
          - MALE
          - FEMALE
          - NON_BINARY
          example: FEMALE
        age:
          description: Age of the speaker
          type: integer
          example: 35
    model.VoicePrompt:
      description: A voice prompt representing a cloned or uploaded voice
      type: object
      properties:
        id:
          description: Unique identifier for the voice prompt
          type: string
          example: vp_12345abcde
        title:
          description: Title of the voice prompt
          type: string
          example: Professional Narrator
        name:
          description: Display name of the voice prompt
          type: string
          example: Professional Female Voice
        locale:
          description: Locale of the voice prompt
          type: string
          example: en-US
        text:
          description: Transcript text associated with the voice prompt
          type: string
        createdAt:
          description: Timestamp when the voice prompt was created
          type: string
          format: date-time
        speakerId:
          description: Unique identifier for the speaker
          type: string
        gender:
          description: Gender of the voice
          type: string
          enum:
          - MALE
          - FEMALE
          - NON_BINARY
          example: FEMALE
        speakingStyle:
          description: Speaking style of the voice
          type: string
          example: narrative
    model.VoiceBankAPIRequest:
      description: Request to upload a voice sample and create a voice prompt
      type: object
      required:
      - filename
      - data
      properties:
        filename:
          description: Name of the audio file being uploaded
          type: string
          example: voice_sample.wav
        data:
          description: Base64-encoded audio data
          type: string
        title:
          description: Title for the voice prompt
          type: string
          example: Professional Narrator
        text:
          description: Transcript of the spoken text in the audio sample
          type: string
          example: This is a sample recording for voice cloning.
        locale:
          description: Language locale code of the voice sample
          type: string
          example: en-US
        gender:
          description: Gender of the speaker
          type: string
          enum:
          - MALE
          - FEMALE
          - NON_BINARY
          example: FEMALE
        age:
          description: Age of the speaker
          type: integer
          example: 35
        speaking_style:
          description: Speaking style descriptor
          type: string
          example: narrative
        speaker_id:
          description: Optional external speaker identifier
          type: string
        publish:
          description: Whether to make the voice prompt publicly available
          type: boolean
          example: false
    model.Response:
      description: Standard API success response wrapper
      type: object
      required:
      - success
      properties:
        success:
          description: Whether the operation was successful
          type: boolean
          example: true
        message:
          description: Human-readable status message
          type: string
          example: Operation successful
        data:
          description: Response payload (varies by endpoint)
    model.APIError:
      description: Error response returned for all non-2xx status codes
      type: object
      required:
      - success
      - message
      properties:
        success:
          description: Always false for error responses
          type: boolean
          example: false
        message:
          description: Human-readable error message
          type: string
          example: Invalid request parameters
  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