openapi: 3.0.1
info:
  title: Argil API
  description: API for AI clone video generation
  version: 1.0.0
  license:
    name: MIT
servers:
  - url: https://api.argil.ai/v1
security:
  - ApiKeyAuth: []
paths:
  /voices:
    get:
      summary: List all voices
      description: Returns an array of Voice objects available for the user
      parameters:
        - name: language
          in: query
          description: Filter voices by language
          required: false
          schema:
            $ref: "#/components/schemas/VoiceLanguage"
        - name: gender
          in: query
          description: Filter voices by gender
          required: false
          schema:
            $ref: "#/components/schemas/VoiceGender"
        - name: visibility
          in: query
          description: "Filter by visibility. 'public' returns only Argil's public voices, 'private' returns only your workspace's custom voices. Omit to return both."
          required: false
          schema:
            type: string
            enum:
              - public
              - private
      responses:
        200:
          description: An array of voices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Voice"
        400:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create a voice from audio
      description: |
        Creates a custom voice by cloning from an audio file.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VoiceCreateArgs"
            examples:
              minimax_default:
                summary: Create voice with default Minimax model
                value:
                  name: "My Custom Voice"
                  audioUrl: "https://example.com/my-audio.mp3"
              minimax_with_settings:
                summary: Create voice with Minimax settings
                value:
                  name: "My Custom Voice"
                  audioUrl: "https://example.com/my-audio.mp3"
                  modelId: "speech-2.8-hd"
                  settings:
                    voiceSpeed: 1.1
                    languageBoost: "English"
                    emotion: "happy"
                  language: "ENGLISH"
                  gender: "MALE"
              elevenlabs:
                summary: Create voice with ElevenLabs model
                value:
                  name: "My Custom Voice"
                  audioUrl: "https://example.com/my-audio.mp3"
                  modelId: "eleven_multilingual_v2"
                  settings:
                    voiceStability: 0.8
                    voiceSimilarity: 0.5
                    voiceStyle: 0.0
                    voiceSpeed: 1.0
                    speakerBoost: true
              elevenlabs_v3:
                summary: Create voice with ElevenLabs V3 model
                value:
                  name: "My Custom Voice"
                  audioUrl: "https://example.com/my-audio.mp3"
                  modelId: "eleven_v3"
                  settings:
                    voiceStability: 0.5
      responses:
        201:
          description: Voice created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Voice"
        400:
          description: Validation error (invalid audio, quota exceeded, etc.)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /voices/{id}:
    get:
      summary: Get a Voice by id
      description: Returns a single Voice identified by its id
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            description: The id of the Voice to retrieve
      responses:
        200:
          description: Detailed information about the Voice
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Voice"
        404:
          description: Voice not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /voices/sync:
    post:
      summary: Sync voices from connected providers
      description: |
        Re-syncs the voices imported from your connected ElevenLabs or Minimax provider accounts.

        After the sync completes, you can call `GET /voices` to retrieve the updated list.

        You must have at least one voice provider connected to your workspace before calling this endpoint.
        Providers can be connected from the Argil dashboard under the Voices page.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                providerName:
                  type: string
                  enum:
                    - ELEVEN_LABS
                    - MINIMAX
                  description: "Optional. Sync only this provider. If omitted, all connected voice providers are synced."
            examples:
              sync_all:
                summary: Sync all connected providers
                value: {}
              sync_elevenlabs:
                summary: Sync only ElevenLabs
                value:
                  providerName: "ELEVEN_LABS"
              sync_minimax:
                summary: Sync only Minimax
                value:
                  providerName: "MINIMAX"
      responses:
        200:
          description: Sync triggered successfully. Returns the list of providers being synced.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SyncedProvider"
        404:
          description: No connected voice providers found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        400:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /avatars:
    get:
      summary: List all avatars
      description: Returns an array of Avatar objects available for the user
      parameters:
        - name: orientation
          in: query
          description: Filter avatars by orientation
          required: false
          schema:
            $ref: "#/components/schemas/AvatarOrientation"
        - name: model
          in: query
          description: Filter avatars by model type
          required: false
          schema:
            $ref: "#/components/schemas/AvatarModel"
        - name: visibility
          in: query
          description: "Filter by visibility. 'public' returns only Argil's public avatars, 'private' returns only your workspace's custom avatars. Omit to return both."
          required: false
          schema:
            type: string
            enum:
              - public
              - private
      responses:
        200:
          description: An array of avatars
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Avatar"
        400:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create a new Avatar
      description: |
        Creates a new avatar.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AvatarCreateArgsImage"
            examples:
              image_url:
                summary: Create avatar from image URL
                value:
                  type: "IMAGE"
                  name: "My Image Avatar"
                  datasetImage:
                    url: "https://example.com/avatar-image.jpg"
                  voiceId: "123e4567-e89b-12d3-a456-426614174000"
              image_base64:
                summary: Create avatar from base64 image
                value:
                  type: "IMAGE"
                  name: "My Image Avatar"
                  datasetImage:
                    base64: "data:image/png;base64,iVBORw0KGgoAAAANS..."
              image_with_voice_design:
                summary: Create avatar with automatic voice design
                value:
                  type: "IMAGE"
                  name: "My Image Avatar"
                  datasetImage:
                    url: "https://example.com/avatar-image.jpg"
              image_with_callback:
                summary: Create avatar with per-request callback
                value:
                  type: "IMAGE"
                  name: "My Image Avatar"
                  datasetImage:
                    url: "https://example.com/avatar-image.jpg"
                  callbackUrl: "https://your-server.com/avatar-ready"
      responses:
        201:
          description: Successfully created Avatar. The training process will start automatically.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Avatar"
        400:
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /avatars/{id}:
    get:
      summary: Get an Avatar by id
      description: Returns a single Avatar identified by its id
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            description: The id of the Avatar to retrieve
      responses:
        200:
          description: Detailed information about the Avatar
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Avatar"
        404:
          description: Avatar not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /videos:
    get:
      summary: Paginated list of Videos
      description: Returns a paginated array of Videos
      parameters:
        - name: page
          in: query
          description: Page number of the video list
          required: false
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Number of videos per page
          required: false
          schema:
            type: integer
            default: 10
        - name: nameSearchQuery
          in: query
          description: Filter videos by name, case-insensitive substring match.
          required: false
          schema:
            type: string
        - name: avatarId
          in: query
          description: Filter videos by avatar ID.
          required: false
          schema:
            type: string
        - name: voiceId
          in: query
          description: Filter videos by voice ID.
          required: false
          schema:
            type: string
        - name: extrasFilter
          in: query
          description: A JSON string representing filters to apply on the extras JSON field. Must be a valid JSON object as a string, specifying properties and values to match.
          required: false
          schema:
            type: string
            example: '{"X_ID": "YOUR_CUSTOM_ID"}'
      responses:
        200:
          description: A paginated list of Videos
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalItems:
                    type: integer
                    description: Total number of videos available
                  totalPages:
                    type: integer
                    description: Total number of pages
                  currentPage:
                    type: integer
                    description: Current page number
                  itemsPerPage:
                    type: integer
                    description: Number of items per page
                  videos:
                    type: array
                    items:
                      $ref: "#/components/schemas/Video"
        400:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create a new Video
      description: Creates a new Video with the specified details
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VideoCreateArgs"
      responses:
        201:
          description: Successfully created Video
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Video"
        400:
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /videos/{id}:
    get:
      summary: Get a Video by id
      description: Returns a single Video identified by its id
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            description: The id of the Video to retrieve
      responses:
        200:
          description: Detailed information about the Video
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Video"
        404:
          description: Video not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: Delete a Video by id
      description: Delete a single Video identified by its id
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            description: The id of the Video to delete
      responses:
        200:
          description: Success message.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        404:
          description: Video not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /videos/{id}/render:
    post:
      summary: Render a Video by id
      description: Returns a single Video object, with its updated status and information
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            description: The id of the Video to render
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                callbackUrl:
                  type: string
                  format: uri
                  description: >
                    Optional HTTPS URL to receive a one-shot webhook notification when this specific render completes (success or fail).
                    The callback is fired once and then discarded.
                  example: "https://example.com/hooks/argil-render"
      responses:
        200:
          description: Detailed information about the Video
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Video"
        400:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Video not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /assets:
    get:
      summary: List audio assets
      description: Returns an array of audio assets available for the user
      responses:
        200:
          description: An array of audio assets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Asset"
        400:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /assets/{id}:
    get:
      summary: Get an Asset by id
      description: Returns a single Asset identified by its id
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            description: The id of the Asset to retrieve
      responses:
        200:
          description: Detailed information about the Asset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Asset"
        404:
          description: Asset not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /subtitles:
    get:
      summary: List subtitle styles
      description: Returns a paginated array of subtitle styles available for the user
      parameters:
        - name: page
          in: query
          description: Page number of the subtitle styles list
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          description: Number of subtitle styles per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        200:
          description: A paginated list of subtitle styles
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/SubtitleStyle"
                  totalItems:
                    type: integer
                    description: Total number of subtitle styles available
                  totalPages:
                    type: integer
                    description: Total number of pages
                  currentPage:
                    type: integer
                    description: Current page number
                  itemsPerPage:
                    type: integer
                    description: Number of items per page
        400:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /subtitles/videos/{videoProjectId}/export:
    get:
      summary: Export subtitles for a video project
      description: Exports subtitles for a video project in VTT or ASS format. The subtitles can optionally include styling information.
      parameters:
        - name: videoProjectId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: The UUID of the video project to export subtitles for
        - name: format
          in: query
          description: Subtitle format to export (vtt or ass)
          required: false
          schema:
            type: string
            enum: [vtt, ass]
            default: vtt
        - name: includeStyling
          in: query
          description: Whether to include styling information in the exported subtitles
          required: false
          schema:
            type: boolean
            default: false
      responses:
        200:
          description: Subtitle file content
          content:
            text/vtt:
              schema:
                type: string
                description: VTT subtitle file content
            text/x-ass:
              schema:
                type: string
                description: ASS subtitle file content
          headers:
            Content-Type:
              description: Content type of the response (text/vtt or text/x-ass)
              schema:
                type: string
            Content-Disposition:
              description: Attachment header with filename
              schema:
                type: string
        400:
          description: Validation error or invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Video project not found or user does not have access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /webhooks:
    post:
      summary: Create a new webhook
      description: Creates a new webhook with the specified details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - callbackUrl
                - events
              properties:
                callbackUrl:
                  type: string
                  description: URL to which the webhook will send POST requests.
                events:
                  $ref: "#/components/schemas/WebhookEventSchema"
              additionalProperties: false
      responses:
        201:
          description: Successfully created webhook
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Webhook"
        400:
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      summary: Retrieve all webhooks
      description: Retrieves all webhooks for the authenticated user.
      responses:
        200:
          description: An array of webhooks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Webhook"
        400:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /webhooks/{id}:
    put:
      summary: Update a webhook
      description: Updates the specified details of an existing webhook.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                callbackUrl:
                  type: string
                events:
                  $ref: "#/components/schemas/WebhookEventSchema"
              additionalProperties: false
      responses:
        200:
          description: Successfully updated webhook
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Webhook"
        400:
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: Delete a webhook
      description: Deletes a single webhook identified by its ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        204:
          description: Successfully deleted webhook
        404:
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    Voice:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        status:
          type: string
        sampleUrl:
          type: string
        language:
          allOf:
            - $ref: "#/components/schemas/VoiceLanguage"
            - nullable: true
        gender:
          allOf:
            - $ref: "#/components/schemas/VoiceGender"
            - nullable: true
    AvatarCreateArgsVideo:
      deprecated: true
      type: object
      required:
        - name
        - type
        - datasetVideo
        - consentVideo
      properties:
        type:
          type: string
          enum: ["VIDEO"]
          description: "Avatar creation type - must be 'VIDEO' for video-based avatars. DEPRECATED: This method will be removed in a future version."
        name:
          type: string
          description: "Name of the avatar"
          minLength: 1
          maxLength: 256
        datasetVideo:
          type: object
          required:
            - url
          properties:
            url:
              type: string
              format: uri
              pattern: ^https://.*
              description: "HTTPS URL to the source video for training. Must be 1-5 minutes long, in MP4 or MOV format, resolution between 720p and 4K. Max size 1.5GB."
          additionalProperties: false
        consentVideo:
          type: object
          required:
            - url
          properties:
            url:
              type: string
              format: uri
              pattern: ^https://.*
              description: "HTTPS URL to the consent video recording. Must be 30 seconds or less, in MP4 or MOV format. Max size 100MB."
          additionalProperties: false
        extras:
          type: object
          description: "Optional dictionary of custom key-value pairs to extend the avatar metadata. Maximum of 10 key-value pairs of 256 characters allowed"
          additionalProperties:
            type: string
          maxProperties: 10
      additionalProperties: false
    AvatarCreateArgsImage:
      type: object
      required:
        - name
        - type
        - datasetImage
      properties:
        type:
          type: string
          enum: ["IMAGE"]
          description: "Avatar creation type - must be 'IMAGE' for image-based avatars"
        name:
          type: string
          description: "Name of the avatar"
          minLength: 1
          maxLength: 256
        datasetImage:
          description: "Image source for avatar creation. Either 'url' or 'base64' must be provided."
          oneOf:
            - type: object
              title: "Image URL"
              required:
                - url
              properties:
                url:
                  type: string
                  format: uri
                  pattern: ^https://.*
                  description: |
                    HTTPS URL to the source image for training. Must meet the following requirements:
                    - Format: PNG, JPEG, or WEBP
                    - Resolution: Between 720p (1280x720 or 720x1280) and 4K (3840x2160 or 2160x3840)
                    - Aspect ratio: 16:9 (landscape) or 9:16 (portrait)
                    - Max size: 10MB
              additionalProperties: false
            - type: object
              title: "Base64 Image"
              required:
                - base64
              properties:
                base64:
                  type: string
                  pattern: ^data:image/(png|jpeg|jpg|webp);base64,.*
                  description: |
                    Base64-encoded image data. Must be in format: data:image/{format};base64,{data}
                    - Format: PNG, JPEG, or WEBP
                    - Resolution: Between 720p (1280x720 or 720x1280) and 4K (3840x2160 or 2160x3840)
                    - Aspect ratio: 16:9 (landscape) or 9:16 (portrait)
                    - Max size: 10MB
              additionalProperties: false
        voiceId:
          type: string
          format: uuid
          description: |
            Optional voice ID to use for this avatar. If not provided, a voice design will be automatically created from the image.
        callbackUrl:
          type: string
          format: uri
          pattern: ^https://.*
          description: |
            Optional HTTPS URL that receives a one-shot POST notification when avatar training completes or fails.
            On success, sends `{ "event": "AVATAR_TRAINING_SUCCESS", "data": { "avatarId", "avatarName", "voiceId", "message" } }`.
            On failure (after all retries), sends `{ "event": "AVATAR_TRAINING_FAILED", "data": { "avatarId", "avatarName", "message" } }`.
        extras:
          type: object
          description: "Optional dictionary of custom key-value pairs to extend the avatar metadata. Maximum of 10 key-value pairs of 256 characters allowed"
          additionalProperties:
            type: string
          maxProperties: 10
      additionalProperties: false
    AvatarStatus:
      type: string
      enum:
        - NOT_TRAINED
        - TRAINING
        - TRAINING_FAILED
        - IDLE
        - REFUSED
      description: |
        * NOT_TRAINED - Initial state after VIDEO mode avatar creation (before training starts)
        * TRAINING - Avatar is currently training. For IMAGE mode avatars, this is the initial status after creation.
        * TRAINING_FAILED - Training process failed
        * IDLE - Avatar is ready to use
        * REFUSED - Avatar was refused by moderation
    Avatar:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        actorName:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        gestures:
          type: array
          description: "A list of labelized gestures available for your avatar."
          items:
            type: object
            properties:
              label:
                type: string
                description: "A label for user readability. Can be setup from the app's UI."
              slug:
                type: string
                description: "Allows identifying the gesture when using it for a specific moment."
              startFrame:
                type: number
                description: "The startFrame of the source Avatar video to be used as start for the video template."
        status:
          $ref: "#/components/schemas/AvatarStatus"
        width:
          type: integer
        height:
          type: integer
        thumbnailUrl:
          type: string
          description: "The url of the thumbnail of the avatar (low resolution)."
        coverImageUrl:
          type: string
          description: "The url of the cover image of the avatar (high resolution)."
        extras:
          type: object
          description: "A dictionary of custom key-value pairs to extend the Avatar metadata. Maximum of 5 key-value pairs of 256 characters allowed."
          additionalProperties:
            type: string
          maxProperties: 10
        orientation:
          $ref: "#/components/schemas/AvatarOrientation"
        model:
          $ref: "#/components/schemas/AvatarModel"
    Video:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        status:
          type: string
          description: "Can be either `IDLE`, `GENERATING_AUDIO`, `GENERATING_VIDEO`, `DONE` or `FAILED`."
        moments:
          type: array
          description: "An array of Moment items, each representing a portion of the complete video."
          items:
            type: object
            properties:
              transcript:
                type: string
                description: "A portion of the complete transcript. Current limit: 250 characters."
              avatarId:
                type: string
                description: "The id of the avatar to be used for this moment."
              voiceId:
                type: string
                description: "The id of the voice to be used for this moment."
              audioUrl:
                type: string
                description: "The audio that will be used for the video rendering. Automatically generated from the transcript when not provided. Current limit: 40 seconds."
              videoUrl:
                type: string
                description: "The url of the avatar rendering video for this moment."
              gestureSlug:
                type: string
                description: "The slug identifier of the gesture to be used for this moment."
        videoUrl:
          type: string
          description: "The url of the final avatar rendering video, containing all the moments merged."
        videoUrlSubtitled:
          type: string
          description: "The url of the final avatar rendering video with subtitles. Only available if subtitles are enabled."
        previewUrl:
          type: string
          description: "Url to the embedable preview of the video. Can be watched from web browsers or integrated in other websites before launching the generation. For embedable mode, add ?embed=true to the url."
        aspectRatio:
          type: string
          enum: ["16:9", "9:16"]
          description: "The aspect ratio of the video output: 16:9 or 9:16."
        subtitles:
          type: object
          properties:
            enable:
              type: boolean
          description: "Subtitles settings for the video"
        extras:
          type: object
          description: "A dictionary of custom key-value pairs to extend the video metadata. Maximum of 5 key-value pairs of 256 characters allowed."
          additionalProperties:
            type: string
          maxProperties: 10
    VideoCreateArgs:
      type: object
      required:
        - name
        - moments
      properties:
        name:
          type: string
        moments:
          type: array
          description: "An array of Moment items, each representing a portion of the complete video."
          items:
            type: object
            description: "A video moment. Exactly one of `transcript` or `audioUrl` must be provided — they are mutually exclusive."
            required:
              - avatarId
            properties:
              transcript:
                type: string
                description: "A portion of the complete transcript. Mutually exclusive with `audioUrl` — provide one or the other, not both. Current limit: 250 characters"
              audioUrl:
                type: string
                description: "URL to an audio file for this moment, bypassing TTS generation. Mutually exclusive with `transcript` — provide one or the other, not both. Max duration: 40 seconds"
              avatarId:
                type: string
                description: "The id of the avatar to be used for this moment"
              voiceId:
                type: string
                description: "The id of the voice to be used for this moment. Optional, default is the avatar's voice."
              voiceModel:
                type: string
                description: |
                  Optional override for the voice's default TTS model. Must be compatible with the voice's provider.
                  ElevenLabs voices: eleven_multilingual_v2, eleven_multilingual_v1, eleven_monolingual_v1, eleven_turbo_v2, eleven_turbo_v2_5, eleven_flash_v2_5, eleven_v3
                  Minimax voices: speech-02-hd, speech-02-turbo, speech-2.5-hd, speech-2.5-turbo, speech-2.6-hd, speech-2.6-turbo, speech-2.8-hd, speech-2.8-turbo
              gestureSlug:
                type: string
                description: "The slug identifier of the gesture to be used for this moment"
              zoom:
                type: object
                description: "Controls the zoom level of the viewport/display, allowing content to be scaled larger or smaller"
                required:
                  - level
                properties:
                  level:
                    type: number
                    minimum: 1.0
                    maximum: 2.0
                    default: 1.0
                    description: "Specifies the zoom scaling factor where 1.0 represents 100% (original size), and 2.0 is 200% (zoomed in)"
                additionalProperties: false
              broll:
                $ref: '#/components/schemas/MomentBroll'
            additionalProperties: false
        subtitles:
          type: object
          properties:
            enable:
              type: boolean
            styleId:
              type: string
              description: "ID of the subtitle style to apply. Styles can be fetched from the /subtitles endpoint."
            position:
              type: string
              enum: ["Top", "Middle", "Bottom"]
              description: "Position of subtitles on the video"
            size:
              type: string
              enum: ["Small", "Medium", "Large"]
              description: "Size of the subtitle text"
          required:
            - enable
          additionalProperties: false
          description: "Subtitles settings for the video"
        aspectRatio:
          type: string
          enum: ["16:9", "9:16"]
          description: "Select desired output aspectRatio: 16:9 or 9:16. Optional, default depends on used avatar."
        enableAutoBrolls:
          type: boolean
          description: "[DEPRECATED] Enable automatic B-roll generation and placement. When enabled, the system will analyze your content and automatically add relevant B-rolls to appropriate moments."
        autoBrolls:
          type: object
          description: "Configuration for automatic B-roll generation and placement."
          properties:
            enable:
              type: boolean
              description: "Enable or disable automatic B-roll generation."
            source:
              type: string
              enum:
                ["GENERATION", "GOOGLE_IMAGES", "STOCKS_VIDEO", "AVATAR_ACTION"]
              description: "Source for B-rolls: 'GENERATION' for generated images or 'GOOGLE_IMAGES' for images from Google, 'STOCKS_VIDEO' for GettyImages videos or 'AVATAR_ACTION' for generated videos including the avatar (only available with AI Influencer avatars)."
            intensity:
              type: string
              enum: ["LOW", "MEDIUM", "HIGH"]
              description: "Intensity level of B-rolls: 'LOW', 'MEDIUM', or 'HIGH'. Not available for 'AVATAR_ACTION' source."
            layout:
              type: string
              enum:
                [
                  "FULLSCREEN",
                  "AVATAR_BOTTOM_LEFT",
                  "AVATAR_BOTTOM_RIGHT",
                  "AVATAR_TOP_LEFT",
                  "AVATAR_TOP_RIGHT",
                  "SPLIT_AVATAR_LEFT",
                  "SPLIT_AVATAR_RIGHT",
                  "SPLIT_AVATAR_TOP",
                  "SPLIT_AVATAR_BOTTOM",
                  "BACKGROUND",
                ]
              description: "Layout control for moments containing a B-roll. Controls how the B-rolls appears relative to the avatar."
          required:
            - enable
            - source
            - intensity
        extras:
          type: object
          description: "Optional dictionary of custom key-value pairs to extend the video metadata. Maximum of 5 key-value pairs of 256 characters allowed"
          additionalProperties:
            type: string
          maxProperties: 10
        backgroundMusic:
          type: object
          description: "Optional configuration for background music"
          properties:
            assetId:
              type: string
              description: "ID of an audio asset to use as background music"
            volume:
              type: number
              description: "Volume level of the background music (0-1). Default is 0.14"
              minimum: 0
              maximum: 1
          required:
            - assetId
        model:
          type: string
          enum: [ARGIL_V1, ARGIL_ATOM]
          description: "Model to use for the video generation."
    BrollLayout:
      type: string
      enum:
        [
          "FULLSCREEN",
          "AVATAR_BOTTOM_LEFT",
          "AVATAR_BOTTOM_RIGHT",
          "AVATAR_TOP_LEFT",
          "AVATAR_TOP_RIGHT",
          "SPLIT_AVATAR_LEFT",
          "SPLIT_AVATAR_RIGHT",
          "SPLIT_AVATAR_TOP",
          "SPLIT_AVATAR_BOTTOM",
          "BACKGROUND",
        ]
      description: "Layout controlling how the B-roll appears relative to the avatar."
    MomentBroll:
      description: |
        Per-moment B-roll configuration. Specify the B-roll type and optional parameters for an individual moment.

        When `prompt` or `query` is omitted, it is auto-generated from the moment's transcript via LLM.
      oneOf:
        - type: object
          title: AVATAR_ACTION
          description: "Generate a video B-roll featuring the avatar in action. Only available with AI Influencer (IMAGE-type) avatars. Consumes 10 image generation credits per moment."
          required:
            - type
          properties:
            type:
              type: string
              enum: [AVATAR_ACTION]
            prompt:
              type: string
              description: "Describes the avatar's action. Auto-generated from the moment's transcript when omitted."
            layout:
              $ref: '#/components/schemas/BrollLayout'
          additionalProperties: false
        - type: object
          title: GENERATION
          description: "Generate an AI image as a B-roll. Consumes 10 image generation credits per moment."
          required:
            - type
          properties:
            type:
              type: string
              enum: [GENERATION]
            prompt:
              type: string
              description: "Describes the image to generate. Auto-generated from the moment's transcript when omitted."
            animate:
              type: boolean
              description: "Animate the generated image. Default: false."
            layout:
              $ref: '#/components/schemas/BrollLayout'
          additionalProperties: false
        - type: object
          title: STOCKS_VIDEO
          description: "Use a Getty Images stock video as a B-roll."
          required:
            - type
          properties:
            type:
              type: string
              enum: [STOCKS_VIDEO]
            query:
              type: string
              description: "Search query for Getty Images. Auto-generated from the moment's transcript when omitted."
            layout:
              $ref: '#/components/schemas/BrollLayout'
          additionalProperties: false
        - type: object
          title: GOOGLE_IMAGES
          description: "Use a Google Images result as a B-roll."
          required:
            - type
          properties:
            type:
              type: string
              enum: [GOOGLE_IMAGES]
            query:
              type: string
              description: "Search query for Google Images. Auto-generated from the moment's transcript when omitted."
            animate:
              type: boolean
              description: "Animate the found image. Default: false."
            layout:
              $ref: '#/components/schemas/BrollLayout'
          additionalProperties: false
      discriminator:
        propertyName: type
    Asset:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
          enum: [AUDIO]
        fileUrl:
          type: string
          description: "URL to access the asset"
    SubtitleStyle:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: "Unique identifier of the subtitle style"
        name:
          type: string
          description: "Name of the subtitle style"
    Webhook:
      type: object
      properties:
        id:
          type: string
          format: uuid
        callbackUrl:
          type: string
        events:
          $ref: "#/components/schemas/WebhookEventSchema"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        lastTriggeredAt:
          type: string
          format: date-time
    SyncedProvider:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: "The provider connection ID"
        providerName:
          type: string
          enum:
            - ELEVEN_LABS
            - MINIMAX
          description: "The voice provider name"
        connectionName:
          type: string
          nullable: true
          description: "The user-defined connection name"
        syncStatus:
          type: string
          enum:
            - SYNCING
          description: "Status of the sync (will be SYNCING after this call)"
    Error:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Success:
      type: object
      properties:
        message:
          type: string
    WebhookEventSchema:
      type: array
      description: List of events the webhook is subscribing to.
      items:
        type: string
        enum:
          - AVATAR_TRAINING_SUCCESS
          - AVATAR_TRAINING_FAILED
          - VIDEO_GENERATION_SUCCESS
          - VIDEO_GENERATION_FAILED
      minItems: 1
    VoiceLanguage:
      type: string
      enum:
        - ENGLISH
        - SPANISH
        - FRENCH
        - PORTUGUESE
        - GERMAN
        - RUSSIAN
        - HINDI
        - CHINESE
        - DUTCH
        - ARABIC
        - POLISH
        - BULGARIAN
        - JAPANESE
        - ITALIAN
    VoiceGender:
      type: string
      enum:
        - MALE
        - FEMALE
    AvatarOrientation:
      type: string
      enum:
        - ASPECT_RATIO_16_9
        - ASPECT_RATIO_9_16
    AvatarModel:
      type: string
      enum:
        - ARGIL_V1
        - ARGIL_ATOM
    Visibility:
      type: string
      enum:
        - public
        - private
      description: "Filter resources by visibility scope"
    VoiceModelId:
      type: string
      description: "Voice model to use for TTS. Determines which provider (ElevenLabs or Minimax) and which settings are available."
      enum:
        - eleven_multilingual_v2
        - eleven_multilingual_v1
        - eleven_monolingual_v1
        - eleven_turbo_v2
        - eleven_turbo_v2_5
        - eleven_flash_v2_5
        - eleven_v3
        - speech-02-hd
        - speech-02-turbo
        - speech-2.5-hd-preview
        - speech-2.5-turbo-preview
        - speech-2.6-hd
        - speech-2.6-turbo
        - speech-2.8-hd
        - speech-2.8-turbo
    MinimaxEmotion:
      type: string
      enum:
        - auto
        - happy
        - sad
        - angry
        - fearful
        - disgusted
        - surprised
        - neutral
    MinimaxLanguageBoost:
      type: string
      enum:
        - auto
        - Afrikaans
        - Arabic
        - Bulgarian
        - Catalan
        - Chinese
        - "Chinese,Yue"
        - Croatian
        - Czech
        - Danish
        - Dutch
        - English
        - Filipino
        - Finnish
        - French
        - German
        - Greek
        - Hebrew
        - Hindi
        - Hungarian
        - Indonesian
        - Italian
        - Japanese
        - Korean
        - Malay
        - Norwegian
        - Nynorsk
        - Persian
        - Polish
        - Portuguese
        - Romanian
        - Russian
        - Slovak
        - Slovenian
        - Spanish
        - Swedish
        - Tamil
        - Thai
        - Turkish
        - Ukrainian
        - Vietnamese
    VoiceSettings:
      type: object
      description: "Model-specific voice settings. Available fields depend on the chosen modelId. See the Settings by Model section for details."
      properties:
        voiceStability:
          type: number
          minimum: 0
          maximum: 1
          description: "ElevenLabs only. Voice stability (0-1). Default: 0.8 (0.5 for eleven_v3)"
        voiceSimilarity:
          type: number
          minimum: 0
          maximum: 1
          description: "ElevenLabs only. Clarity + similarity (0-1). Default: 0.5"
        voiceStyle:
          type: number
          minimum: 0
          maximum: 1
          description: "ElevenLabs only. Style exaggeration (0-1). Default: 0.0"
        voiceSpeed:
          type: number
          minimum: 0.7
          maximum: 1.2
          description: "ElevenLabs and Minimax. Playback speed (0.7-1.2). Default: 1.0"
        speakerBoost:
          type: boolean
          description: "ElevenLabs only (not available for eleven_v3). Enable speaker boost. Default: true"
        languageBoost:
          $ref: "#/components/schemas/MinimaxLanguageBoost"
        emotion:
          $ref: "#/components/schemas/MinimaxEmotion"
    VoiceCreateArgs:
      type: object
      required:
        - name
        - audioUrl
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: "Name of the voice"
        audioUrl:
          type: string
          format: uri
          pattern: ^https://.*
          description: "HTTPS URL to the audio file for voice cloning (MP3, WAV, M4A). Duration must be between 30 seconds and 4 minutes."
        modelId:
          $ref: "#/components/schemas/VoiceModelId"
        settings:
          $ref: "#/components/schemas/VoiceSettings"
        language:
          $ref: "#/components/schemas/VoiceLanguage"
        gender:
          $ref: "#/components/schemas/VoiceGender"
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: "API key to be included in the x-api-key header"