> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mosaic.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Avatar

> Create a reusable AI Avatar from source media.

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

```bash theme={null}
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:

```json theme={null}
{
  "name": "Founder Avatar",
  "sources": {
    "image_url": "https://example.com/founder.jpg",
    "audio_url": "https://example.com/founder-voice.wav"
  }
}
```

## Parameters

| Field               | Type        | Required    | Description                                                                                                                                                                                            |
| ------------------- | ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`              | string      | Yes         | Avatar display name.                                                                                                                                                                                   |
| `sources.video_url` | string URL  | Conditional | Source 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_url` | string URL  | Conditional | Character image reference. Required when no `sources.video_url` is supplied. Should show one person only.                                                                                              |
| `sources.audio_url` | string URL  | Conditional | Voice 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_id`  | string UUID | Conditional | Existing uploaded video asset ID. Alternative to `sources.video_url`; should follow the same one-person, clear-audio guidance.                                                                         |
| `sources.image_id`  | string UUID | Conditional | Existing uploaded image asset ID. Alternative to `sources.image_url`; should show one person only.                                                                                                     |
| `sources.audio_id`  | string UUID | Conditional | Existing uploaded audio asset ID. Alternative to `sources.audio_url`; should contain clean single-speaker speech.                                                                                      |

<Note>URL sources are downloaded and stored as Mosaic asset IDs when the avatar is created, so expiring signed URLs are not reused later.</Note>

## Response

Returns the created avatar profile. The response shape is:

| Field               | Type                                               | Description                                                                                                                                                                                     |
| ------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                | string UUID                                        | Avatar profile ID. Pass this as `avatar_profile_id` in an AI Avatar tile.                                                                                                                       |
| `video_preview_url` | string URL \| null                                 | Signed video preview URL. This is `null` until a preview/reference video is available.                                                                                                          |
| `name`              | string                                             | Avatar 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_message`    | string \| null                                     | Error message when `status` is `failed`; otherwise `null`.                                                                                                                                      |

```json theme={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.