> ## Documentation Index > Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/llms.txt > Use this file to discover all available pages before exploring further. # List Avatar Looks > Returns a paginated list of avatar looks (outfits, poses, styles). Filterable by group_id, avatar_type, and ownership. The look id is the avatar_id to pass when creating a video. ## OpenAPI ````yaml /openapi/external-api.json get /v3/avatars/looks openapi: 3.1.0 info: title: HeyGen External API version: 1.0.0 description: >- HeyGen's external API for programmatic AI video creation. See https://docs.heygen.com for full documentation. contact: name: HeyGen Product Infra url: https://heygen.com servers: - url: https://api.heygen.com description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Video Agent description: Create videos from text prompts using AI - name: Videos description: Create, list, retrieve, and delete videos - name: Voices description: Text-to-speech and voice management - name: Audio description: Search the background-music and sound-effects catalog - name: Video Translate description: Translate videos into other languages - name: User description: Account information and billing - name: Avatars description: List and manage avatars and looks - name: Assets description: Upload files for use in video creation - name: Webhooks description: Manage webhook endpoints and events - name: Lipsync description: Dub or replace audio on existing videos - name: Brand description: >- Brand-related resources — brand kits (colors, fonts, logos) and brand glossaries (custom term translations) paths: /v3/avatars/looks: get: tags: - Avatars summary: List Avatar Looks description: >- Returns a paginated list of avatar looks (outfits, poses, styles). Filterable by group_id, avatar_type, and ownership. The look id is the avatar_id to pass when creating a video. operationId: listAvatarLooks parameters: - name: group_id in: query required: false description: >- Filter looks to a specific avatar group. Returns only looks belonging to this group. schema: type: string - name: avatar_type in: query required: false description: >- Filter by avatar type: 'studio_avatar', 'digital_twin', or 'photo_avatar'. schema: type: string enum: - studio_avatar - digital_twin - photo_avatar - name: ownership in: query required: false description: >- Filter by ownership: 'public' for preset avatars, or 'private' for your own. Omit for all. schema: type: string enum: - public - private - name: limit in: query required: false description: Maximum number of items to return per page (1-50). schema: type: integer minimum: 1 maximum: 50 default: 20 - name: token in: query required: false description: Opaque cursor token for the next page. schema: type: string responses: '200': description: Successful response content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/AvatarLookItem' has_more: type: boolean description: Whether more pages are available next_token: type: - string - 'null' description: Opaque cursor for the next page '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: invalid_parameter message: '''limit'' must be between 1 and 50.' param: limit doc_url: null '401': description: Authentication failed content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: authentication_failed message: Invalid or expired API key. Verify your x-api-key header. param: null doc_url: null '429': description: Rate limit exceeded content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: rate_limit_exceeded message: >- Too many requests. Retry after the duration specified in the Retry-After header. param: null doc_url: null headers: Retry-After: description: Seconds to wait before retrying schema: type: integer security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: AvatarLookItem: description: |- A single avatar look in the list response. The ``id`` field is the look-level identifier to pass as ``avatar_id`` to POST /v3/videos. properties: id: description: Unique look identifier. Pass this as avatar_id to POST /v3/videos. examples: - lk_abc123 title: Id type: string name: description: Display name of the look. examples: - Business Suit title: Name type: string avatar_type: $ref: '#/components/schemas/AvatarLookType' description: Avatar type — determines engine and parameter compatibility. examples: - photo_avatar group_id: anyOf: - type: string - type: 'null' default: null description: ID of the avatar group this look belongs to. examples: - ag_abc123 title: Group Id preview_image_url: anyOf: - type: string - type: 'null' default: null description: URL to the look preview image. examples: - https://files.heygen.ai/look/business_preview.jpg title: Preview Image Url preview_video_url: anyOf: - type: string - type: 'null' default: null description: URL to the look preview video. examples: - https://files.heygen.ai/look/business_preview.mp4 title: Preview Video Url gender: anyOf: - type: string - type: 'null' default: null description: Gender of the avatar. examples: - female title: Gender tags: description: Tags associated with the look. examples: - - business - formal items: type: string title: Tags type: array default_voice_id: anyOf: - type: string - type: 'null' default: null description: Default voice ID for this look. examples: - 1bd001e7e50f421d891986aad5c8bbd2 title: Default Voice Id supported_api_engines: description: Engine values this look supports for POST /v3/videos. examples: - - avatar_v - avatar_iv items: type: string title: Supported Api Engines type: array image_width: anyOf: - type: integer - type: 'null' default: null description: Native width of the look in pixels. examples: - 1920 title: Image Width image_height: anyOf: - type: integer - type: 'null' default: null description: Native height of the look in pixels. examples: - 1080 title: Image Height preferred_orientation: anyOf: - enum: - portrait - landscape - square type: string - type: 'null' default: null description: >- Preferred orientation of the look: 'portrait', 'landscape', or 'square'. title: Preferred Orientation status: anyOf: - $ref: '#/components/schemas/AvatarStatus' - type: 'null' default: null description: >- Training status of the avatar look: 'processing', 'completed', or 'failed'. Only present for private avatars. examples: - completed error: anyOf: - $ref: '#/components/schemas/AvatarError' - type: 'null' default: null description: Error details. Only present when status is 'failed'. required: - id - name - avatar_type title: AvatarLookItem type: object StandardAPIError: type: object properties: code: type: string description: Machine-readable error code example: invalid_parameter message: type: string description: Human-readable error message example: Video not found param: type: - string - 'null' description: Which request field caused the error doc_url: type: - string - 'null' description: Link to error documentation required: - code - message AvatarLookType: description: Avatar look type — determines engine compatibility with POST /v3/videos. enum: - studio_avatar - digital_twin - photo_avatar title: AvatarLookType type: string AvatarStatus: description: Training/creation status of an avatar group or look. enum: - processing - pending_consent - failed - completed title: AvatarStatus type: string AvatarError: description: Error details for a failed avatar creation. properties: code: description: Machine-readable error code. examples: - training_failed title: Code type: string message: description: Human-readable error description. examples: - Footage duration must be between 15s and 600s title: Message type: string required: - code - message title: AvatarError type: object securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: HeyGen API key. Obtain from your HeyGen dashboard. BearerAuth: type: http scheme: bearer description: OAuth2 bearer token. ````