Skip to main content
POST
/
avatar-profiles
/
create
Create Avatar
curl --request POST \
  --url https://api.example.com/avatar-profiles/create
Creates an avatar in your organization’s primary workspace so it can be used by AI Avatar tiles across your workspaces. Processing starts automatically after creation. Provide either a source video URL, or an image URL plus an audio URL. You may include all three if you want separate visual and voice references. Source videos and audio voice references must be between 4 and 15 seconds. Avatar sources should represent one person only. For best results, use direct-to-camera footage with one visible speaker, clear mouth movement, and clean audio from that same person. Avoid background speakers, music, dubbing, heavy noise, overlays, cuts, or other people in frame. If you provide an image plus audio, the image should show the same single person and the audio should be clean single-speaker speech from that person.

​
Request

curl -X POST "https://api.mosaic.so/avatar-profiles/create" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Founder Avatar",
    "sources": {
      "video_url": "https://example.com/founder-reference.mp4"
    }
  }'
Image plus voice-reference audio: 
{
  "name": "Founder Avatar",
  "sources": {
    "image_url": "https://example.com/founder.jpg",
    "audio_url": "https://example.com/founder-voice.wav"
  }
}

​
Parameters

FieldTypeRequiredDescription
namestringYesAvatar display name.
sources.video_urlstring URLConditionalSource video reference. Required unless both sources.image_url and sources.audio_url are supplied. Must be 4-15 seconds, show one person, and contain clear single-speaker audio from that person.
sources.image_urlstring URLConditionalCharacter image reference. Required when no sources.video_url is supplied. Should show one person only.
sources.audio_urlstring URLConditionalVoice reference audio. Required when no sources.video_url is supplied. Must be 4-15 seconds of clean single-speaker speech from the same person shown in the image.
sources.video_idstring UUIDConditionalExisting uploaded video asset ID. Alternative to sources.video_url; should follow the same one-person, clear-audio guidance.
sources.image_idstring UUIDConditionalExisting uploaded image asset ID. Alternative to sources.image_url; should show one person only.
sources.audio_idstring UUIDConditionalExisting uploaded audio asset ID. Alternative to sources.audio_url; should contain clean single-speaker speech.
URL sources are downloaded and stored as Mosaic asset IDs when the avatar is created, so expiring signed URLs are not reused later.

​
Response

Returns the created 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": null,
  "name": "Founder Avatar",
  "status": "processing",
  "status_message": null
}
Use the returned id as avatar_profile_id in an AI Avatar tile immediately. If processing is still running when the agent starts, the run waits for the avatar to become ready.