HeyGen Photo Avatars API
Photo avatar generation, training, and enhancement endpoints.
OpenAPI Specification
openapi: 3.1.0
info:
title: HeyGen Account Photo Avatars 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: Photo Avatars
description: Photo avatar generation, training, and enhancement endpoints.
paths:
/v2/photo_avatar/photo/generate:
post:
summary: Generate photo avatar photos
description: This endpoint will generate photos that can be used to create photo avatars, returns a generation id, which can be used in the check generation status endpoint to get status and final image/image keys
operationId: generate-photo-avatar-photos
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
age:
type: string
enum:
- Young Adult
- Early Middle Age
- Late Middle Age
- Senior
- Unspecified
gender:
type: string
enum:
- Woman
- Man
- Unspecified
ethnicity:
type: string
enum:
- White
- Black
- Asian American
- East Asian
- South East Asian
- South Asian
- Middle Eastern
- Pacific
- Hispanic
- Unspecified
orientation:
type: string
enum:
- square
- horizontal
- vertical
pose:
type: string
enum:
- half_body
- close_up
- full_body
style:
type: string
enum:
- Realistic
- Pixar
- Cinematic
- Vintage
- Noir
- Cyberpunk
- Unspecified
appearance:
type: string
description: Description/Prompt of the generated avatar photo, maximum 1000 characters
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"error\": null,\n \"data\": {\n \"generation_id\": \"51be01eda38e4c2b9836f06957f66b7d\"\n }\n}"
schema:
type: object
properties:
error: {}
data:
type: object
properties:
generation_id:
type: string
example: 51be01eda38e4c2b9836f06957f66b7d
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
x-mint:
href: /reference/generate-photo-avatar-photos
tags:
- Photo Avatars
security:
- ApiKeyAuth: []
/v2/photo_avatar/look/generate:
post:
summary: Generate photo avatar looks
description: This endpoint can be used to generate additional looks for a trained photo avatar group. The photo avatar group must be trained to use this endpoint.
operationId: generate-photo-avatar-looks
requestBody:
content:
application/json:
schema:
type: object
properties:
group_id:
type: string
prompt:
type: string
description: Prompt to generate different looks
orientation:
type: string
enum:
- square
- horizontal
- vertical
pose:
type: string
enum:
- half_body
- close_up
- full_body
style:
type: string
enum:
- Realistic
- Pixar
- Cinematic
- Vintage
- Noir
- Cyberpunk
- Unspecified
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/generate-photo-avatar-looks
tags:
- Photo Avatars
security:
- ApiKeyAuth: []
/v2/photo_avatar/generation/{generation_id}:
get:
summary: Check photo/look generation status
description: Check photo/look generation status
operationId: check-photolook-generation-status
parameters:
- name: generation_id
in: path
schema:
type: string
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"error\": null,\n \"data\": {\n \"id\": \"51be01eda38e4c2b9836f06957f66b7d\",\n \"status\": \"success\",\n \"msg\": null,\n \"image_url_list\": [\n \"https://resource2.heygen.ai/image/d9e6bbbba83a400885fe9df1abe5f131/original\",\n \"https://resource2.heygen.ai/image/d0130e2c57024e208f5aab3bdfd5fefb/original\",\n \"https://resource2.heygen.ai/image/d982e90bb20f410786914732eac634b7/original\",\n \"https://resource2.heygen.ai/image/dfef1b03e4b2439c85ada1458df37fc2/original\"\n ],\n \"image_key_list\": [\n \"image/d9e6bbbba83a400885fe9df1abe5f131/original\",\n \"image/d0130e2c57024e208f5aab3bdfd5fefb/original\",\n \"image/d982e90bb20f410786914732eac634b7/original\",\n \"image/dfef1b03e4b2439c85ada1458df37fc2/original\"\n ]\n }\n}"
schema:
type: object
properties:
error: {}
data:
type: object
properties:
id:
type: string
example: 51be01eda38e4c2b9836f06957f66b7d
status:
type: string
example: success
msg: {}
image_url_list:
type: array
items:
type: string
example: https://resource2.heygen.ai/image/d9e6bbbba83a400885fe9df1abe5f131/original
image_key_list:
type: array
items:
type: string
example: image/d9e6bbbba83a400885fe9df1abe5f131/original
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
x-mint:
href: /reference/check-photolook-generation-status
tags:
- Photo Avatars
security:
- ApiKeyAuth: []
/v2/photo_avatar/avatar_group/create:
post:
summary: Create photo avatar group
description: 'This api can be used to create a photo avatar group
For generated photo avatar, pass the generation_id and the image_key
For user uploaded avatar, first upload the photo using the upload assets api. Then use the key as image_key
This api only allows using one photo to establish the identity, you can add more photos using the add looks api'
operationId: create-photo-avatar-group
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
image_key:
type: string
generation_id:
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/create-photo-avatar-group
tags:
- Photo Avatars
security:
- ApiKeyAuth: []
/v2/photo_avatar/avatar_group/add:
post:
summary: Add looks to photo avatar group
description: Add other looks to existing photo avatar group
operationId: add-looks-to-photo-avatar-group
requestBody:
content:
application/json:
schema:
type: object
properties:
group_id:
type: string
description: avatar group id to add looks into
image_keys:
type: array
description: A list of images you want to add to the avatar group, maximum 4 at a time
items:
type: string
name:
type: string
description: Name of the looks
generation_id:
type: string
description: Generation id what is used to generate the image_keys, it must be passed in if the image is generated, if it's an upload image, then this is optional
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/add-looks-to-photo-avatar-group
tags:
- Photo Avatars
security:
- ApiKeyAuth: []
/v2/photo_avatar/train:
post:
summary: Train photo avatar group
description: Train a photo avatar group.
operationId: train-photo-avatar-group
requestBody:
content:
application/json:
schema:
type: object
properties:
group_id:
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/train-photo-avatar-group
tags:
- Photo Avatars
security:
- ApiKeyAuth: []
/v2/photo_avatar/train/status/{group_id}:
get:
summary: Get training job status
description: Get the training status of a avatar group
operationId: get-training-job-status
parameters:
- name: group_id
in: path
description: Avatar group id
schema:
type: string
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"error\": null,\n \"data\": {\n \"status\": \"pending\",\n \"error_msg\": null,\n \"created_at\": 1733861263,\n \"updated_at\": null\n }\n}"
schema:
type: object
properties:
error: {}
data:
type: object
properties:
status:
type: string
example: pending
error_msg: {}
created_at:
type: integer
example: 1733861263
default: 0
updated_at: {}
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
x-mint:
href: /reference/get-training-job-status
tags:
- Photo Avatars
security:
- ApiKeyAuth: []
/v2/photo_avatar/add_motion:
post:
summary: Add motion
description: Add motion to an existing photo avatar, returns the id of the new avatar that has motion
operationId: add-motion
requestBody:
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: photo avatar id
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/add-motion
tags:
- Photo Avatars
security:
- ApiKeyAuth: []
/v2/photo_avatar/add_sound_effect:
post:
summary: Add sound effect
description: This api adds sound effect into a photo avatar
operationId: add-sound-effect
requestBody:
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: photo avatar id
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/add-sound-effect
tags:
- Photo Avatars
security:
- ApiKeyAuth: []
/v2/photo_avatar/{id}:
get:
summary: Photo avatar details
description: Get the details of a photo avatar
operationId: photo-avatar-details
parameters:
- name: id
in: path
schema:
type: string
required: true
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/photo-avatar-details
tags:
- Photo Avatars
security:
- ApiKeyAuth: []
/v2/photo_avatar/upscale:
post:
summary: Upscale an avatar
description: Call this api to upscale an avatar, can only be called on an avatar that has motion, returns the photo avatar id that is upscaled
operationId: upscale-an-avatar
requestBody:
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: avatar id
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/upscale-an-avatar
tags:
- Photo Avatars
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