openapi: 3.2.0
info:
  version: 1.0.0
  title: Firefly Services Audio and Video Text To Avatar API
  description: This RESTful API provides resources to use Firefly Services AI for audio and video generation and processing.
  termsOfService: https://www.adobe.com/content/dam/cc/en/legal/terms/enterprise/pdfs/PSLT-AdobeCreativeAPI-WW-2024v2.pdf
servers:
- url: https://audio-video-api.adobe.io
  description: Production server.
security:
- AccessToken: []
  X-Api-Key: []
tags:
- name: Text-to-Avatar
  description: Endpoints for Text-to-Avatar operations.
paths:
  /v1/voices:
    get:
      tags:
      - Text-to-Avatar
      summary: Get available voices
      description: This endpoint provides the list of all available voices for the user's enterprise.
      operationId: voices
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulVoicesResponse'
              examples:
                Success:
                  $ref: '#/components/examples/SuccessfulVoicesResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResponse'
              examples:
                ErrorBodyUnauthorized:
                  $ref: '#/components/examples/ErrorBodyUnauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResponse'
              examples:
                ErrorBodyForbidden:
                  $ref: '#/components/examples/ErrorBodyForbidden'
                ErrorBodyAPIKeyInvalid:
                  $ref: '#/components/examples/ErrorBodyAPIKeyInvalid'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResponse'
              examples:
                ErrorBodyTooManyRequests:
                  $ref: '#/components/examples/ErrorBodyTooManyRequests'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResponse'
              examples:
                RunTimeError:
                  $ref: '#/components/examples/RunTimeError'
                StudioAPIFailedEntitiesErrorResponse:
                  $ref: '#/components/examples/StudioAPIFailedEntitiesErrorResponse'
  /v1/avatars:
    get:
      tags:
      - Text-to-Avatar
      summary: Get available avatars
      description: Retrieves the list of all available avatars for the user's enterprise.
      operationId: avatars
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulAvatarsResponse'
              examples:
                Success:
                  $ref: '#/components/examples/SuccessfulAvatarsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResponse'
              examples:
                ErrorBodyUnauthorized:
                  $ref: '#/components/examples/ErrorBodyUnauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResponse'
              examples:
                ErrorBodyForbidden:
                  $ref: '#/components/examples/ErrorBodyForbidden'
                ErrorBodyAPIKeyInvalid:
                  $ref: '#/components/examples/ErrorBodyAPIKeyInvalid'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResponse'
              examples:
                ErrorBodyTooManyRequests:
                  $ref: '#/components/examples/ErrorBodyTooManyRequests'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResponse'
              examples:
                RunTimeError:
                  $ref: '#/components/examples/RunTimeError'
                StudioAPIFailedEntitiesErrorResponse:
                  $ref: '#/components/examples/StudioAPIFailedEntitiesErrorResponse'
  /v1/generate-avatar:
    post:
      tags:
      - Text-to-Avatar
      summary: Generate avatar video from text
      description: Generates an avatar video from a provided transcript or audio file. You can provide the transcript either as plain text or a pre-signed URL. The API is asynchronous, so the response will include a job ID and a status URL for tracking the running job.
      operationId: generate-avatar
      requestBody:
        description: The request body contains the transcript and details for generating an avatar.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AvatarRequest'
            examples:
              PlainTextInputForAvatarGeneration:
                $ref: '#/components/examples/PlainTextInputForAvatarGeneration'
              PlainTextInputForAvatarGenerationUsingVideoBackground:
                $ref: '#/components/examples/PlainTextInputForAvatarGenerationUsingVideoBackground'
              PlainTextInputForAvatarGenerationUsingImageBackground:
                $ref: '#/components/examples/PlainTextInputForAvatarGenerationUsingImageBackground'
              PlainTextInputForAvatarGenerationUsingColorBackground:
                $ref: '#/components/examples/PlainTextInputForAvatarGenerationUsingColorBackground'
              URLTextInputForAvatarGeneration:
                $ref: '#/components/examples/URLTextInputForAvatarGeneration'
              URLInputForAvatarGeneration:
                $ref: '#/components/examples/URLInputForAvatarGeneration'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitAPIResponse'
              examples:
                SubmitRequestResponse:
                  $ref: '#/components/examples/SubmitRequestResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResponse'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResponse'
              examples:
                UnauthorizedAccessError:
                  $ref: '#/components/examples/ErrorBodyUnauthorized'
                ErrorBodyAccessDenied:
                  $ref: '#/components/examples/ErrorBodyAccessDenied'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResponse'
              examples:
                ErrorBodyForbidden:
                  $ref: '#/components/examples/ErrorBodyForbidden'
                ErrorBodyAPIKeyInvalid:
                  $ref: '#/components/examples/ErrorBodyAPIKeyInvalid'
                UserNotEntitledError:
                  $ref: '#/components/examples/UserNotEntitledError'
                QuotaExceededError:
                  $ref: '#/components/examples/QuotaExceededError'
                UserProfileDeniedError:
                  $ref: '#/components/examples/UserProfileDeniedError'
                UserBlockedError:
                  $ref: '#/components/examples/UserBlockedError'
                InvalidSubscriptionError:
                  $ref: '#/components/examples/InvalidSubscriptionError'
                ViolationError:
                  $ref: '#/components/examples/ViolationError'
                TasteExhaustedError:
                  $ref: '#/components/examples/TasteExhaustedError'
                AccessError:
                  $ref: '#/components/examples/AccessError'
        '422':
          description: Unprocessable Entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResponse'
              examples:
                InvalidInputErrorExample:
                  $ref: '#/components/examples/InvalidInputErrorExample'
                MissingInputFileUrlErrorExample:
                  $ref: '#/components/examples/MissingInputFileUrlErrorExample'
                InvalidInputUrlErrorExample:
                  $ref: '#/components/examples/InvalidInputUrlErrorExample'
                InputFileFormatValidationErrorExample:
                  $ref: '#/components/examples/InputFileFormatValidationErrorExample'
                MissingScriptErrorExample:
                  $ref: '#/components/examples/MissingScriptErrorExample'
                EmptyTextForScriptErrorExample:
                  $ref: '#/components/examples/EmptyTextForScriptErrorExample'
                TextLengthExceededForScriptErrorExample:
                  $ref: '#/components/examples/TextLengthExceededForScriptErrorExample'
                TextLengthTooShortForScriptErrorExample:
                  $ref: '#/components/examples/TextLengthTooShortForScriptErrorExample'
                ScriptInvalidASCIIRange:
                  $ref: '#/components/examples/ScriptInvalidASCIIRange'
                ScriptInvalidTextSupportedRange:
                  $ref: '#/components/examples/ScriptInvalidTextSupportedRange'
                InvalidOrMissingLocaleCodeForScriptErrorExample:
                  $ref: '#/components/examples/InvalidOrMissingLocaleCodeForScriptErrorExample'
                MissingMediaTypeForScriptErrorExample:
                  $ref: '#/components/examples/MissingMediaTypeForScriptErrorExample'
                MissingSourceLocaleErrorExample:
                  $ref: '#/components/examples/MissingSourceLocaleErrorExample'
                SourceUrlSourceTextConflictErrorExample:
                  $ref: '#/components/examples/SourceUrlSourceTextConflictErrorExample'
                UnsupportedVoiceIdErrorExample:
                  $ref: '#/components/examples/UnsupportedVoiceIdErrorExample'
                MissingVoiceIdErrorExample:
                  $ref: '#/components/examples/MissingVoiceIdErrorExample'
                MissingOutputErrorExample:
                  $ref: '#/components/examples/MissingOutputErrorExample'
                MissingMediaTypeForOutputErrorExample:
                  $ref: '#/components/examples/MissingMediaTypeForOutputErrorExample'
                InvalidOutputFileFormatErrorExample:
                  $ref: '#/components/examples/InvalidOutputFileFormatErrorExample'
                InvalidRequestPayloadErrorExample:
                  $ref: '#/components/examples/InvalidRequestPayloadErrorExample'
                InputScriptAudioConflictErrorExample:
                  $ref: '#/components/examples/InputScriptAudioConflictErrorExample'
                InputScriptAudioMissingErrorExample:
                  $ref: '#/components/examples/InputScriptAudioMissingErrorExample'
                InputScriptAudioMissingOrInvalidErrorExample:
                  $ref: '#/components/examples/InputScriptAudioMissingOrInvalidErrorExample'
                InvalidOrMissingAudioUrlErrorExample:
                  $ref: '#/components/examples/InvalidOrMissingAudioUrlErrorExample'
                MissingAudioSourceErrorExample:
                  $ref: '#/components/examples/MissingAudioSourceErrorExample'
                MissingAvatarIdErrorExample:
                  $ref: '#/components/examples/MissingAvatarIdErrorExample'
                UnsupportedAvatarIdErrorExample:
                  $ref: '#/components/examples/UnsupportedAvatarIdErrorExample'
                MissingBackgroundUrlErrorExample:
                  $ref: '#/components/examples/MissingBackgroundUrlErrorExample'
                MissingBackgroundTypeErrorExample:
                  $ref: '#/components/examples/MissingBackgroundTypeErrorExample'
                InvalidBackgroundUrlErrorExample:
                  $ref: '#/components/examples/InvalidBackgroundUrlErrorExample'
                BackgroundSourceColorConflictErrorExample:
                  $ref: '#/components/examples/BackgroundSourceColorConflictErrorExample'
                BackgroundSourceColorMissingErrorExample:
                  $ref: '#/components/examples/BackgroundSourceColorMissingErrorExample'
                InvalidBackgroundColorErrorExample:
                  $ref: '#/components/examples/InvalidBackgroundColorErrorExample'
                MissingBackgroundColorErrorExample:
                  $ref: '#/components/examples/MissingBackgroundColorErrorExample'
                BackgroundIncompatibleWithFormat:
                  $ref: '#/components/examples/BackgroundIncompatibleWithFormat'
                FormatIncompatibleWithBackground:
                  $ref: '#/components/examples/FormatIncompatibleWithBackground'
                UnsupportedOutputResolution:
                  $ref: '#/components/examples/UnsupportedOutputResolution'
                UnsupportedShotTypeErrorExample:
                  $ref: '#/components/examples/UnsupportedShotTypeErrorExample'
                InvalidSourceUrlErrorExample:
                  $ref: '#/components/examples/InvalidSourceUrlErrorExample'
                IncorrectVoiceNameErrorExample:
                  $ref: '#/components/examples/IncorrectVoiceNameErrorExample'
                MediatypeIncompatibleForText:
                  $ref: '#/components/examples/MediatypeIncompatibleForText'
                MISSING_PARAMS_IN_CROP_AREA:
                  $ref: '#/components/examples/MISSING_PARAMS_IN_CROP_AREA'
                INVALID_CROP_AREA_PARAMS:
                  $ref: '#/components/examples/INVALID_CROP_AREA_PARAMS'
                CROP_AREA_ASPECT_RATIO_NOT_SUPPORTED:
                  $ref: '#/components/examples/CROP_AREA_ASPECT_RATIO_NOT_SUPPORTED'
                StatusAPIFailedBackgroundFileResponse:
                  $ref: '#/components/examples/StatusAPIFailedBackgroundFileResponse'
                CROP_AREA_UNSUPPORTED_FOR_NON_IMAGE_VIDEO_BACKGROUND:
                  $ref: '#/components/examples/CROP_AREA_UNSUPPORTED_FOR_NON_IMAGE_VIDEO_BACKGROUND'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResponse'
              examples:
                ErrorBodyTooManyRequests:
                  $ref: '#/components/examples/ErrorBodyTooManyRequests'
                ErrorBodyRateLimited:
                  $ref: '#/components/examples/ErrorBodyRateLimited'
        '451':
          description: Unavailable For Legal Reasons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResponse'
              examples:
                ErrorBodyLegalReasons:
                  $ref: '#/components/examples/ErrorBodyLegalReasons'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResponse'
              examples:
                TTSServiceSubmitError:
                  $ref: '#/components/examples/TTSServiceSubmitError'
                TTSEntityCreationError:
                  $ref: '#/components/examples/TTSEntityCreationError'
                TTSRuntimeError:
                  $ref: '#/components/examples/TTSRuntimeError'
