openapi: 3.1.0
info:
  title: HeyGen Account Videos API
  version: 4.0.8
  description: OpenAPI specification for the HeyGen API endpoints referenced across the documentation.
servers:
- url: https://api.heygen.com
security:
- ApiKeyAuth: []
tags:
- name: Videos
  description: Video generation, retrieval, and management endpoints.
paths:
  /v1/video_status.get:
    get:
      summary: Retrieve Video Status/Details
      description: This endpoint allows you to retrieve the status and details of a specific video.
      operationId: video-status
      parameters:
      - name: video_id
        in: query
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: "{\n  \"code\": 400,\n  \"message\": \"Invlid parameters\"\n}"
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                    default: 0
                  message:
                    type: string
                    example: Invlid parameters
      deprecated: false
      x-mint:
        href: /reference/video-status
      tags:
      - Videos
      security:
      - ApiKeyAuth: []
  /v1/video.delete:
    delete:
      summary: Delete a Video
      description: ''
      operationId: delete-a-video
      parameters:
      - name: video_id
        in: query
        description: id of the video you want to delete
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: '{"code": 100, "data": null, "msg": null}'
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 100
                    default: 0
                  data: {}
                  msg: {}
        '404':
          description: '404'
          content:
            application/json:
              examples:
                Result:
                  value: '{"code":40104,"message":"Video not found"}'
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 40104
                    default: 0
                  message:
                    type: string
                    example: Video not found
      deprecated: false
      x-mint:
        href: /reference/delete-a-video
      tags:
      - Videos
      security:
      - ApiKeyAuth: []
  /v2/video/generate:
    post:
      summary: Create Avatar Video (V2)
      description: This API now generates videos with our New AI Studio backend.
      operationId: create-an-avatar-video-v2
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - dimension
              - video_inputs
              properties:
                caption:
                  type: boolean
                  description: Whether to add a caption to the video.
                  default: false
                title:
                  type: string
                  description: Title of this video
                callback_id:
                  type: string
                  description: A custom ID for callback purposes.
                dimension:
                  type: object
                  properties:
                    width:
                      type: integer
                      default: 1280
                      format: int32
                    height:
                      type: integer
                      default: 720
                      format: int32
                video_inputs:
                  type: array
                  items:
                    properties:
                      character:
                        type: object
                        description: Could be an `avatar` or `talking photo`.
                        properties:
                          type:
                            type: string
                            description: Could be either `avatar` or `talking_photo`(for photo avatars).
                            default: avatar
                            enum:
                            - avatar
                            - talking_photo
                          avatar_id:
                            type: string
                            description: Provide either `avatar_id` or `talking_photo_id`.
                          talking_photo_id:
                            type: string
                            description: Provide either `avatar_id` or `talking_photo_id`.
                          scale:
                            type: number
                            description: _applies to both `avatar` and `talking_photo` type._
                            default: 1
                            format: float
                          avatar_style:
                            type: string
                            description: _applies to this `avatar` type._
                            default: normal
                            enum:
                            - circle
                            - closeUp
                            - normal
                          offset:
                            type: object
                            description: _applies to both `avatar` and `talking_photo` type._
                            properties:
                              x:
                                type: number
                                format: float
                              y:
                                type: number
                                format: float
                          matting:
                            type: string
                            description: _applies to both `avatar` and `talking_photo` type._
                          circle_background_color:
                            type: string
                            description: _applies to both `avatar` and `talking_photo` type._
                          talking_photo_style:
                            type: string
                            description: _applies to this `talking_photo` type._
                          talking_style:
                            type: string
                            description: _applies to this `talking_photo` type._
                            enum:
                            - stable
                            - expressive
                          expression:
                            type: string
                            description: _applies to this `talking_photo` type._
                            enum:
                            - default
                            - happy
                          super_resolution:
                            type: string
                            description: _applies to this `talking_photo` type._
                      voice:
                        type: object
                        description: could be TextVoiceSettings or AudioVoiceSettings or SilenceVoiceSettings
                        properties:
                          type:
                            type: string
                            description: must be text
                          voice_id:
                            type: string
                            description: voice id
                          input_text:
                            type: string
                            description: script to drive the voice
                          speed:
                            type: number
                            description: Voice speed, value between 0.5 and 1.5. Default is 1.
                            format: float
                          pitch:
                            type: integer
                            description: Voice pitch, value between -50 and 50. Default is 0.
                            format: int32
                          emotion:
                            type: string
                            description: Voice emotion, if voice support emotion.
                            enum:
                            - Excited
                            - Friendly
                            - Serious
                            - Soothing
                            - Broadcaster
                          locale:
                            type: string
                            description: Allows to specify voice accents/locales for multilingual voices. (e.g., en-US, en-IN, pt-PT, pt-BR )
                      background:
                        type: object
                        description: could be ColorBackground, ImageBackground or VideoBackground
                        properties:
                          type:
                            type: string
                            description: could be `color`, `image`, `video`
                            enum:
                            - color
                            - image
                            - video
                          value:
                            type: string
                            description: _applies to `color` type._
                          ? ''
                          : type: string
                    type: object
                folder_id:
                  type: string
                  description: Allows them to specify the video output folder destination.
                callback_url:
                  type: string
                  description: A custom curl for callback
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
      deprecated: false
      x-mint:
        href: /reference/create-an-avatar-video-v2
      tags:
      - Videos
      security:
      - ApiKeyAuth: []
  /v1/video.list:
    get:
      summary: Retrieve Video List
      description: This endpoint retrieves a list of videos associated with the user.
      operationId: video-list
      parameters:
      - name: limit
        in: query
        description: Enter a range from 0-100 for the number of videos you wish to retrieve in one response. If more than 100 videos exist, you can retrieve the remaining videos using the pagination token returned in the response.
        schema:
          type: integer
          format: int32
          default: null
      - name: folder_id
        in: query
        schema:
          type: string
      - name: title
        in: query
        schema:
          type: string
      - name: token
        in: query
        description: pagination token for next page
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
      deprecated: false
      x-mint:
        href: /reference/video-list
      tags:
      - Videos
      security:
      - ApiKeyAuth: []
  /v1/video.webm:
    post:
      summary: Create a WebM Video
      description: Generates a webm video with transparent background and an avatar speaking the input text. You can customize the avatar's pose, style, and voice, as well as the dimensions of the video.
      operationId: create-a-webm-video
      parameters:
      - name: x-api-key
        in: header
        description: You api key
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                avatar_pose_id:
                  type: string
                  description: The ID of the avatar's pose. You can specify this field from the response of avatar.list API
                  default: Vanessa-invest-20220722
                avatar_style:
                  type: string
                  description: The style of the avatar. Can be "normal" or other styles supported by the API. 'circle', 'closeUp', 'normal', 'voiceOnly'.
                  default: normal
                  enum:
                  - normal
                  - closeUp
                input_text:
                  type: string
                  description: The text that the avatar will speak in the video.
                  default: This is a WebM video generated by HeyGen API
                voice_id:
                  type: string
                  description: The ID of the voice that the avatar will use.
                  default: 1bd001e7e50f421d891986aad5158bc8
                input_audio:
                  type: string
                  description: input audio url. Specify either input_text/voice_id or input_audio.
                dimension:
                  type: object
                  description: The dimensions of the output video will be scaled by the height of the original avatar size.
                  properties:
                    width:
                      type: integer
                      default: 1280
                      format: int32
                    height:
                      type: integer
                      default: 720
                      format: int32
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: '{"code": 100, "data": {"video_id": "xxx"}, "msg": null, "message": null}%'
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
      deprecated: false
      x-mint:
        href: /reference/create-a-webm-video
      tags:
      - Videos
      security:
      - ApiKeyAuth: []
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: x-api-key
      x-default: <your-api-key>
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY