# Create Photo Avatar Group

Creates an avatar group, which can include both AI-generated and user-uploaded photos of the avatar.

Learn more: [generated photo avatar](https://www.heygen.com/avatars/ai-photo-avatar)

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "heygen-api",
    "version": "4.0.8"
  },
  "servers": [
    {
      "url": "https://api.heygen.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header",
        "x-default": "<your-api-key>"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/v2/photo_avatar/avatar_group/create": {
      "post": {
        "summary": "Create photo avatar group",
        "description": "Easily organize and customize your AI avatars with photo groups",
        "operationId": "create-photo-avatar-group",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Name of the avatar group. "
                  },
                  "image_key": {
                    "type": "string",
                    "description": "Image key of the AI-generated avatar/uploaded photo. For AI-generated photos, this can be retrieved from the <a href=\"https://docs.heygen.com/reference/check-photolook-generation-status\" target=\"_blank\">Check Photo/Look Generation Status</a> endpoint. For user-uploaded photos, this can be retrieved from the <a href=\"https://docs.heygen.com/reference/upload-asset\" target=\"_blank\">Upload Asset</a> endpoint."
                  },
                  "generation_id": {
                    "type": "string",
                    "description": "Unique identifier of the AI-generated avatar. Can be retrieved from the <a href=\"https://docs.heygen.com/reference/generate-photo-avatar-photos\" target=\"_blank\">Generate Photo Avatar Photos</a> endpoint. _Applies only to the AI-generated avatars._"
                  }
                },
                "required": [
                  "name",
                  "image_key"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Avatar group created successfully - Expand to view the detailed response schema.",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": {
                      "error": null,
                      "data": {
                        "id": "5fod957cf9514e88878b56cec14231s7",
                        "image_url": "https://files2.heygen.ai/image/ca03b269c23445359c0l3f04fbebf705/original?Expires=1760964149&Signature=Oq1L6zO7mMuoWOUnWXrWOTMj9Ixl0kTBpEg6HHB5Y~fK5gixvAfuFm7kFKOK4NsFmQCfb0w~KVWwMQWVIKoI5ODY0Hku98C1k~-I5ibDbqdLPiEKJFSAKmOde~8oian0D-UNjnt5~NYrj4iL177zSOd1yMwZi2BkryWAXs2RRoPpCBEDWfrckOPpafttg-4hQFBTOHbMIzEDUPKvqwFib-VPcxCmG~dn6~2d96NXOUHWvIhlYuJXf5uImOtlFWOT8u0GSn15-8W~zG52sCKGfldYt0Z5lXHNJcYWuajKWG1DqEFAlfpNfDyqmzpN4Gp4tOSTppBD4vG~4ht2Y3936A__&Key-Pair-Id=K38HBHX5LX3X2H",
                        "created_at": 1760359348.932659,
                        "name": "Eli",
                        "status": "pending",
                        "group_id": "5fod957cf9514e88878b56cec14231s7",
                        "is_motion": false,
                        "motion_preview_url": null,
                        "business_type": "uploaded",
                        "upscale_availability": {
                          "available": false,
                          "reason": "Photo avatar look upload not completed"
                        },
                        "upscaled": false,
                        "background_sound_effect": null,
                        "default_voice_id": null,
                        "moderation_msg": null
                      }
                    }
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Displays error message when the request fails; null if the request is successful."
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Unique identifier of the avatar group."
                        },
                        "image_url": {
                          "type": "string",
                          "description": "URL of the avatar group's image."
                        },
                        "created_at": {
                          "type": "number",
                          "format": "float",
                          "description": "Unix timestamp when the avatar group was created."
                        },
                        "name": {
                          "type": "string",
                          "description": "Name of the avatar group. "
                        },
                        "status": {
                          "type": "string",
                          "description": "Processing status of the avatar group (e.g., \"pending\", \"in_appeal\", \"moderation_rejected\"). "
                        },
                        "group_id": {
                          "type": "string",
                          "description": "Unique identifier of the avatar group. "
                        },
                        "is_motion": {
                          "type": "boolean",
                          "description": "Whether the avatar is a motion (animated) avatar. "
                        },
                        "motion_preview_url": {
                          "type": "string",
                          "description": "URL of the motion avatar's preview. Returns null if not available. "
                        },
                        "business_type": {
                          "type": "string",
                          "description": "Indicates the origin of the avatar (e.g., \"generated\" or \"uploaded\")."
                        },
                        "upscale_availability": {
                          "type": "object",
                          "properties": {
                            "available": {
                              "type": "boolean",
                              "description": "Whether the avatar can be upscaled. "
                            },
                            "reason": {
                              "type": "string",
                              "description": "Reason why the avatar cannot be upscaled (if applicable). "
                            }
                          },
                          "description": "Information about the avatar's upscaling availability.  "
                        },
                        "upscaled": {
                          "type": "boolean",
                          "description": "Whether the avatar has already been upscaled. "
                        },
                        "background_sound_effect": {
                          "type": "string",
                          "description": "Background sound effect applied to the avatar. Returns null if none. "
                        },
                        "default_voice_id": {
                          "type": "string",
                          "description": "Default voice ID assigned to the avatar. "
                        },
                        "moderation_msg": {
                          "type": "string",
                          "description": "Message describing the result of content moderation for the avatar. Provides the reason if the avatar is rejected, suspended, or pending review. Returns null if no moderation issues exist."
                        }
                      },
                      "description": "Contains detailed information about the avatar group. "
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```