components:
  examples:
    InvalidSourceUrlErrorExample:
      summary: Invalid Source URL
      value:
        error_code: validation_error
        message: Invalid source url specified
    BackgroundSourceColorConflictErrorExample:
      summary: Both Background Source and Color
      value:
        error_code: validation_error
        message: Must specify either background source or color, not both
    ErrorBodyForbidden:
      summary: Api Key is required
      value:
        error_code: '403000'
        message: Api Key is required
    MissingMediaTypeForScriptErrorExample:
      summary: Missing Script Mediatype
      value:
        error_code: validation_error
        message: Missing script 'mediaType' in the payload
    MissingInputFileUrlErrorExample:
      summary: Missing Input URL
      value:
        error_code: validation_error
        message: Missing input file URL
    EmptyTextForScriptErrorExample:
      summary: Empty Input Text
      value:
        error_code: validation_error
        message: The provided 'text' is empty
    MissingSourceLocaleErrorExample:
      summary: Missing Source Locale
      value:
        error_code: validation_error
        message: Source locale missing in payload
    ErrorBodyRateLimited:
      summary: Rate Limited
      value:
        error_code: rate_limited
        message: Too many requests received
    InvalidBackgroundColorErrorExample:
      summary: Invalid Background Color
      value:
        error_code: validation_error
        message: Invalid 'color' specified in background
    MissingVoiceIdErrorExample:
      summary: Missing Voice ID
      value:
        error_code: validation_error
        message: Missing 'voiceId' in the payload
    InvalidOrMissingAudioUrlErrorExample:
      summary: Invalid Audio URL
      value:
        error_code: validation_error
        message: Invalid or missing 'url' specified in audio
    BadRequestError:
      summary: Bad Request
      value:
        error_code: invalid_json
        message: Invalid request. Please check the input data.
    SuccessfulAvatarsResponse:
      summary: Successful response with avatars details
      value:
        avatars:
        - avatarId: a321
          displayName: Alice
          gender: F
          clothingStyle: Formal
          ageGroup: Young Adult
          ethnicity: Caucasian
          status: Active
          style: Doctor
          extendedPropertyMap:
            aspectRatio:
              x: 16
              y: 9
            resolution:
              width: 1920
              height: 1080
          thumbnailUrls:
            hd: <pre-signed url for downloading HD avatar thumbnail>
            lowRes: <pre-signed url for downloading low resolution avatar thumbnail>
          voiceId: v321
          sampleVideo:
            webm: <pre-signed url for downloading the avatar sample video in WEBM format>
            mp4: <pre-signed url for downloading the avatar sample video in MP4 format>
    InvalidInputErrorExample:
      summary: Invalid Input
      value:
        error_code: validation_error
        message: The request could not be processed due to invalid input
    TTSEntityCreationError:
      summary: Error Processing Request
      value:
        error_code: runtime_error
        message: Internal Server Error while creating text to speech request
    UnsupportedAvatarIdErrorExample:
      summary: Invalid Avatar ID
      value:
        error_code: validation_error
        message: The requested 'avatarId' is not supported
    TTSRuntimeError:
      summary: Error Handling Response
      value:
        error_code: runtime_error
        message: Internal Server Error while receiving or handling response
    InputScriptAudioMissingOrInvalidErrorExample:
      summary: None of Text or URL
      value:
        error_code: validation_error
        message: Provide non-empty text in 'script' or a valid URL in 'source'
    InputScriptAudioMissingErrorExample:
      summary: None of Script or Audio
      value:
        error_code: validation_error
        message: Must specify either script or audio, both cannot be empty
    TasteExhaustedError:
      summary: Taste Exhausted
      value:
        error_code: taste_exhausted
        message: 'Unauthorized: Limited taste for user is exhausted.'
    INVALID_CROP_AREA_PARAMS:
      summary: Invalid value in crop area
      value:
        error_code: validation_error
        message: Invalid value in crop area params
    SuccessfulVoicesResponse:
      summary: Successful response with voices details
      value:
        voices:
        - voiceId: v123
          displayName: John Doe
          gender: M
          style: Professional
          voiceType: Nurse
          status: Active
          extendedPropertyMap: {}
          wordsPerMinute: '100'
          rolePlayList: []
          sampleURL: <pre-signed url for downloading the sample audio>
    ErrorBodyLegalReasons:
      summary: Legal Restrictions
      value:
        error_code: unauthorized_legal_reasons
        message: 'Unauthorized access: Legal restrictions prevent you from accessing this resource.'
    FormatIncompatibleWithBackground:
      summary: Incompatible Output Format
      value:
        error_code: validation_error
        message: The 'video/webm' output format can only be used when the background type is 'transparent'
    MissingBackgroundColorErrorExample:
      summary: Missing Background Color
      value:
        error_code: validation_error
        message: Background color must be specified for type 'color'
    PlainTextInputForAvatarGeneration:
      summary: Generate avatar using plain text
      value:
        script:
          text: <plain text>
          mediaType: text/plain
          localeCode: en-US
        voiceId: <voice id>
        avatarId: <avatar id>
        output:
          mediaType: video/mp4
    InvalidInputUrlErrorExample:
      summary: Invalid Input URL
      value:
        error_code: validation_error
        message: Invalid input 'url' specified
    ErrorBodyAPIKeyInvalid:
      summary: Api Key is invalid
      value:
        error_code: '403003'
        message: Api Key is invalid
    CROP_AREA_ASPECT_RATIO_NOT_SUPPORTED:
      summary: Aspect ratio in Crop
      value:
        error_code: validation_error
        message: ' Aspect ratio 16:9 is not maintained in crop width*height'
    TextLengthExceededForScriptErrorExample:
      summary: Input Text Too Long
      value:
        error_code: validation_error
        message: Input text has more than 20000 characters
    InvalidOutputFileFormatErrorExample:
      summary: Invalid Output Format
      value:
        error_code: validation_error
        message: Output file format is not valid
    ErrorBodyTooManyRequests:
      summary: Too many requests
      value:
        error_code: '429050'
        message: Too many requests
    MissingOutputErrorExample:
      summary: Missing Output Config
      value:
        error_code: validation_error
        message: Missing 'output' field in the payload
    PlainTextInputForAvatarGenerationUsingColorBackground:
      summary: Generate avatar using plain text and color background
      value:
        script:
          text: <plain text>
          mediaType: text/plain
          localeCode: en-US
        voiceId: <voice id>
        avatarId: <avatar id>
        output:
          mediaType: video/mp4
          background:
            type: color
            color: '#FFF000'
    ViolationError:
      summary: User Blocked Due To Violation
      value:
        error_code: user_blocked_due_to_violation
        message: 'Account blocked: Your account has been blocked due to a violation of terms.'
    UnsupportedVoiceIdErrorExample:
      summary: Invalid Voice ID
      value:
        error_code: validation_error
        message: The requested 'voiceId' is not supported
    UnsupportedShotTypeErrorExample:
      summary: Invalid Shot Type
      value:
        error_code: validation_error
        message: Shot Type is not supported.
    MissingAvatarIdErrorExample:
      summary: Missing Avatar ID
      value:
        error_code: validation_error
        message: The 'avatarId' property is required
    CROP_AREA_UNSUPPORTED_FOR_NON_IMAGE_VIDEO_BACKGROUND:
      summary: Crop area support
      value:
        error_code: validation_error
        message: Crop area supported only for image and video background
    ErrorBodyUnauthorized:
      summary: Invalid Token
      value:
        error_code: '401013'
        message: Oauth token is not valid
    InvalidRequestPayloadErrorExample:
      summary: Invalid TTS Request
      value:
        error_code: validation_error
        message: Text to speech service marked this request as invalid
    SourceUrlSourceTextConflictErrorExample:
      summary: Both URL and Text
      value:
        error_code: validation_error
        message: Both source url and source text is present in the request
    TextLengthTooShortForScriptErrorExample:
      summary: Input Text Too Short
      value:
        error_code: validation_error
        message: Input text has less than 15 characters
    SubmitRequestResponse:
      summary: Successful response with job details
      value:
        jobId: string
        statusUrl: string
    StudioAPIFailedEntitiesErrorResponse:
      summary: Error Fetching Entities
      value:
        error_code: runtime_error
        message: Error while fetching available entities
    ScriptInvalidTextSupportedRange:
      summary: Invalid Input Text
      value:
        error_code: validation_error
        message: Input contains unsupported characters. Please remove any Emojis or Symbols
    InputScriptAudioConflictErrorExample:
      summary: Both Script and Audio
      value:
        error_code: validation_error
        message: Must specify either script or audio, not both
    MissingBackgroundTypeErrorExample:
      summary: Missing Background Type
      value:
        error_code: validation_error
        message: 'Background type must be set to one of the following: ''image'', ''video'', ''color'', or ''transparent''.'
    StatusAPIFailedBackgroundFileResponse:
      summary: Failed Background File Download
      value:
        error_code: validation_error
        message: Error while downloading file from Background URL
    BackgroundSourceColorMissingErrorExample:
      summary: None of Background Source or Color
      value:
        error_code: validation_error
        message: Must specify either background source or color, both cannot be empty
    UserBlockedError:
      summary: User Blocked By Admin
      value:
        error_code: user_blocked_by_admin
        message: 'Access blocked: Your account has been blocked by an administrator.'
    UserProfileDeniedError:
      summary: User Profile Denied
      value:
        error_code: user_profile_denied
        message: 'User profile denied: Your profile does not meet the requirements for this action.'
    PlainTextInputForAvatarGenerationUsingVideoBackground:
      summary: Generate avatar using plain text and video background
      value:
        script:
          text: <plain text>
          mediaType: text/plain
          localeCode: en-US
        voiceId: <voice id>
        avatarId: <avatar id>
        output:
          mediaType: video/mp4
          background:
            type: video
            source:
              url: <pre-signed url of background video>
    TTSServiceSubmitError:
      summary: Error Submitting Request
      value:
        error_code: runtime_error
        message: Internal Server Error while submitting text to speech request
    BackgroundIncompatibleWithFormat:
      summary: Incompatible Background Type
      value:
        error_code: validation_error
        message: Transparent background is only supported for 'video/webm' output file format
    MissingBackgroundUrlErrorExample:
      summary: Missing Background URL
      value:
        error_code: validation_error
        message: Background URL must be specified for type 'video' or 'image'
    ScriptInvalidASCIIRange:
      summary: Non-ASCII Input Text
      value:
        error_code: validation_error
        message: Input contains unsupported characters. Please use only ASCII or extended ASCII.
    MediatypeIncompatibleForText:
      summary: Invalid Script Mediatype
      value:
        error_code: validation_error
        message: Provided text format is not valid for input mediaType
    RunTimeError:
      summary: Internal Server Error
      value:
        error_code: runtime_error
        message: Internal Server Error
    MissingAudioSourceErrorExample:
      summary: Missing Audio Source
      value:
        error_code: validation_error
        message: Audio source missing in payload
    PlainTextInputForAvatarGenerationUsingImageBackground:
      summary: Generate avatar using plain text and image background
      value:
        script:
          text: <plain text>
          mediaType: text/plain
          localeCode: en-US
        voiceId: <voice id>
        avatarId: <avatar id>
        output:
          mediaType: video/mp4
          background:
            type: image
            source:
              url: <pre-signed url of background image>
    MissingMediaTypeForOutputErrorExample:
      summary: Missing Output Mediatype
      value:
        error_code: validation_error
        message: Missing output 'mediaType' in payload
    MissingScriptErrorExample:
      summary: Missing Input Script
      value:
        error_code: validation_error
        message: Script missing in the payload
    InvalidBackgroundUrlErrorExample:
      summary: Invalid Background URL
      value:
        error_code: validation_error
        message: Invalid 'url' specified in background
    UserNotEntitledError:
      summary: User Not Entitled
      value:
        error_code: user_not_entitled
        message: 'User not entitled: You do not have the entitlement to perform this operation.'
    ErrorBodyAccessDenied:
      summary: Access Denied
      value:
        error_code: unauthorized_forbidden
        message: 'Access Denied: You do not have the necessary permissions to access this resource'
    InputFileFormatValidationErrorExample:
      summary: Invalid Input Format
      value:
        error_code: validation_error
        message: Input file format is not supported
    URLInputForAvatarGeneration:
      summary: Generate avatar using audio file
      value:
        audio:
          source:
            url: <pre-signed url of input audio>
          mediaType: audio/wav
          localeCode: en-US
        avatarId: <avatar id>
        output:
          mediaType: video/mp4
    URLTextInputForAvatarGeneration:
      summary: Generate avatar using text file
      value:
        script:
          source:
            url: <pre-signed url of text file>
          mediaType: text/plain
          localeCode: en-US
        voiceId: <voice id>
        avatarId: <avatar id>
        output:
          mediaType: video/mp4
    InvalidOrMissingLocaleCodeForScriptErrorExample:
      summary: Invalid Source Locale
      value:
        error_code: validation_error
        message: Invalid source locale code specified
    UnsupportedOutputResolution:
      summary: Invalid Output Resolution
      value:
        error_code: validation_error
        message: Unsupported resolution specified in output. Accepted values are [1920x1080, 3840x2160]
    QuotaExceededError:
      summary: Quota Exceeded
      value:
        error_code: quota_exhausted
        message: 'Quota exceeded: You have reached the maximum allowed usage for this service.'
    IncorrectVoiceNameErrorExample:
      summary: Invalid Voice Name
      value:
        error_code: validation_error
        message: The provided `voice name` is incorrect in the script text
    AccessError:
      summary: Access Error
      value:
        error_code: access_error
        message: Token not allowed in the current context
    InvalidSubscriptionError:
      summary: Invalid Subscription
      value:
        error_code: invalid_subscription
        message: 'Invalid subscription: Your subscription does not cover this service or feature.'
    MISSING_PARAMS_IN_CROP_AREA:
      summary: Missing params in crop area
      value:
        error_code: validation_error
        message: Missing params in crop area
  schemas:
    AvatarOutputObject:
      type: object
      description: Output configuration for avatar video generation.
      properties:
        mediaType:
          $ref: '#/components/schemas/SupportedOutputVideoFormat'
        background:
          oneOf:
          - $ref: '#/components/schemas/OutputColor'
          - $ref: '#/components/schemas/URLSource'
          type: object
          properties:
            type:
              $ref: '#/components/schemas/SupportedBackgroundType'
        resolution:
          type: object
          properties:
            width:
              type: string
            height:
              type: string
      required:
      - mediaType
    OutputColor:
      type: string
      title: Color background
      description: Color specification for avatar background.
      properties:
        color:
          type: string
          pattern: ^#[0-9a-fA-F]{6}$
          description: Color code for the background of the output. This should be a six digit hexadecimal value.
    URLObject:
      type: object
      description: URL object containing a pre-signed URL. See the [list of allowed domains for storage](https://developer.adobe.com/audio-video-firefly-services/getting-started/storage-solutions/).
      properties:
        url:
          type: string
          format: uri
          description: The pre-signed URL pointing to the resource to be used for avatar/speech generation.
    FailedResponse:
      type: object
      description: Generic error response object.
      properties:
        error_code:
          type: string
        message:
          type: string
    AvatarEntity:
      type: object
      description: Details of the avatar entity.
      properties:
        avatarId:
          type: string
          description: The unique ID for the avatar.
        displayName:
          type: string
          description: The displayed name for the avatar.
        gender:
          type: string
          description: The gender of the avatar.
        clothingStyle:
          type: string
          description: The clothing style worn by the avatar.
          enum:
          - Casual
          - Formal
          - Professional
        ageGroup:
          type: string
          description: The intended age bracket of the avatar.
          enum:
          - Young Adult
          - Middle Aged
          - Senior
        ethnicity:
          type: string
          description: The ethnicity of the avatar.
        style:
          type: string
          description: This property is used when the avatar wears a professional or region-specific costume (like Nurse, Doctor, Emergency Worker, Retail Worker, etc.).
        status:
          type: string
          description: This determines if the specific avatar ID is available for use. Deprecated avatars will have an Inactive status.
          enum:
          - Active
          - Inactive
        extendedPropertyMap:
          type: object
          properties:
            aspectRatio:
              type: object
              properties:
                x:
                  type: integer
                y:
                  type: integer
            resolution:
              type: object
              properties:
                width:
                  type: integer
                height:
                  type: integer
          description: This is a field for any additional properties for the avatar.
        thumbnailUrls:
          type: object
          properties:
            hd:
              type: string
              description: A pre-signed URL for downloading the high-resolution avatar thumbnail.
            lowRes:
              type: string
              description: A pre-signed URL for downloading the low-resolution avatar thumbnail.
        voiceId:
          type: string
          description: The unique ID for the voice.
        sampleVideo:
          type: object
          properties:
            webm:
              type: string
              description: A pre-signed URL for downloading avatar sample video in WEBM format.
            mp4:
              type: string
              description: A pre-signed URL for downloading avatar sample video in MP4 format.
    URLSource:
      type: object
      title: Image or video background
      properties:
        source:
          type: object
          properties:
            url:
              type: string
              format: uri
              description: The pre-signed URL pointing to the resource to be used for avatar/speech generation.
          description: Details of the source including a pre-signed URL. See the [list of allowed domains for storage](https://developer.adobe.com/audio-video-firefly-services/getting-started/storage-solutions/).
    SuccessfulAvatarsResponse:
      type: object
      description: List of available avatars.
      properties:
        avatars:
          type: array
          items:
            $ref: '#/components/schemas/AvatarEntity'
    SupportedLanguageCode:
      type: string
      enum:
      - en-US
      - es-ES
      - de-DE
      - fr-FR
      - da-DK
      - en-GB
      - en-IN
      - es-419
      - es-AR
      - fr-CA
      - hi-IN
      - it-IT
      - ja-JP
      - ko-KR
      - nb-NO
      - pt-BR
      - pt-PT
      - nl-NL
      - zh-CN
      - sv-SE
      description: The language code for the supported language desired in the result.
    SuccessfulVoicesResponse:
      type: object
      description: List of available voices.
      properties:
        voices:
          type: array
          items:
            $ref: '#/components/schemas/VoiceEntity'
    GenerateAvatarUsingPlainText:
      title: Using Plain Text
      type: object
      properties:
        script:
          oneOf:
          - $ref: '#/components/schemas/TextSource'
          - $ref: '#/components/schemas/URLSource'
          type: object
          properties:
            localeCode:
              $ref: '#/components/schemas/SupportedLanguageCode'
            mediaType:
              type: string
              enum:
              - text/plain
              description: The format of the text resource.
          required:
          - localeCode
          - mediaType
        voiceId:
          type: string
          description: ID of the voice to use from the catalog of voices.
        avatarId:
          type: string
          description: ID of the avatar to use from the catalog of avatars.
        output:
          $ref: '#/components/schemas/AvatarOutputObject'
      required:
      - voiceId
      - output
      - script
      - avatarId
    GenerateAvatarUsingAudioFile:
      title: Using Audio File
      type: object
      properties:
        audio:
          type: object
          properties:
            source:
              $ref: '#/components/schemas/URLObject'
            mediaType:
              type: string
              enum:
              - audio/wav
            localeCode:
              $ref: '#/components/schemas/SupportedLanguageCode'
          required:
          - localeCode
          - mediaType
          - source
        avatarId:
          type: string
          description: ID of the avatar to use from the catalog of avatars.
        output:
          $ref: '#/components/schemas/AvatarOutputObject'
      required:
      - output
      - audio
      - avatarId
    SupportedOutputVideoFormat:
      type: string
      enum:
      - video/mp4
      description: The supported video format for background video for Avatar.
    SubmitAPIResponse:
      type: object
      description: Response returned when a job is successfully submitted.
      properties:
        jobId:
          type: string
        statusUrl:
          type: string
    VoiceEntity:
      type: object
      description: Details of Voice Entity.
      properties:
        voiceId:
          type: string
          description: The unique ID for the voice.
        displayName:
          type: string
          description: The displayed name for the voice.
        gender:
          type: string
          description: The gender of the voice.
        style:
          type: string
          description: The speaking style of the voice.
          enum:
          - Casual
          - Excited
        voiceType:
          type: string
          description: Not applicable at this time.
        status:
          type: string
          description: This determines if the specific voice ID is available for use. Deprecated voices will have an Inactive status.
          enum:
          - Active
          - Inactive
        extendedPropertyMap:
          type: object
          description: This is a field for any additional properties for the voice.
        wordsPerMinute:
          type: string
          description: The speed of speaking, in words per minute.
        rolePlayList:
          type: array
          description: Not applicable at this time.
          items:
            type: string
        sampleURL:
          type: string
          description: A pre-signed URL for downloading the sample audio.
    SupportedBackgroundType:
      type: string
      enum:
      - color
      - video
      - image
      description: Supported background type for output Avatar video.
    TextSource:
      description: Details of the text resource.
      type: string
      properties:
        text:
          type: string
    AvatarRequest:
      type: object
      oneOf:
      - $ref: '#/components/schemas/GenerateAvatarUsingPlainText'
      - $ref: '#/components/schemas/GenerateAvatarUsingAudioFile'
  securitySchemes:
    AccessToken:
      type: http
      scheme: bearer
      description: The Adobe-generated access token, S2S format.
    X-Api-Key:
      type: apiKey
      name: x-api-key
      in: header
      description: The client ID for authentication.