---
title: 아바타 만들기
description: Prompt, Profile, Image 입력으로 재사용 가능한 아바타를 만드는 방법을 살펴보세요.
---

아바타를 만드는 방법은 세 가지입니다.

1. **Prompt**: 원하는 아바타를 글로 설명합니다.
2. **Profile**: 아바타의 구조화된 특성을 제공합니다.
3. **Image**: 레퍼런스 이미지를 사용합니다.

각 요청은 Job을 만듭니다. Job이 완료될 때까지 폴링한 다음, 반환된 아바타
handle이나 리소스 id로 아바타 비디오를 생성하세요.

정식 Avatar 1.0 라우트를 사용하세요.

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

아바타 생성은 최상위 `avatar_handle`과 `input` 유니온을 사용합니다. handle 앞에
`@`를 붙여도 되며, Sume는 `@`를 뺀 형태로 정규화해 저장합니다.

## 1. Prompt

텍스트만으로 아바타를 만들고 싶을 때 사용하세요.

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

## 2. Profile

앱에 이미 아바타의 프로필 정보가 있을 때 사용하세요. API에서는 `props` 입력
타입을 씁니다.

```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

레퍼런스 이미지가 있을 때 사용하세요. API에서는 `photo` 입력 타입을 씁니다.

```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`은 가져올 수 있는 공개 HTTPS 이미지 URL이어야 합니다. localhost,
사설 네트워크 URL, HTTPS가 아닌 URL, 이미지가 아닌 응답은 생성 제출 전에
거부됩니다. [미디어 입력](/workflows/asset-library)에서 살펴보세요.

## Job 폴링하기

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

Job이 `completed`가 되면 결과를 가져오세요.

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

## 아바타 리소스 읽기

Avatar 1.0 리소스 라우트를 사용하세요.

```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"
```

## 호환 별칭

다음 예전 경로들도 계속 지원하며 Request Body는 같습니다.

| 별칭 | 설명 |
|---|---|
| `POST /v1/models/sume/avatar-1.0/generate/runs` | 정식 model-run 별칭입니다. 새 연동에는 `/v1/avatar-1.0/generate`를 사용하세요. |
| `POST /v1/models/sume/avatar/v1.0/runs` | 레거시 실행 별칭입니다. |
| `GET /v1/avatars`, `GET /v1/avatars/:id` | 호환용 목록·조회 라우트입니다. 응답 형태는 `/v1/avatar-1.0/avatars`와 같습니다. |

## 다음

반환된 아바타 handle을 [아바타 비디오 생성](/models/avatar-videos)에서
사용하세요. 전체 렌더 전에 첫 프레임을 확인하려면
[아바타 비디오 프리뷰](/models/avatar-video-previews)를 살펴보세요.