HeyGen Videos API
Video generation, retrieval, and management endpoints.
OpenAPI Specification
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