Sync.so API 립싱크 자동화: 파이썬 3단계로 나레이션 입히기 커버 이미지

Sync.so API 립싱크 자동화: 파이썬 3단계로 나레이션 입히기 (2026년 10월 기준)

by

지난 립싱크·더빙 툴 4종 비교에서 Sync.so를 “API 종량제로 쓰기 가장 좋은 선택지”로 꼽았습니다. 이번 글은 그 후속입니다. 대시보드에서 클릭으로 하는 게 아니라, 파이썬 코드 3단계로 나레이션 오디오를 영상에 자동으로 입히는 전 과정을 정리합니다. 얼굴 없는 채널 파이프라인에서 “캐릭터가 말하는 장면”을 사람 손 없이 뽑는 것이 목표입니다.

준비물: API 키와 요금 구조부터

API 키는 Sync.so 대시보드의 Settings → API Keys에서 발급합니다. 단, 종량제만으로는 쓸 수 없고 구독 플랜에 가입해야 합니다. 2026년 10월 기준 플랜과 모델별 단가는 다음과 같습니다.

항목 Hobbyist $5/월 Creator $19/월 Growth $49/월
영상 최대 길이 1분 5분 10분
동시 생성 1개 3개 6개
종량 단가 할인 – – 5%

생성 비용은 초당 과금입니다(25fps 기준). lipsync-1.9.0-beta가 초당 $0.025, lipsync-2가 $0.05, lipsync-2-pro가 $0.08325, 최신 플래그십 sync-3가 $0.1334입니다. 30초 쇼츠 클립 하나를 lipsync-2로 처리하면 $1.50, 1.9 베타로는 $0.75 수준입니다. 품질·가격 균형으로는 lipsync-2를 기본값으로 추천합니다.

1단계: 생성 요청 보내기

엔드포인트는 하나입니다. POST https://api.sync.so/v2/generate에 영상 URL과 오디오 URL을 넣으면 됩니다. 인증은 x-api-key 헤더입니다.

import requests, time

API_KEY = "sync_xxx"  # 대시보드에서 발급
BASE = "https://api.sync.so/v2"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}

payload = {
    "model": "lipsync-2",
    "input": [
        {"type": "video", "url": "https://내서버/scene01.mp4"},
        {"type": "audio", "url": "https://내서버/narration01.mp3"}
    ],
    "options": {"sync_mode": "cut_off"},
    "outputFileName": "scene01_synced"
}

res = requests.post(BASE + "/generate", headers=HEADERS, json=payload)
job = res.json()
print(job["id"], job["status"])  # 처음엔 PENDING

입력은 공개 URL이 기본입니다. 파일 직접 업로드는 20MB 제한이 있어서, 생성 영상을 S3나 R2 같은 스토리지에 올려두고 URL로 넘기는 쪽이 실무에서 안정적입니다. 요청 자체의 속도 제한은 분당 100회라 개인 파이프라인에서는 걸릴 일이 거의 없습니다.

2단계: 상태 폴링과 결과 다운로드

생성은 비동기로 돌아갑니다. GET /v2/generate/{id}를 주기적으로 조회해서 상태가 끝날 때까지 기다립니다. 상태값은 PENDING → PROCESSING을 거쳐 COMPLETED, FAILED, REJECTED 중 하나로 끝납니다.

while True:
    r = requests.get(BASE + "/generate/" + job["id"], headers=HEADERS).json()
    if r["status"] in ("COMPLETED", "FAILED", "REJECTED"):
        break
    time.sleep(10)

if r["status"] == "COMPLETED":
    video = requests.get(r["outputUrl"]).content
    open("scene01_synced.mp4", "wb").write(video)

상태 조회는 분당 600회까지 허용되지만 10초 간격이면 충분합니다. 폴링이 싫다면 요청에 webhookUrl을 넣어 완료 알림을 HTTPS로 받을 수도 있습니다. 클립이 많을 때는 POST /v2/batch로 한 번에 최대 500건까지 묶어 보낼 수 있습니다.

3단계: 생성 전에 비용 미리 계산하기

자동화 파이프라인에서 제일 무서운 건 조용히 쌓이는 과금입니다. Sync.so는 같은 payload를 POST /v2/analyze/cost에 먼저 보내면 예상 프레임 수(estimatedFrameCount)와 예상 비용(estimatedGenerationCost)을 달러로 돌려줍니다. 파이프라인에 “건당 $2 초과 시 중단” 같은 가드를 넣기에 딱 좋습니다.

영상과 오디오 길이가 다를 때의 처리도 옵션으로 정합니다. sync_mode 기본값인 cut_off는 긴 쪽을 잘라내고, loop는 짧은 쪽을 반복, bounce는 역재생으로 채우고, silence는 무음으로 늘리고, remap은 재생 속도를 조정합니다. 10초 생성 클립에 8초 나레이션을 얹는 흔한 상황이라면 cut_off가 무난합니다.

어떤 모델을 언제 쓰나

대량 처리 초벌에는 lipsync-1.9.0-beta, 업로드용 기본값은 lipsync-2, 클로즈업처럼 입이 크게 잡히는 컷만 lipsync-2-pro로 올리는 식의 계층 운용이 비용 효율이 좋습니다. 2026년 들어 나온 sync-3는 샷 전체를 한 번에 처리하는 방식으로 바뀌면서 손·마이크 같은 가림 요소 자동 처리, 정지 이미지 입력(이미지 한 장을 말하는 영상으로), 4K 네이티브 출력까지 지원합니다. 초당 $0.1334로 비싸지만 무료로 월 1회(15초 이내) 테스트할 수 있으니 품질 차이는 직접 확인해 보세요.

다음 행동

이 코드 두 블록을 설명형 쇼츠 파이프라인의 나레이션 단계 뒤에 붙이면, 대본 → 나레이션 → 영상 → 립싱크까지 사람 개입 없이 이어집니다. 먼저 10초짜리 테스트 클립 하나로 /analyze/cost 응답부터 확인해 보는 것을 추천합니다.

가격·스펙은 2026년 10월 기준 Sync.so 공식 문서(docs)와 요금 페이지에서 확인한 값입니다.

Leave a Comment