---
title: "Generate a new avatar (async)"
method: POST
path: "/v1/avatars"
tags: ["Avatars"]
---

# Generate a new avatar (async)

`POST /v1/avatars`

## Request

- Base URL: `https://api.vivideo.ai`
- URL: `https://api.vivideo.ai/v1/avatars`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/vivideo/apis/vivideo-api/docs/v1/avatars/post.ts> (a function with typed inputs; its response is checked against the schema)

`kind: "prompt"` designs an AI avatar from a text description (no real
person). `kind: "photo"` builds an avatar from a photo and requires
`consent: true` plus a `file_url` or `asset_id`. Training runs in the
background — poll `GET /v1/avatars/{id}`. Free accounts may create one
avatar; more requires premium.

## Request body

- object
  - `kind` 'prompt' | 'photo', required
  - `name` string, required
  - `prompt` string: For kind=prompt.
  - `file_url` string: For kind=photo: https URL of the photo.
  - `asset_id` string: Alternative to file_url: an uploaded asset id.
  - `consent` boolean: Required true for kind=photo.
  - `reference_images` string[]

## Response `201`

Avatar creation started.

- Avatar
  - `id` string: avatar_ref (av_...) for your avatars, or the catalogue avatar_id.
  - `object` string
  - `name` string
  - `kind` 'prompt' | 'photo'
  - `status` string
  - `ready` boolean
  - `gender` string
  - `preview_image_url` string
  - `preview_video_url` string
  - `looks` object[]

## Other responses

- `400`: Invalid parameters (`invalid_request`, `unknown_model`, `invalid_url`).
- `401`: Missing, malformed or revoked API key (`missing_api_key`, `invalid_api_key`, `api_key_revoked`).
- `403`: Premium plan required or the free allowance is used (`upgrade_required`, `free_limit_reached`); `links.upgrade` = https://app.vivideo.ai/upgrade.
- `429`: Rate limit hit (`rate_limited`). Honor the `Retry-After` header / `retry_after_seconds` field.

---

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