Skip to main content
GET
/
avatar-profiles
/
{id}
Get Avatar
curl --request GET \
  --url https://api.example.com/avatar-profiles/{id}
Returns one avatar from your organization’s primary workspace. The response includes processing status, so this endpoint replaces a separate status check. You can pass an avatar ID to an AI Avatar tile as soon as it is created. If it is still processing, the run waits for processing to finish. If processing_status is failed, the avatar cannot be used until you create a new one.

​
Request

curl "https://api.mosaic.so/avatar-profiles/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb" \
  -H "Authorization: Bearer mk_your_api_key"

​
Parameters

FieldLocationTypeRequiredDescription
idpathstring UUIDYesAvatar ID.

​
Response

Returns the avatar profile. The response shape is:
FieldTypeDescription
idstring UUIDAvatar profile ID. Pass this as avatar_profile_id in an AI Avatar tile.
video_preview_urlstring URL | nullSigned video preview URL. This is null until a preview/reference video is available.
namestringAvatar display name.
status"pending" | "processing" | "ready" | "failed"Avatar processing state. ready means the avatar is fully prepared. pending or processing can still be used in an AI Avatar tile; the run waits. failed means the avatar cannot be used.
status_messagestring | nullError message when status is failed; otherwise null.
{
  "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "video_preview_url": "https://...",
  "name": "Founder Avatar",
  "status": "processing",
  "status_message": null
}