Anam.ai Avatars API
The Avatars API from Anam.ai — 2 operation(s) for avatars.
OpenAPI Specification
openapi: 3.1.0
info:
title: Anam AI Avatars API
version: '1.0'
servers:
- url: https://api.anam.ai
description: Anam API
security:
- BearerAuth: []
tags:
- name: Avatars
paths:
/v1/avatars:
get:
description: Returns a list of all avatars
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
tags:
- Avatars
operationId: listAvatars
summary: list avatars
x-mint:
metadata:
title: list avatars
mcp:
enabled: true
name: list-avatars
description: Returns a list of all avatars
post:
description: Create a new one-shot avatar from an image file or image URL. You can use either multipart/form-data with an image file, or JSON with an image URL.
requestBody:
description: Source image and display name for the new one-shot avatar. Provide either an uploaded file (`multipart/form-data` with `imageFile`) or a URL (`application/json` with `imageUrl`) — not both.
required: true
content:
multipart/form-data:
schema:
type: object
required:
- displayName
properties:
displayName:
type: string
description: Display name for the avatar (3-50 characters)
imageFile:
type: string
format: binary
description: Image file to create the avatar from (JPEG, PNG, or WebP, max 4.5MB). Either imageFile or imageUrl must be provided, but not both.
imageUrl:
type: string
format: uri
description: URL of the image to create the avatar from (JPEG, PNG, or WebP, max 4.5MB). Either imageFile or imageUrl must be provided, but not both.
avatarModel:
type: string
description: Avatar model to use (e.g. "cara-3", "cara-4", "cara-4-latest"). `cara-3` and `cara-4` are generally available. Defaults to the server default model. Gated models (the '-latest' suffix) require organization-level access.
application/json:
examples:
default:
$ref: '#/components/examples/AvatarCreate'
schema:
type: object
required:
- displayName
- imageUrl
properties:
displayName:
type: string
description: Display name for the avatar (1+ characters)
imageUrl:
type: string
format: uri
description: URL of the image to create the avatar from (JPEG, PNG, or WebP, max 4.5MB). The image will be downloaded, processed, and stored permanently.
avatarModel:
type: string
description: Avatar model to use (e.g. "cara-3", "cara-4", "cara-4-latest"). `cara-3` and `cara-4` are generally available. Defaults to the server default model. Gated models (the '-latest' suffix) require organization-level access.
responses:
'201':
description: Successfully created avatar
content:
application/json:
schema:
$ref: '#/components/schemas/Avatar'
examples:
default:
$ref: '#/components/examples/AvatarResponse'
'400':
description: Bad request - Invalid avatar data, missing image file/URL, or both provided
'401':
description: Unauthorized - Invalid or missing API key
'403':
description: Forbidden - Requires enterprise plan or API key lacks the required permission
'422':
description: Unprocessable Entity - Image could not be processed, or was rejected by content moderation (e.g. inappropriate content, celebrity likeness, or the subject's age could not be verified)
'429':
description: Too Many Requests - Content moderation rate limit reached; wait and retry
'500':
description: Server error
tags:
- Avatars
operationId: createAvatar
summary: create avatar
x-mint:
metadata:
title: create avatar
mcp:
enabled: true
name: create-avatar
description: Create a new one-shot avatar from an image file or image URL. You can use either multipart/form-data with an image file, or JSON with an image URL.
/v1/avatars/{id}:
get:
description: Returns an avatar by ID
parameters:
- in: path
name: id
schema:
type: string
format: uuid
required: true
description: Avatar ID
responses:
'200':
description: Successfully retrieved avatar
content:
application/json:
schema:
$ref: '#/components/schemas/Avatar'
examples:
default:
$ref: '#/components/examples/AvatarResponse'
'400':
description: Bad request - Invalid avatar ID
'401':
description: Unauthorized - Invalid or missing API key
'403':
description: Forbidden - API key lacks the required permission
'404':
description: Not Found - Avatar not found
'500':
description: Server error
tags:
- Avatars
operationId: getAvatar
summary: get avatar
x-mint:
metadata:
title: get avatar
mcp:
enabled: true
name: get-avatar
description: Returns an avatar by ID
put:
description: Update an avatar by ID (only display name can be updated)
parameters:
- in: path
name: id
schema:
type: string
format: uuid
required: true
description: Avatar ID
requestBody:
description: Fields to update on the avatar. Only `displayName` is editable.
required: true
content:
application/json:
examples:
default:
$ref: '#/components/examples/AvatarUpdate'
schema:
type: object
required:
- displayName
properties:
displayName:
type: string
description: New display name for the avatar
responses:
'200':
description: Successfully updated avatar
content:
application/json:
schema:
$ref: '#/components/schemas/Avatar'
examples:
default:
$ref: '#/components/examples/AvatarResponse'
'400':
description: Bad request - Invalid avatar data
'401':
description: Unauthorized - Invalid or missing API key
'403':
description: Forbidden - API key lacks the required permission
'404':
description: Not Found - Avatar not found
'500':
description: Server error
tags:
- Avatars
operationId: updateAvatar
summary: update avatar
x-mint:
metadata:
title: update avatar
mcp:
enabled: true
name: update-avatar
description: Update an avatar by ID (only display name can be updated)
delete:
description: 'Delete an avatar by ID. By default this is a soft delete: the avatar is hidden and can be restored. Pass `hard=true` to permanently purge the avatar and its stored assets (source image and generated versions). A hard delete cannot be undone and is intended for data-erasure requests; it also purges avatars that were previously soft-deleted.'
parameters:
- in: path
name: id
schema:
type: string
format: uuid
required: true
description: Avatar ID
- in: query
name: hard
schema:
type: boolean
required: false
description: When `true`, permanently deletes the avatar and purges its stored source and generated assets instead of soft-deleting it.
responses:
'200':
description: Successfully deleted avatar
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Avatar deleted successfully
'400':
description: Bad request - Invalid avatar ID
'401':
description: Unauthorized - Invalid or missing API key
'403':
description: Forbidden - API key lacks the required permission
'404':
description: Not Found - Avatar not found
'500':
description: Server error
tags:
- Avatars
operationId: deleteAvatar
summary: delete avatar
x-mint:
metadata:
title: delete avatar
mcp:
enabled: true
name: delete-avatar
description: 'Delete an avatar by ID. By default this is a soft delete: the avatar is hidden and can be restored. Pass `hard=true` to permanently purge the avatar and its stored assets (source image and generated versions). A hard delete cannot be undone and is intended for data-erasure requests; it also purges avatars that were previously soft-deleted.. Use with caution as this action cannot be undone.'
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: URL of the still image used as a preview of the avatar.
landscapeImageUrl:
type:
- string
- 'null'
format: uri
description: Preview image cropped exactly as the engine frames landscape (1152x768) output. Use this when displaying the avatar at a landscape aspect ratio. For avatars with legacy landscape source images this is the same as `imageUrl`.
portraitImageUrl:
type:
- string
- 'null'
format: uri
description: Preview image cropped exactly as the engine frames portrait (768x1152) output. Use this when starting a session with portrait `videoWidth`/`videoHeight`. `null` when the avatar cannot render portrait output.
videoUrl:
type:
- string
- 'null'
format: uri
description: Signed URL for a muted MP4 preview of the avatar, if one exists. 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. 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:
AvatarCreate:
summary: Create a one-shot avatar from an image URL
value:
displayName: Alex
imageUrl: https://example.com/alex.jpg
AvatarResponse:
summary: A single avatar resource
value:
id: 071b0286-4cce-4808-bee2-e642f1062de3
displayName: Liv
variantName: home
imageUrl: https://lab.anam.ai/persona_thumbnails/liv_home.png
videoUrl: https://example.com/avatar-preview.mp4?X-Amz-Signature=...
createdAt: '2026-04-20T10:00:00.000Z'
updatedAt: '2026-04-20T10:00:00.000Z'
createdByOrganizationId: null
availableVersions:
- cara-3
activeVersion: cara-3
description: A friendly professional in a modern office setting, warm expression, business casual attire.
displayTags:
- professional
- friendly
- office
renderStyle: realistic
AvatarUpdate:
summary: Rename an avatar
value:
displayName: Updated avatar name
AvatarListResponse:
summary: A paginated list of avatars
value:
data:
- id: 071b0286-4cce-4808-bee2-e642f1062de3
displayName: Liv
variantName: home
imageUrl: https://lab.anam.ai/persona_thumbnails/liv_home.png
videoUrl: https://example.com/avatar-preview.mp4?X-Amz-Signature=...
createdAt: '2026-04-20T10:00:00.000Z'
updatedAt: '2026-04-20T10:00:00.000Z'
createdByOrganizationId: null
availableVersions:
- cara-3
activeVersion: cara-3
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
x-mint:
mcp:
enabled: true