---
title: "Create avatar"
method: POST
path: "/avatar-profiles/create"
tags: ["Avatar Profiles"]
---

# Create avatar

`POST /avatar-profiles/create`

## Request

- Base URL: `https://api.mosaic.so`
- URL: `https://api.mosaic.so/avatar-profiles/create`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Create a reusable AI Avatar in the organization's primary workspace. Provide either a video source or an image plus audio source. Sources should represent one person only, with clean single-speaker audio from that person. URL sources are stored as Mosaic asset records.

## Request body

- object
  - `name` string, required
  - `sources` object, required: Avatar source media. Required: either video_url/video_id, or image_url/image_id plus audio_url/audio_id. Use one visible person and clean single-speaker audio from that same person.
    - `video_url` string, uri, nullable: 4-15 second source video URL. Should show one person and contain clean single-speaker audio from that person.
    - `audio_url` string, uri, nullable: 4-15 second voice reference audio URL. Should contain clean single-speaker speech from the same person shown in the image.
    - `image_url` string, uri, nullable: Character image URL. Should show one person only.
    - `video_id` string, uuid, nullable: Existing video asset ID. Should follow the same one-person, clear-audio guidance.
    - `audio_id` string, uuid, nullable: Existing audio asset ID. Should contain clean single-speaker speech.
    - `image_id` string, uuid, nullable: Existing image asset ID. Should show one person only.

## Response `201`

Avatar profile created

- object
  - `id` string, uuid, required: Avatar profile ID. Pass this as avatar_profile_id in an AI Avatar tile.
  - `video_preview_url` string, uri, nullable, required: Signed video preview URL. Null until a preview/reference video is available.
  - `name` string, required: Avatar display name.
  - `status` 'pending' | 'processing' | 'ready' | 'failed', required: Avatar processing state. Ready means fully prepared; pending/processing can be used while the run waits; failed cannot be used.
  - `status_message` string, nullable, required: Error message when status is failed; otherwise null.

## Other responses

- `400`: Invalid request
- `401`: Authentication failed
- `403`: Access denied
- `409`: Conflict

---

[API](https://skmtc.dev/mosaic/apis/mosaic-ai-api.md) - [All operations](https://skmtc.dev/mosaic/apis/mosaic-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mosaic/apis/mosaic-ai-api/revisions/c20e9fc606a4?raw)