update avatar

curl --request PUT \
  --url https://api.anam.ai/v1/avatars/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "displayName": "Updated avatar name"
}
'

import requests

url = "https://api.anam.ai/v1/avatars/{id}"

payload = { "displayName": "Updated avatar name" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({displayName: 'Updated avatar name'})
};

fetch('https://api.anam.ai/v1/avatars/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.anam.ai/v1/avatars/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'displayName' => 'Updated avatar name'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.anam.ai/v1/avatars/{id}"

	payload := strings.NewReader("{\n  \"displayName\": \"Updated avatar name\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.anam.ai/v1/avatars/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"displayName\": \"Updated avatar name\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.anam.ai/v1/avatars/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"displayName\": \"Updated avatar name\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "error": "Service temporarily unavailable",
  "message": "We could not check your API key. Please retry shortly."
}

PUT

avatars

{id}

update avatar

curl --request PUT \
  --url https://api.anam.ai/v1/avatars/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "displayName": "Updated avatar name"
}
'

import requests

url = "https://api.anam.ai/v1/avatars/{id}"

payload = { "displayName": "Updated avatar name" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({displayName: 'Updated avatar name'})
};

fetch('https://api.anam.ai/v1/avatars/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.anam.ai/v1/avatars/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'displayName' => 'Updated avatar name'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.anam.ai/v1/avatars/{id}"

	payload := strings.NewReader("{\n  \"displayName\": \"Updated avatar name\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.anam.ai/v1/avatars/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"displayName\": \"Updated avatar name\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.anam.ai/v1/avatars/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"displayName\": \"Updated avatar name\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "error": "Service temporarily unavailable",
  "message": "We could not check your API key. Please retry shortly."
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

string<uuid>

required

Avatar ID

Body

application/json

Fields to update on the avatar. Only displayName is editable.

displayName

string

required

New display name for the avatar

Response

Successfully updated avatar

A face preset that a persona can use as its visual representation.

string<uuid>

Unique identifier for the avatar.

displayName

string

Human-readable name shown in the Lab and share links.

variantName

string

Name of the specific variant (e.g. lighting or pose) within the avatar family.

imageUrl

string<uri>

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, or when its images are not available through the API. May be a time-limited link; see imageUrlsExpireAt.

sourceImageUrl

string<uri>

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. Empty when the avatar's images are not available through the API. May be a time-limited link; see imageUrlsExpireAt.

landscapeImageUrl

string<uri> | null

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. null when the avatar's images are not available through the API. May be a time-limited link; see imageUrlsExpireAt.

portraitImageUrl

string<uri> | null

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 or its images are not available through the API. May be a time-limited link; see imageUrlsExpireAt.

imageUrlsExpireAt

string<date-time> | null

When set, imageUrl, sourceImageUrl, landscapeImageUrl and portraitImageUrl are time-limited links that stop working at this time; fetch the avatar again for fresh ones. They stay valid for at least an hour, and repeated requests within the same hour return the same links, so browsers can cache them. Treat them as credentials for those images, since anyone holding a link can load the image until it expires. null when the image URLs don't expire.

videoUrl

string<uri> | null

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

string<uri> | null

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

string<date-time>

Timestamp when the avatar was created.

updatedAt

string<date-time>

Timestamp when the avatar was last updated.

createdByOrganizationId

string | null

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

string[]

Avatar models this avatar can be used with. Pass one of these values as avatarModel when creating a persona or starting a session.

activeVersion

string | null

Avatar model used by default when no explicit avatarModel is requested.

description

string | null

AI-generated description of the avatar's appearance, setting, and style. null if metadata generation has not completed.

displayTags

string[]

Curated tags describing the avatar. Empty array if metadata generation has not completed.

renderStyle

enum<string>

Render style of the avatar. unknown covers custom avatars and avatars whose metadata has not yet been generated.

Available options:

realistic,

animated_3d,

illustrated,

unknown

Use the API

Sessions

Meetings

Avatar Videos

Personas

Avatars

Voices

Pronunciation Dictionaries

LLMs

Knowledge

Tools

Share Links

Engine

update avatar

Authorizations

Path Parameters

Body

Response