> ## Documentation Index > Fetch the complete documentation index at: https://anam.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # list avatars > Returns a list of all avatars ## OpenAPI ````yaml https://api.anam.ai/swagger.json get /v1/avatars openapi: 3.1.0 info: title: Anam AI API version: '1.0' servers: - url: https://api.anam.ai description: Anam API security: - BearerAuth: [] tags: - name: Sessions - name: Avatar Videos - name: Meetings - name: Personas - name: Avatars - name: Voices - name: LLMs - name: Knowledge - name: Tools - name: Share Links - name: Engine paths: /v1/avatars: get: tags: - Avatars summary: list avatars description: Returns a list of all avatars operationId: listAvatars parameters: - in: query name: page schema: type: integer minimum: 1 default: 1 description: Page number for pagination - in: query name: perPage schema: type: integer minimum: 1 maximum: 100 default: 10 description: Number of avatars per page (max 100) - in: query name: search schema: type: string description: >- Search term to filter avatars by display name or generated description - in: query name: renderStyle schema: type: string enum: - all - realistic - animated_3d - illustrated - unknown default: all description: >- Filter avatars by render style. `unknown` includes avatars whose style has not been determined (all custom avatars, and any avatar whose metadata generation has not completed). - in: query name: tags schema: type: array items: type: string style: form explode: false description: >- Comma-separated list of tags to filter by (e.g. `tags=professional,studio`). Matches avatars with ANY of the given tags. Tags are generated alongside `description`/`displayTags` and are lowercase. - in: query name: onlyOneShot schema: type: boolean default: false description: Only return one-shot avatars responses: '200': description: Successfully retrieved avatars content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Avatar' meta: $ref: '#/components/schemas/Pagination' examples: default: $ref: '#/components/examples/AvatarListResponse' '401': description: Unauthorized - Invalid or missing API key '403': description: Forbidden - API key lacks the required permission '404': description: Not Found - No avatars found '500': description: Server error components: schemas: Avatar: type: object description: A face preset that a persona can use as its visual representation. properties: id: type: string format: uuid description: Unique identifier for the avatar. displayName: type: string description: Human-readable name shown in the Lab and share links. variantName: type: string description: >- Name of the specific variant (e.g. lighting or pose) within the avatar family. imageUrl: type: string format: uri description: >- Still image of the avatar, framed exactly like `videoUrl`, `idleVideoUrl` and a landscape session (the default). Use it as the thumbnail, poster or loading image wherever a preview video or the live stream replaces it, and give the image and the video the same box, `object-fit` and `object-position` so the avatar doesn't move when they swap. For Cara 4 avatars this is the 1152x768 landscape crop (the same image as `landscapeImageUrl`). Cara 4 avatars used to return their square source image here; that image is now `sourceImageUrl`. Empty when the avatar has no image yet. sourceImageUrl: type: string format: uri description: >- The image the avatar was created from. For Cara 4 avatars it is square (1152x1152) and shows more of the scene than the 1152x768 crop that preview videos and sessions use, so the avatar appears to zoom in when a video or call replaces it. Don't use it as a thumbnail, poster or loading image next to `videoUrl` or a session; use `imageUrl`, `landscapeImageUrl` or `portraitImageUrl`. For legacy avatars it is the same landscape image as `imageUrl`. landscapeImageUrl: type: - string - 'null' format: uri description: >- Still image cropped exactly as the engine frames landscape (1152x768) output, which is also the framing of `videoUrl` and `idleVideoUrl`. Use it with landscape sessions (the default) and preview videos. For avatars with legacy landscape source images this is the source image. portraitImageUrl: type: - string - 'null' format: uri description: >- Still image cropped exactly as the engine frames portrait (768x1152) output. Use it as the poster for a session started with portrait `videoWidth`/`videoHeight`. Preview videos are landscape, so don't swap this image for `videoUrl`. `null` when the avatar cannot render portrait output. videoUrl: type: - string - 'null' format: uri description: >- Signed URL for a verified muted MP4 preview of the avatar. Uses the idle loop if the talking preview is unavailable. Landscape (1152x768 for Cara 4 avatars, 720x480 for legacy avatars) and framed exactly like `imageUrl`, so pair it with `imageUrl` or `landscapeImageUrl`, not `sourceImageUrl`. The URL expires after 1 hour; re-fetch the avatar to get a fresh URL. `null` when the preview is unavailable or still generating. idleVideoUrl: type: - string - 'null' format: uri description: >- Signed URL for a muted idling-loop MP4 of the avatar, if one exists. Landscape and framed exactly like `imageUrl`, like `videoUrl`. The URL expires after 1 hour; re-fetch the avatar to get a fresh URL. `null` when unavailable or still generating. createdAt: type: string format: date-time description: Timestamp when the avatar was created. updatedAt: type: string format: date-time description: Timestamp when the avatar was last updated. createdByOrganizationId: type: - string - 'null' description: >- ID of the organization that created the avatar, or `null` for stock avatars. IDs may be either UUIDs or nanoid-style strings depending on when the organization was created. availableVersions: type: array items: type: string description: >- Avatar models this avatar can be used with. Pass one of these values as `avatarModel` when creating a persona or starting a session. activeVersion: type: - string - 'null' description: >- Avatar model used by default when no explicit `avatarModel` is requested. description: type: - string - 'null' description: >- AI-generated description of the avatar's appearance, setting, and style. `null` if metadata generation has not completed. displayTags: type: array items: type: string description: >- Curated tags describing the avatar. Empty array if metadata generation has not completed. renderStyle: type: string enum: - realistic - animated_3d - illustrated - unknown description: >- Render style of the avatar. `unknown` covers custom avatars and avatars whose metadata has not yet been generated. Pagination: type: object description: >- Pagination metadata returned alongside the `data` array of every list endpoint. properties: total: type: integer description: Total number of items across all pages. lastPage: type: integer description: Number of the last page. currentPage: type: integer description: Number of the current page. perPage: type: integer description: Number of items per page. prev: type: - integer - 'null' description: Number of the previous page, or null if on the first page. next: type: - integer - 'null' description: Number of the next page, or null if on the last page. examples: AvatarListResponse: summary: A paginated list of avatars value: data: - id: 071b0286-4cce-4808-bee2-e642f1062de3 displayName: Liv variantName: home imageUrl: >- https://lab.anam.ai/api/avatars/071b0286-4cce-4808-bee2-e642f1062de3/image/landscape?v=3f2a1b0c9d8e7f6a sourceImageUrl: >- https://example.public.blob.vercel-storage.com/avatar-previews/liv_home.webp landscapeImageUrl: >- https://lab.anam.ai/api/avatars/071b0286-4cce-4808-bee2-e642f1062de3/image/landscape?v=3f2a1b0c9d8e7f6a portraitImageUrl: >- https://lab.anam.ai/api/avatars/071b0286-4cce-4808-bee2-e642f1062de3/image/portrait?v=3f2a1b0c9d8e7f6a videoUrl: >- https://example.com/avatars/cara-4/stock/liv_home/talking_preview_video.mp4?X-Amz-Signature=... idleVideoUrl: >- https://example.com/avatars/cara-4/stock/liv_home/idling_video.mp4?X-Amz-Signature=... createdAt: '2026-04-20T10:00:00.000Z' updatedAt: '2026-04-20T10:00:00.000Z' createdByOrganizationId: null availableVersions: - cara-4 activeVersion: cara-4 description: >- A friendly professional in a modern office setting, warm expression, business casual attire. displayTags: - professional - friendly - office renderStyle: realistic meta: total: 1 lastPage: 1 currentPage: 1 perPage: 10 prev: null next: null securitySchemes: BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.