Python으로 말하는 아바타 만들기: Sume API 활용

Python으로 말하는 아바타를 만들려면 Requests 라이브러리로 Job 두 개를 실행하세요. 하나는 텍스트 프롬프트, 프로필, 사진 중 하나로 아바타를 만들고, 다른 하나는 아바타에게 말할 스크립트를 보냅니다. Sume에서는 각각 POST /v1/avatar-1.0/generate와 POST /v1/avatar-1.0/talking-video입니다. 각 Job을 끝날 때까지 폴링한 다음 영상의 URL을 읽으세요.

Sume 관련 사실은 아바타 만들기, 아바타 영상 생성, Job과 결과 (영문) 문서와 Sume API 레퍼런스에서, Requests의 동작은 Requests의 빠른 시작에서 가져왔습니다. 모두 2026-09-27에 확인했습니다. Sume 문서는 TypeScript SDK인 @sume-com/sdk를 다루지만, 이 스크립트는 대신 Requests로 일반 HTTPS 호출을 합니다. Python으로 텍스트에서 영상을 만드는 기본 Job은 Python Text-to-Video API를 참고하세요.

스크립트를 실행하기 전에 무엇이 필요한가요?

• requests 패키지를 설치한 Python과 SUME_API_KEY 환경 변수에 넣은 Sume API 키. 키는 서버나 자신의 컴퓨터에만 두고, 프런트엔드 JavaScript나 모바일 앱에는 절대 넣지 마세요.
• 아바타 handle: 글자, 숫자, 밑줄, 마침표로 이루어진 2~30자이며, 하이픈은 쓸 수 없고, 마침표나 밑줄은 맨 앞이나 맨 뒤에 오거나 두 번 연속으로 올 수 없습니다. Sume는 handle을 소문자로 저장하며, sume_ 접두사는 Sume 자체 아바타용으로 예약되어 있습니다.
• 입력: 텍스트 프롬프트, 프로필, 공개 HTTPS 사진 URL 중 하나. 세 가지는 재사용 가능한 AI 아바타 만들기에서 비교하며, 이 스크립트는 프롬프트를 씁니다.

Python으로 아바타를 어떻게 만드나요?

post()는 json=으로 JSON을 보내며(Requests가 인코딩하고 application/json으로 표시합니다), Idempotency-Key도 함께 보냅니다. 호출이 타임아웃되면 같은 키와 같은 본문으로 다시 보내세요. 그러면 Sume는 두 번째 유료 Job을 시작하지 않고 원래 Job을 돌려줍니다. wait()는 Sume가 제안하는 next_poll_after_seconds만큼 기다리면서 terminal이 true가 될 때까지 Job의 status_url을 폴링한 뒤 sume_status를 반환합니다. 값은 completed, failed, canceled 중 하나입니다. 모든 호출에 timeout을 설정하는 이유는 Requests가 이 값 없이는 타임아웃되지 않기 때문입니다.

import os, time, requests

API = "https://api.sume.com/v1"
AUTH = {"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"}

def post(path, body, key):
    return requests.post(API + path, json=body, timeout=30,
                         headers={**AUTH, "Idempotency-Key": key})

def wait(url):  # poll a job's status_url until it is terminal
    while True:
        r = requests.get(url, headers=AUTH, timeout=30)
        r.raise_for_status()
        s = r.json()["data"]
        if s["terminal"]:
            return s["sume_status"]
        time.sleep(s["next_poll_after_seconds"] or 10)

prompt = {"type": "prompt", "prompt": "A friendly presenter in a bright studio"}
r = post("/avatar-1.0/generate", {"avatar_handle": "demo_host", "input": prompt}, "demo-host-v1")
r.raise_for_status()
assert wait(r.json()["data"]["status_url"]) == "completed"

아바타가 말하게 하려면 어떻게 하나요?

handle과 script를 talking-video 라우트로 보내고 그 Job을 기다린 다음, 제출 응답이 avatar_video_id로 알려 주는 아바타 영상 리소스에서 video_url을 읽으세요. 현재 코드에서 아바타는 영어로만 말하므로 스크립트는 영어로 쓰고, 추정 4~60초 안에 맞추세요. 단어 수 계산은 60초에 들어가는 단어 수에서 설명합니다.

body = {"avatar_handle": "demo_host", "script": "Hi! A Python script made this whole video."}
r = post("/avatar-1.0/talking-video", body, "demo-video-v1")
r.raise_for_status()  # 409 avatar_not_ready: the avatar or its voice isn't ready; resend later
job = r.json()["data"]
assert wait(job["status_url"]) == "completed"
res = requests.get(f"{API}/avatar-videos/{job['avatar_video_id']}", headers=AUTH, timeout=30)
res.raise_for_status()
print(res.json()["data"]["avatar_video"]["video_url"])

각 호출은 무엇을 반환하나요?

응답은 필드를 data로 감쌉니다. 스크립트가 읽는 필드는 다음과 같습니다.

폴링 대신 sync 모드로 기다리면 안 되나요?

두 생성 요청 모두 기본값은 async입니다. sync는 요청을 최대 30초까지만 붙잡아 두는데, 문서에 따르면 아바타 영상 Job은 대개 그보다 오래 걸리므로 어차피 폴링하게 됩니다. 클라이언트 쪽 타임아웃은 Job을 취소하지 않습니다. Job은 계속 실행되고 요금도 청구되므로, 다시 제출하지 말고 status_url을 저장해 두었다가 폴링을 이어 가세요.

현재 코드에서는 아바타가 준비되지 않았을 때 요청한 말하는 영상이 409 avatar_not_ready로 거부되며, "Avatar voice is not ready for video generation." 메시지는 아바타는 있지만 그 음성이 아직 준비되지 않았다는 뜻입니다. 아바타 리소스인 GET /v1/avatar-1.0/avatars/{id}는 voice.status를 processing, ready, failed 중 하나로 알려 줍니다.

비용은 얼마이고, 어떤 제한이 있나요?

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

• quality의 기본값은 plus, aspect_ratio의 기본값은 9:16이며, 문서에 나온 해상도는 720p입니다.
• 영상 하나는 추정 4~60초를 다룹니다. 더 긴 스크립트는 여러 Job으로 나누세요.
• 문서에는 captions가, API 레퍼런스에는 package가 이 라우트의 필드로 나와 있지만, 현재 코드에서 talking-video 라우트는 captions와 package를 400 invalid_request로 거부합니다. 아바타 영상 프리뷰는 둘 다 저장해 두었다가 generate-video에서 적용합니다. 이 흐름은 아바타 영상 프리뷰에서 다룹니다.