Create a new Avatar

Creates a new avatar.

POST /avatars

Try it

Create a new Avatar

cURL

curl --request POST \
  --url https://api.argil.ai/v1/avatars \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "type": "IMAGE",
  "name": "<string>",
  "datasetImage": {
    "url": "<string>"
  },
  "voiceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "extras": {}
}
'

201

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "actorName": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "gestures": [
    {
      "label": "<string>",
      "slug": "<string>",
      "startFrame": 123
    }
  ],
  "status": "NOT_TRAINED",
  "width": 123,
  "height": 123,
  "thumbnailUrl": "<string>",
  "coverImageUrl": "<string>",
  "extras": {},
  "orientation": "ASPECT_RATIO_16_9",
  "model": "ARGIL_V1"
}

This endpoint is deprecated. Video-based avatar creation will be removed in a future version. Please use image-based avatar creation instead.

Overview

Create a new avatar from a video. This method requires both a dataset video and a consent video.

Deprecation Notice: This video-based avatar creation method is deprecated and will be removed in a future API version. Migrate to image-based avatar creation for better performance and simpler workflow.

Video Requirements

Dataset Video:

• Duration: 1-5 minutes
• Format: MP4 or MOV
• Resolution: Between 720p and 4K
• Max size: 1.5GB
• Protocol: HTTPS only

Consent Video:

• Duration: 30 seconds or less
• Format: MP4 or MOV
• Max size: 100MB
• Protocol: HTTPS only

Optional Fields

• extras: Custom metadata dictionary (max 10 key-value pairs, 256 characters each)

Authorizations

x-api-key · string · header · required

API key to be included in the x-api-key header

Body

application/json

type · enum<string> · required

Avatar creation type - must be 'IMAGE' for image-based avatars

Available options: IMAGE

name · string · required

Name of the avatar

Required string length: 1 - 256

datasetImage · Image URL · object · required

Image source for avatar creation. Either 'url' or 'base64' must be provided.

Image URL

Base64 Image

Show child attributes

datasetImage. 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

voiceId · string<uuid>

Optional voice ID to use for this avatar. If not provided, a voice design will be automatically created from the image.

extras · object

Optional dictionary of custom key-value pairs to extend the avatar metadata. Maximum of 10 key-value pairs of 256 characters allowed

Show child attributes

extras. {key} · string

Response

201

application/json

Successfully created Avatar. The training process will start automatically.

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.

Show child attributes

gestures. label · string

A label for user readability. Can be setup from the app's UI.

gestures. slug · string

Allows identifying the gesture when using it for a specific moment.

gestures. startFrame · number

The startFrame of the source Avatar video to be used as start for the video template.

status · enum<string>

• 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

Available options: NOT_TRAINED, TRAINING, TRAINING_FAILED, IDLE, REFUSED

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.

Show child attributes

extras. {key} · string

orientation · enum<string>

Available options: ASPECT_RATIO_16_9, ASPECT_RATIO_9_16

model · enum<string>

Available options: ARGIL_V1, ARGIL_ATOM