---
title: Create new avatar
description: Create a reusable avatar with Prompt, Profile, or Image inputs.
---

There are three ways to make an avatar:

1. **Prompt**: describe the avatar you want.
2. **Profile**: provide structured traits for the avatar.
3. **Image**: use a reference image.

Each request creates a job. Poll the job until it completes, then use the
returned avatar handle or resource id to generate avatar videos.

Prefer the canonical Avatar 1.0 route:

```text
POST /v1/avatar-1.0/generate
```

Avatar creation uses a top-level `avatar_handle` plus an `input` union. The
handle may include a leading `@`; Sume stores it normalized without `@`.

## 1. Prompt

Use this when you want to create an avatar from text only.

<!-- api-call-example:avatar-generate -->

## 2. Profile

Use this when your app already has profile details for the avatar. In the API,
this uses the `props` input type.

```bash
curl -X POST https://api.sume.com/v1/avatar-1.0/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: avatar-profile-001" \
  -d '{
    "avatar_handle": "product_host",
    "input": {
      "type": "props",
      "ethnicity": "Asian",
      "sex": "female",
      "age": 28
    }
  }'
```

## 3. Image

Use this when you have a reference image. In the API, this uses the `photo`
input type.

```bash
curl -X POST https://api.sume.com/v1/avatar-1.0/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: avatar-image-001" \
  -d '{
    "avatar_handle": "reference_presenter",
    "input": {
      "type": "photo",
      "image_url": "https://example.com/reference.png"
    }
  }'
```

`image_url` must be a fetchable public HTTPS image URL. Localhost,
private-network URLs, non-HTTPS URLs, and non-image responses are rejected
before generation submission. See [Media inputs](/workflows/asset-library).

## Poll the job

```bash
curl https://api.sume.com/v1/jobs/job_123/status \
  -H "Authorization: Bearer $SUME_API_KEY"
```

Fetch the result when the job is `completed`.

```bash
curl https://api.sume.com/v1/jobs/job_123/result \
  -H "Authorization: Bearer $SUME_API_KEY"
```

## Read avatar resources

Prefer the Avatar 1.0 resource routes:

```bash
curl https://api.sume.com/v1/avatar-1.0/avatars \
  -H "Authorization: Bearer $SUME_API_KEY"

curl https://api.sume.com/v1/avatar-1.0/avatars/avatar_123 \
  -H "Authorization: Bearer $SUME_API_KEY"
```

## Compatibility aliases

These older paths remain supported and share the same request body:

| Alias | Notes |
|---|---|
| `POST /v1/models/sume/avatar-1.0/generate/runs` | Canonical model-run alias. Prefer `/v1/avatar-1.0/generate` for new integrations. |
| `POST /v1/models/sume/avatar/v1.0/runs` | Legacy launch alias. |
| `GET /v1/avatars`, `GET /v1/avatars/:id` | Compatibility list/read routes. Response shape matches `/v1/avatar-1.0/avatars`. |

## Next

Use the returned avatar handle on [Generate avatar video](/models/avatar-videos).
For first-frame review before a full render, see
[Avatar video previews](/models/avatar-video-previews).