2026-09-25Sume Avatar 1.0

Sume Avatar 1.0 API로 재사용 가능한 AI 아바타 만들기

POST /v1/avatar-1.0/generate에 avatar_handle과 프롬프트·프로필·이미지 중 한 가지 입력을 보내세요. Job을 폴링한 뒤 handle을 아바타 영상에 재사용하세요.

읽는 시간 5분Sume

Sume에서 재사용 가능한 AI 아바타를 만들려면 POST /v1/avatar-1.0/generate로 avatar_handle과 input을 보내세요. input은 텍스트 프롬프트, 구조화된 프로필 특성, 레퍼런스 이미지 중 하나로 만듭니다. 이 요청은 Job을 만듭니다. Job이 완료되면 반환된 아바타 handle이나 리소스 id로 아바타 영상을 생성합니다.

아래 API 세부 사항은 모두 아바타 만들기 문서 페이지에서 가져왔습니다.

아바타를 만드는 세 가지 방법은 무엇인가요?

모든 요청에는 최상위 avatar_handle과 input 유니온이 들어갑니다. 다음 세 가지 입력 중 하나를 고르세요.

아바타 만들기 기준, 2026-09-25 확인.
방법	사용 시점	input에 넣는 값
Prompt	텍스트만으로 아바타를 만들고 싶을 때	원하는 아바타에 대한 설명입니다.
Profile	앱에 이미 아바타의 프로필 정보가 있을 때	구조화된 특성을 담은 `props` 입력 타입입니다. 문서 예시는 `ethnicity`, `sex`, `age`를 보냅니다.
Image	레퍼런스 이미지가 있을 때	`image_url`을 담은 `photo` 입력 타입입니다.

생성 요청은 어떤 형태인가요?

아래 요청은 레퍼런스 이미지로 아바타를 만듭니다. 공개 image_url과 함께 photo 입력 타입을 사용합니다. handle 앞에는 @를 붙여도 되며, Sume는 @를 뺀 형태로 정규화해 저장합니다.

Profile 방식이라면 문서 예시처럼 input을 { "type": "props", "ethnicity": "Asian", "sex": "female", "age": 28 }로 바꾸세요. 문서 예시들은 이 요청처럼 Idempotency-Key 헤더를 보냅니다. AI 영상 API 멱등성 키를 참고하세요.

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"
    }
  }'

아바타 생성은 어떤 이미지 URL을 거부하나요?

image_url은 가져올 수 있는 공개 HTTPS 이미지 URL이어야 합니다(미디어 입력 참고). Sume는 생성 제출 전에 다음 URL을 거부합니다.

localhost URL
사설 네트워크 URL
HTTPS가 아닌 URL
응답이 이미지가 아닌 URL

아바타가 준비됐는지 어떻게 알 수 있나요?

Job을 폴링하다가 상태가 completed가 되면 결과를 가져오세요. job_123은 해당 Job의 id로 바꾸세요.

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

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

새 연동에서는 어떤 아바타 라우트를 써야 하나요?

정식 Avatar 1.0 라우트를 우선 사용하세요. 예전 경로도 계속 지원되며 요청 본문이 같습니다.

아바타 만들기 기준, 2026-09-25 확인.
라우트	역할
`POST /v1/avatar-1.0/generate`	정식 생성 라우트입니다. 새 연동에는 이 라우트를 우선 사용하세요.
`GET /v1/avatar-1.0/avatars`	권장 리소스 라우트입니다. 아바타 목록을 가져옵니다.
`GET /v1/avatar-1.0/avatars/avatar_123`	권장 리소스 라우트입니다. 아바타 하나를 읽습니다.
`POST /v1/models/sume/avatar-1.0/generate/runs`	정식 model-run 별칭입니다.
`POST /v1/models/sume/avatar/v1.0/runs`	레거시 실행 별칭입니다.
`GET /v1/avatars`, `GET /v1/avatars/:id`	호환용 목록·조회 라우트입니다. 응답 형태는 `/v1/avatar-1.0/avatars`와 같습니다.

아바타 생성 비용은 얼마인가요?

API 요금에는 아바타 생성이 아바타당 $0.95로 나와 있으며, 여기에 기본 5.5% 에이전트 수수료가 더해집니다. 이후 이 아바타로 생성하는 영상은 품질 등급별로 초 단위 요금이 매겨집니다. 요율은 초당 $0.184(standard), $0.245(plus), $0.55(max), 제품 이미지 없음 기준이며, 여기에도 에이전트 수수료가 더해집니다.

아바타를 만든 다음에는 무엇을 하나요?

반환된 아바타 handle은 아바타 영상 생성에서 사용하세요. 요청 하나를 따라가 보는 과정은 말하는 아바타 영상 API에서 다룹니다. 전체 렌더 전에 첫 프레임을 검토하려면 아바타 영상 프리뷰부터 시작하세요. 이 흐름은 아바타 영상 프리뷰: 첫 프레임 승인하기에서 설명합니다.

출처

작성자 Sume