HeyGen Photo Avatars API
Photo avatar generation, training, and enhancement endpoints.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/heygen-photo-avatars-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.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