---
title: "Create a new Avatar"
method: POST
path: "/avatars"
---

# Create a new Avatar

`POST /avatars`

Creates a new avatar.

## Request body

- AvatarCreateArgsImage
  - `type` 'IMAGE', required — Avatar creation type - must be 'IMAGE' for image-based avatars
  - `name` string, required — Name of the avatar
  - `datasetImage` union, required — Image source for avatar creation. Either 'url' or 'base64' must be provided.
    - object
      - `url` string, uri, required — HTTPS URL to the source image for training. Must meet the following requirements: - Format: PNG, JPEG, or WEBP - Resolution: Between 720p (1280x720 or 720x1280) and 4K (3840x2160 or 2160x3840) - Aspect ratio: 16:9 (landscape) or 9:16 (portrait) - Max size: 10MB
    - object
      - `base64` string, required — Base64-encoded image data. Must be in format: data:image/{format};base64,{data} - Format: PNG, JPEG, or WEBP - Resolution: Between 720p (1280x720 or 720x1280) and 4K (3840x2160 or 2160x3840) - Aspect ratio: 16:9 (landscape) or 9:16 (portrait) - Max size: 10MB
  - `voiceId` string, uuid — Optional voice ID to use for this avatar. If not provided, a voice design will be automatically created from the image.
  - `callbackUrl` string, uri — Optional HTTPS URL that receives a one-shot POST notification when avatar training completes or fails. On success, sends `{ "event": "AVATAR_TRAINING_SUCCESS", "data": { "avatarId", "avatarName", "voiceId", "message" } }`. On failure (after all retries), sends `{ "event": "AVATAR_TRAINING_FAILED", "data": { "avatarId", "avatarName", "message" } }`.
  - `extras` object — Optional dictionary of custom key-value pairs to extend the avatar metadata. Maximum of 10 key-value pairs of 256 characters allowed

## Response `201`

Successfully created Avatar. The training process will start automatically.

- Avatar
  - `id` string, uuid
  - `name` string
  - `actorName` string
  - `createdAt` string, date-time
  - `updatedAt` string, date-time
  - `gestures` object[] — A list of labelized gestures available for your avatar.
    - `label` string — A label for user readability. Can be setup from the app's UI.
    - `slug` string — Allows identifying the gesture when using it for a specific moment.
    - `startFrame` number — The startFrame of the source Avatar video to be used as start for the video template.
  - `status` 'NOT_TRAINED' | 'TRAINING' | 'TRAINING_FAILED' | 'IDLE' | 'REFUSED' — * NOT_TRAINED - Initial state after VIDEO mode avatar creation (before training starts) * TRAINING - Avatar is currently training. For IMAGE mode avatars, this is the initial status after creation. * TRAINING_FAILED - Training process failed * IDLE - Avatar is ready to use * REFUSED - Avatar was refused by moderation
  - `width` integer
  - `height` integer
  - `thumbnailUrl` string — The url of the thumbnail of the avatar (low resolution).
  - `coverImageUrl` string — The url of the cover image of the avatar (high resolution).
  - `extras` object — A dictionary of custom key-value pairs to extend the Avatar metadata. Maximum of 5 key-value pairs of 256 characters allowed.
  - `orientation` 'ASPECT_RATIO_16_9' | 'ASPECT_RATIO_9_16'
  - `model` 'ARGIL_V1' | 'ARGIL_ATOM'

## Other responses

- `400` — Validation error

## Changes

- **2026-03-13** `025ac5a8b5df` — 1 info
  - added the new optional request property `callbackUrl`
- **2025-12-03** `8deefa349e1d` — 2 breaking, 3 warning, 2 info
  - added the new required request property `datasetImage`
  - added the new required request property `type`
  - removed the request property `consentVideo`
  - removed the request property `datasetVideo`
  - …3 more
- **2025-10-24** `9346a335d8ce` — 3 info
  - added the optional property `actorName` to the response with the `201` status
  - added the optional property `model` to the response with the `201` status
  - added the optional property `orientation` to the response with the `201` status
- **2025-04-10** `0f305512c004` — 1 info
  - added the optional property `coverImageUrl` to the response with the `201` status

[Change history](https://skmtc.dev/argildotai/apis/argil-api/changes/avatars/post.md)

---

[API](https://skmtc.dev/argildotai/apis/argil-api.md) · [All operations](https://skmtc.dev/argildotai/apis/argil-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/argildotai/argil-api/revisions/f3d0315da0f0/schema)