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"
      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"
  /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"
  /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"
      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"
      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
      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"
  /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.
        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: 20 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."
        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
            required:
              - transcript
              - avatarId
            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. Optional, default is the avatar's voice."
              gestureSlug:
                type: string
                description: "The slug identifier of the gesture to be used for this moment"
              audioUrl:
                type: string
                description: "Optional url to the audio to be used for the video rendering, for bypassing our audio generation model. Current limit: 20 seconds"
              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
            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."
    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
    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
        - BRAZILIAN_PORTUGUESE
        - GERMAN
        - RUSSIAN
        - HINDI
        - CHINESE
        - DUTCH
        - ARABIC
    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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: "API key to be included in the x-api-key header"