> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jogg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Public Avatars

> Retrieve list of public avatars with filtering options.
Supports pagination and various filters including aspect ratio, style, gender, age, scene, and ethnicity.


Retrieve the list of public avatars available from the JoggAI library. These avatars can be used immediately in your videos.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/avatars/public' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Related Guides

<CardGroup cols={2}>
  <Card title="Create Avatar Videos" href="/api-reference/v2/API Documentation/CreateAvatarVideos">
    Use avatars to create videos
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /v2/avatars/public
openapi: 3.0.1
info:
  title: JoggAI OpenAPI v2
  description: >
    JoggAI OpenAPI v2 provides a comprehensive suite of endpoints for creating
    and managing AI-powered video content.


    ## Authentication

    All API requests require authentication using an API key provided in the
    `x-api-key` header.


    ## Base URL

    Production: https://api.jogg.ai/v2


    ## Rate Limiting

    API calls are subject to rate limiting based on your subscription plan.


    ## Error Handling

    All endpoints return standard HTTP status codes along with detailed error
    messages in the response body.
  version: 2.0.0
  license:
    name: MIT
servers:
  - url: https://api.jogg.ai
    description: Production server
security:
  - apiKeyAuth: []
tags:
  - name: Video
    description: Video creation and management operations
  - name: Avatar
    description: Avatar management and creation operations
  - name: Voice
    description: Voice and timbre management operations
  - name: Asset
    description: Asset management including music, scripts, and uploads
  - name: Template
    description: Template management operations
  - name: Product
    description: Product management operations
  - name: User
    description: User account operations
  - name: Webhook
    description: Webhook endpoint management for event notifications
paths:
  /v2/avatars/public:
    get:
      tags:
        - Avatar
      summary: Get Public Avatar List
      description: >
        Retrieve list of public avatars with filtering options.

        Supports pagination and various filters including aspect ratio, style,
        gender, age, scene, and ethnicity.
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
        - name: aspect_ratio
          in: query
          description: Filter by aspect ratio
          schema:
            type: string
            enum:
              - portrait
              - landscape
              - square
            example: portrait
        - name: style
          in: query
          description: Filter by avatar style
          schema:
            type: string
            enum:
              - professional
              - social
        - name: gender
          in: query
          description: Filter by avatar gender
          schema:
            type: string
            enum:
              - female
              - male
        - name: age
          in: query
          description: Filter by age group
          schema:
            type: string
            enum:
              - adult
              - senior
              - young_adult
        - name: scene
          in: query
          description: Filter by scene type
          schema:
            type: string
            enum:
              - lifestyle
              - outdoors
              - business
              - studio
              - health_fitness
              - education
              - news
        - name: ethnicity
          in: query
          description: Filter by ethnicity
          schema:
            type: string
            enum:
              - european
              - african
              - south_asian
              - east_asian
              - middle_eastern
              - south_american
              - north_american
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          avatars:
                            type: array
                            description: List of public avatars
                            items:
                              type: object
                              properties:
                                id:
                                  type: integer
                                  description: Avatar ID
                                  example: 123
                                name:
                                  type: string
                                  description: Avatar name
                                  example: Professional Female
                                video_url:
                                  type: string
                                  description: Video URL
                                  format: uri
                                  example: https://example.com/video.mp4
                                cover_url:
                                  type: string
                                  description: Cover URL
                                  format: uri
                                  example: https://example.com/cover.jpg
                                aspect_ratio:
                                  type: integer
                                  description: Aspect ratio
                                  enum:
                                    - 0
                                    - 1
                                    - 2
                                  example: 1
                                style:
                                  type: string
                                  description: Style
                                  enum:
                                    - professional
                                    - social
                                  example: professional
                                gender:
                                  type: string
                                  description: Gender
                                  enum:
                                    - female
                                    - male
                                  example: female
                                age:
                                  type: string
                                  description: Age
                                  enum:
                                    - adult
                                    - senior
                                    - young_adult
                                  example: adult
components:
  parameters:
    PageParam:
      name: page
      in: query
      description: Page number for pagination
      schema:
        type: integer
        minimum: 1
        default: 1
        example: 1
    PageSizeParam:
      name: page_size
      in: query
      description: Number of items per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
        example: 10
  schemas:
    BaseResponse:
      type: object
      required:
        - code
        - msg
      properties:
        code:
          type: integer
          description: |
            Business status code:
            * 0 - Success
            * 10104 - Record not found
            * 10105 - Invalid API key
            * 18020 - Insufficient credit
            * 18025 - No permission to call APIs
            * 40000 - Parameter error
            * 50000 - System error
          example: 0
        msg:
          type: string
          description: Response message
          example: Success
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. Obtain your key from the JoggAI dashboard.

````