spicyapi/talking-avatar-v1/talking-avatar를 사용하면 인물 사진 한 장과 3~60초 길이의 MP3 또는 WAV 음성으로 말하는 MP4를 만들 수 있습니다. 녹음이 말과 타이밍을 정하고, 사진이 얼굴과 장면을 정합니다. 요금은 반환된 1초당 $0.018이며 초 단위로 올림하고 최소 3초가 적용됩니다. 4~5초짜리 대사는 약 1분 안에 렌더링됩니다(60초 녹음은 더 오래 걸립니다). 출력은 약 0.2메가픽셀, 25 fps의 작은 크기여서 카드, 피드, 채팅 창에 알맞고 전체 화면 HD 발표자 영상에는 맞지 않습니다. HD나 더 긴 오디오가 필요하면 끝부분의 Kling Avatar 2.0 항목을 보세요. 실제 출력은 모델 페이지에서 들어볼 수 있습니다.
인물 사진과 녹음 준비하기
이 예제에서는 청록색 블라우스를 입은 가상의 성인 강의 진행자 Mara를 사용합니다. 인물 사진은 다음 조건을 갖추세요.
- 얼굴이 하나만 또렷하게 나오고, 대체로 정면을 향하며, 조명이 고르고, 머리와 어깨가 보일 것
- 입 앞을 가리는 손, 머리카락, 선글라스, 마이크가 없을 것
- JPEG, PNG 또는 WebP이며 10 MB 이하이고, 최종 플레이어에 맞게 턱과 머리 주변에 여백이 있을 것
녹음은 90 MB 이하, 3~60초의 MP3 또는 WAV이며, 목소리는 한 명이고 음악이나 겹치는 화자가 없어야 합니다. 실수로 들어간 무음은 잘라내되 첫 단어와 마지막 단어는 자르지 마세요. 무음도 요금이 매겨지는 길이에 포함됩니다. 3~60초 범위를 벗어난 파일은 요금이 청구되기 전에 거부됩니다.
준비 단계를 그린 삽화이며, Talking Avatar 프레임이 아닙니다.
script, voice_id, language 필드는 없습니다. 다른 언어가 필요하면 다른 오디오 파일을 녹음하거나 생성하고 같은 인물 사진을 다시 사용하세요. 이미 움직이는 발표자의 영상이 있고 음성만 바꾸려는 경우에는 대신 립싱크 워크플로를 사용하세요.
입력
| 입력 | 이 예제에서의 사용 |
|---|---|
image_url | 필수: 승인된 Mara의 인물 사진 |
audio_url | 필수: 내보낸 녹음 |
prompt | 선택: calm and welcoming. 표정에만 영향을 주며 누가 말하는지, 어디에서 말하는지는 바꿀 수 없습니다 |
mask_url | 한 사람이면 생략합니다. 단체 사진이면 같은 크기의 흑백 이미지에서 말하는 사람 위를 흰색으로 칠합니다 |
seed | 선택 사항인 0~2147483647 범위의 정수. 같은 인물 사진에서 두 녹음을 비교하려면 고정하고, 새 테이크를 원하면 생략합니다 |
해상도, 프레임 속도, 길이, 카메라를 지정하는 필드는 없습니다. 16:9 사진은 640×352, 3:4 인물 사진은 400×544로 반환됩니다.
파일은 직접 접근할 수 있는 HTTPS 링크로 가져올 수 있어야 합니다. 페이지나 공유 링크를 가리키는 것보다 업로드하는 쪽이 더 안정적입니다. 업로드한 참조 파일은 오래 유지되지 않으므로 원본은 직접 보관하세요.
요금과 견적이 $1.08인 이유
요금은 반환된 길이를 정수 초로 올림한 값이며 최소 3초입니다.
| 반환된 길이 | 청구 초 | 최종 요금 |
|---|---|---|
| 3초 | 3 | $0.054 |
| 12.2초 | 13 | $0.234 |
| 60초 | 60 | $1.08 |
견적과 작업 생성 시 잡히는 예약 금액은 60초 상한인 $1.08입니다. 오디오 길이와 관계없이 같습니다. 클립이 완성되면 최종 요금은 실제 길이로 정산되고 나머지는 해제됩니다. 작업이 실패하면 예약 금액 전체가 해제됩니다. 그때까지는 예약 금액이 잔액과 지출 한도에 반영되므로, 잔액이 거의 없거나 한도가 빠듯하면 12초짜리 클립도 막힐 수 있습니다. 견적을 조회하는 것만으로는 아무것도 예약되지 않습니다.
먼저 Playground에서 시험해 보기
- Talking Avatar 모델 페이지를 열고 Playground 탭의 Form 보기를 유지하세요. 실행하려면 잔액이 있는 계정으로 로그인해야 하며, 로그인하면 가격이 표시됩니다.
- Input image에 Mara의 인물 사진을 놓거나 Add URL로 링크를 붙여 넣으세요.
- Input audio에 MP3 또는 WAV를 같은 방법으로 추가하세요. 링크보다 업로드가 더 안정적입니다.
- 원하면 Prompt에 표정을 나타내는 짧은 말(
calm and welcoming)을 입력하고, 단체 사진이면 Mask를 추가하고, 두 녹음을 비교하려면 Seed를 설정하세요. - 실행한 뒤 실제로 표시할 크기에서 소리를 켜고 결과를 재생하세요.
Playground는 API와 같은 요청을 보내므로, 여기서 동작하는 인물 사진과 녹음은 코드에서도 동작합니다. 여기서 입 모양을 읽기 어렵다면 코드를 쓰기 전에 원본 파일부터 고치세요.
그다음 코드에서 호출하기
Python SDK를 설치하고(pip install spicyapi), SPICY_API_KEY를 설정한 뒤 아래 코드를 실행하세요. 작업을 만들 때 요금이 청구되며, 예약 금액은 위에서 설명한 상한 $1.08입니다.
import shutil
import urllib.request
import uuid
from spicyapi import SpicyClient, output_assets
client = SpicyClient() # reads SPICY_API_KEY from the environment
portrait = client.upload_file("./mara.png") # local files become spicy:// URIs
speech = client.upload_file("./mara-intro.mp3")
task = client.create_task(
model="spicyapi/talking-avatar-v1/talking-avatar",
input_data={
"image_url": portrait["uri"],
"audio_url": speech["uri"],
"prompt": "calm and welcoming",
"seed": 42,
},
idempotency_key=str(uuid.uuid4()), # new key per new request; reuse only to retry the same one
)
final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
raise RuntimeError(f"Task {task['taskId']} ended as {final['state']}")
url = output_assets(final)[0]["url"]
request = urllib.request.Request(url, headers={"User-Agent": "avatar-example/1.0"}) # default Python clients can get a 403
with urllib.request.urlopen(request, timeout=60) as response, open("avatar.mp4", "wb") as target:
shutil.copyfileobj(response, target)
print("Saved avatar.mp4")견적, 대기, 재시도, 오류는 Python SDK 레퍼런스와 비동기 작업 가이드에 나와 있습니다. 접수된 작업은 취소할 수 없으므로 실행하기 전에 가격을 확인하세요. 결과 링크는 일시적이므로 생성한 미디어를 오래 보관하는 방법에서 설명하듯 직접 사본을 저장하세요.
에이전트에게 실행시키기
어시스턴트가 클립을 만들게 하려면 CLI나 MCP 서버를 주세요. 둘 다 가격을 보여 주고 유료 호출 전에 확인을 요청합니다. Skill은 둘 중 어느 쪽 위에든 지침을 더합니다.
- CLI.
spicyapi는 터미널에서 작업 하나를 실행합니다(npx @spicyapi/cli는 설치 없이 동작합니다).
``bash spicyapi files upload ./mara.png # prints a spicy:// URI; repeat for the audio spicyapi tasks create --model spicyapi/talking-avatar-v1/talking-avatar \ --input-file input.json --wait ``
input.json에는 위와 같은 input 객체와 두 개의 spicy:// URI가 들어갑니다.
- MCP 서버. 어시스턴트에 MCP 서버를 추가한 뒤 "Make Mara speak ./mara-intro.mp3 using ./mara.png with Talking Avatar."라고 요청하세요.
spicyapi_upload_file,spicyapi_task_create(가격 확인을 위해 멈춥니다),spicyapi_task_wait순서로 호출합니다.
``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``
- Skill.
npx skills add spicyapi-ai/spicy-skill은 Agent Skill을 설치하며, 코딩 어시스턴트가 추측하지 않고 최신 스키마를 읽고 멱등성 키를 재사용하도록 가르칩니다. Skill 자체로는 작업을 실행할 수 없으므로 CLI 또는 MCP와 함께 사용하세요.
문제는 원본에서 고치기
avatar.mp4를 실제로 표시할 크기에서 소리를 켜고 재생해, 눈, 얼굴 윤곽, 헤어라인을 원본 인물 사진과 비교하세요. 입이 움직인다는 사실만으로는 캐릭터가 일관되게 유지되었다고 할 수 없습니다.
| 증상 | 다음 단계 |
|---|---|
| 얼굴이 작거나 입 모양을 읽기 어려움 | 턱이 보이도록 머리와 어깨까지로 원본을 크롭해 다시 제출 |
| 말이 급하거나 발음이 부정확함 | 다시 녹음하세요. 분위기 프롬프트로는 단어도 속도도 고칠 수 없습니다 |
| 음악이나 여러 목소리 때문에 음성이 뭉개짐 | 목소리가 하나뿐인 깨끗한 녹음을 내보내고 음악은 애니메이션 뒤에 추가 |
| 단체 사진에서 엉뚱한 사람이 말함 | 인물 사진과 정확히 같은 크기의 마스크를 추가하고 말하는 사람 위를 흰색으로 |
| 편집 후 일정한 오디오 어긋남 | 내려받은 원본과 내보낸 파일을 비교하고 편집에서 트랙 타이밍을 수정 |
| 한 구절에서 입이나 치아 움직임이 어색함 | 더 선명한 인물 사진을 쓰거나 그 구절을 더 천천히 읽기 |
동일 인물 여부 확인을 그린 삽화입니다. 인쇄된 인물 사진은 만들어 낸 그림이며 아바타 프레임이 아닙니다.
콘텐츠 규칙과 다른 모델을 고를 때
SpicyAPI는 Talking Avatar v1에 안전 검사를 추가하지 않으며, 무엇이 반환될지는 모델이 직접 결정합니다. 모델이 감지하지 못하는 얼굴이나 거부된 이미지는 작업을 실패시킵니다. 가상의 인물 사진이나 동의한 성인의 사진만 사용하세요.
Kling Avatar 2.0도 인물 사진과 오디오를 받으며, 720p(초당 $0.0512) 또는 1080p(초당 $0.1024)로 최대 약 5분 길이의 클립을 만들 수 있습니다. 이 모델은 필터가 적용된 모델이라 노골적인 인물 사진은 거부되므로, 성인 대상 캐릭터보다는 발표자나 브랜드 클립에 알맞습니다. 카드 크기의 짧고 저렴한 클립에는 Talking Avatar v1을, 전체 크기에서 선명해야 하거나 1분보다 길어야 하는 클립에는 Kling Avatar 2.0을 고르세요.
