PixVerse 립 싱크 API 튜토리얼: 업로드, 생성, 폴링 및 검토

AI Overview

PixVerse 립 싱크 API는 무엇을 필요로 하나요?

하나의 영상 참조 자료와 하나의 음성 소스가 필요합니다. 영상은 PixVerse에서 생성된 source_video_id이거나 업로드된 video_media_id일 수 있으며, 음성은 업로드된 오디오 파일이거나 TTS 음성 + 대본일 수 있습니다.

어떤 엔드포인트가 립 싱크 작업을 생성하나요?

API 키, 새 trace ID, 그리고 유효한 영상/오디오 조합을 포함해 POST /openapi/v2/video/lip_sync/generate 요청을 전송하세요. 성공적인 작업 응답은 완료된 파일이 아닌 video_id를 반환합니다.

결과가 준비되었는지 어떻게 알 수 있나요?

반환된 video_id를 사용해 GET /openapi/v2/video/result/{id}를 폴링하세요. PixVerse은 상태 코드 5를 ‘생성 중’으로, 상태 코드 1을 ‘성공’으로 문서화하고 있으며, 이때만 반환된 영상 URL을 사용해야 합니다.

오디오 파일 대신 텍스트를 사용할 수 있나요?

가능합니다. 내장 또는 사용자 정의 TTS 음성을 선택하고 lip_sync_tts_speaker_id와 lip_sync_tts_content를 함께 전송하세요. 이 경로를 동일한 예시 내에서 관련 없는 오디오 미디어 ID와 혼용하지 마세요.

API 호출 전에 영상과 음성을 선택하세요

이 PixVerse 립 싱크 API 튜토리얼은 특정 작업을 위한 것입니다: 기존 움직이는 얼굴 위에 선택된 음성 문장을 적용하고, 비동기식 결과를 수신한 후 입 움직임이 실용적으로 사용 가능한지 판단하는 것입니다. 기준 클립을 먼저 생성해야 한다면, 빠른 컷, 측면에서 정면으로 회전하는 장면, 혹은 손으로 가려진 얼굴보다 짧은 스피커 샷을 평가하기가 더 쉽습니다. 해당 기준 클립은 이미지-비디오 워크플로, PixVerse 생성, 또는 사용 권한이 있는 영상 자료로 만들 수 있습니다.

PixVerse의 공식 음성 가이드는 영상 제공 방식을 두 가지로 구분합니다. 해당 API로 생성된 클립은 이미 video_id를 가지며, 이를 source_video_id로 전달합니다. 외부 클립은 미디어 엔드포인트를 통해 업로드되며, media_id를 반환받아 video_media_id로 전달합니다. 이 두 ID는 상호 교환 불가능합니다. 나중에 재시도 시 생성된 영상 필드에 업로드된 미디어 번호를 잘못 전송하지 않도록, 각 ID 옆에 출처를 작업 로그에 기록하세요.

음성의 경우, audio_media_id를 사용한 완성된 녹음 파일을 선택하거나, lip_sync_tts_speaker_id와 lip_sync_tts_content를 사용한 텍스트-음성 변환(TTS) 방식을 선택할 수 있습니다. 네 가지 조합은 2×2 매트릭스로 구성됩니다: 생성된 영상 또는 업로드된 영상 × 녹음된 오디오 또는 TTS. 사용자 정의 음성을 생성하기 위해 사용된 음성 샘플은 립 싱크 작업을 위해 최종 업로드되는 오디오와는 다른 역할을 하며, 두 경우 모두 미디어 업로드 단계를 거치긴 하지만 그 목적은 다릅니다.

정지 이미지들은 실제 PixVerse 출력물이나 입 움직임 정확도의 증거가 아닌, 한 명의 가상 성인 발표자의 편집용 삽화입니다. 이는 소스 클립을 선택할 때 선명한 얼굴과 가리지 않은 입이 왜 중요한지를 보여줍니다.

원본 편집용 정지 이미지이며, PixVerse 출력물이 아님. 정면을 향한 안정적인 얼굴은 음성 정렬을 확인하기 위한 실용적인 첫 입력입니다.

첫 번째 테스트는 절제된 규모로 진행하세요: 한 명의 시각적으로 확인 가능한 발표자, 짧은 문장, 깨끗한 음성, 그리고 적은 카메라 움직임을 사용하세요. 음성 서사 가이드와 미디어 업로드 참조 문서는 현재 립 싱크 업로드에 대해 서로 다른 기능 제한을 명시하고 있으므로, 복사된 크기나 지속 시간을 영구적이고 보편적인 규칙으로 간주하지 마세요. 현재 엔드포인트별 문서를 확인하고, 초기 샘플은 여유 있게 짧게 유지하세요. PixVerse API 크레딧은 웹 앱 멤버십과 별도로 관리되며, 일괄 처리를 시작하기 전에 잔액을 반드시 확인하세요.

ID 혼동 없이 외부 미디어 업로드하기

이미 PixVerse에서 생성된 video_id를 보유하고 있다면 영상 업로드를 건너뛰세요. 그렇지 않다면, POST /openapi/v2/media/upload를 통해 지원되는 외부 영상을 업로드한 후, 반환된 Resp.media_id를 video_media_id로 저장하세요. 녹음된 음성 트랙도 동일한 미디어 엔드포인트를 통해 업로드하고, 반환된 Resp.media_id를 audio_media_id로 저장하세요. PixVerse은 MP4, MOV, WebM 등 일반적인 영상 형식과 MP3, WAV, M4A, AAC 등 일반적인 오디오 형식을 문서화하고 있으나, 전송 전에 현재 형식 및 기능 제한을 반드시 확인하세요.

아티팩트는 용도에 따라 명명하세요: speaker-base-v1.mp4, line-01-clean-v1.wav, 그리고 해당 미디어 ID를 포함한 작업 기록. 음성이 시작될 때 얼굴이 보이도록 하고, 불필요한 무음 구간은 잘라내며, 소스 클립이 새로운 문장에 충분한 입 움직임을 제공하는지 확인하세요.

원본 편집용 정지 이미지. 3/4 프레이밍은 리뷰어에게 더 많은 깊이 단서를 제공하지만, 타이밍 편차가 발생할 경우 이빨, 턱, 입 가장자리를 숨기기 어렵게 만듭니다.

TTS의 경우, 완성된 오디오 업로드를 생략하세요. 음성 목록을 조회하고, 내장 음성 ID를 선택하거나, 별도로 업로드된 샘플(사용 허가 필요)으로 사용자 정의 음성을 생성하세요. auto가 모든 언어에 적합하다고 가정하지 마세요. 실제로 선택된 음성 ID를 저장하세요. 여러 음성을 사용할 경우, 별도의 클립을 생성한 후 나중에 결합하세요.

네이티브 오디오 비디오 가이드에서는 음성, 배경음, 움직임이 공동 검토되어야 하는 이유를 설명합니다. 실제 인물의 얼굴 또는 음성을 사용할 경우 사전 동의를 얻어야 하며, 합성 음성 사용 시 적절히 공개해야 합니다.

하나의 유효한 생성 요청 전송하기

공식 생성 경로는 https://app-api.pixverse.ai/openapi/v2/video/lip_sync/generate입니다. PixVerse은 각 새로운 API 요청에 대해 API-KEY와 새 Ai-trace-id를 요구합니다. API 키는 브라우저 JavaScript나 문서 예시 내부가 아닌 서버 측에 안전하게 저장하세요. trace ID를 재사용하면 의도한 새 작업이 아니라 이전 결과가 반환될 수 있으므로, 각 trace ID는 입력 ID, 스크립트 버전, 응답과 함께 로그에 기록하세요.이 자리 표시자 요청은 PixVerse에서 생성한 소스 영상과 업로드된 최종 오디오를 함께 사용합니다. 예시 숫자를 귀하의 계정에서 반환된 ID로 대체하세요. 본 문서에서는 이 요청을 실행하지 않았습니다.

curl -X POST 'https://app-api.pixverse.ai/openapi/v2/video/lip_sync/generate' \
  -H "API-KEY: $PIXVERSE_API_KEY" \
  -H "Ai-trace-id: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"source_video_id":123456,"audio_media_id":234567}'

외부 영상의 경우 source_video_id를 video_media_id로 대체하세요. 텍스트-음성 변환(TTS)의 경우 audio_media_id를 lip_sync_tts_speaker_id와 lip_sync_tts_content로 각각 대체하세요. 이는 무분별하게 네 필드를 모두 채우는 것이 아니라, 서로 다른 대체 경로입니다. 응답 래퍼는 ErrCode, ErrMsg, Resp를 사용하며, 작업 생성 성공 시 Resp.video_id가 저장해야 할 식별자입니다. 이 값은 재생 가능한 파일 생성 완료를 보장하지는 않습니다.

호출 전에 하나의 영상 ID 유형과 하나의 음성 모드만 유효성을 검사하세요. 빈 TTS 스크립트는 거부하세요. 가격을 하드코딩하지 말고, 반환된 크레딧을 로그로 기록하세요. 각 라인 및 작업 응답을 안정적인 샷 ID(예: 시각적 연속성을 위한 첫 프레임-마지막 프레임 전달)와 연결하세요.

작업 상태 확인 및 결과 추적 가능성 유지

작업 생성 후, 반환된 video_id를 사용해 GET /openapi/v2/video/result/{id} 엔드포인트를 호출하세요. PixVerse는 상태 5를 ‘생성 중’으로, 상태 1을 ‘성공’으로 문서화합니다. 성공적인 HTTP 응답 또는 생성 호출에서 ErrCode: 0이 반환되면, 작업이 수락되었음을 의미할 뿐, 움직이는 결과물이 귀하의 검토를 통과했음을 의미하지는 않습니다. 상태가 1일 때는 결과에서 출력 URL을 조회하여, URL 만료 또는 액세스 규칙 변경 전에 귀하의 일반 자산 정책에 따라 복사본을 저장하세요.

상태 7은 콘텐츠 심사 실패로 문서화되어 있으며, 상태 8은 생성 실패로 문서화되어 있습니다. 이들 각각을 무한히 폴링하는 대신, 작업이 중단된 것으로 간주하세요. 실제 운영 환경의 폴러는 제한된 대기 시간, 백오프(backoff), 그리고 마지막 관찰 상태를 지속적으로 기록할 수 있는 내구성 있는 기록을 가져야 합니다. 작업자가 재시작될 경우, 동일한 유료 작업을 다시 생성하는 대신 저장된 video_id에서 재개하세요. 의도적으로 새 요청을 보낼 때는 새 트레이스 ID를 사용하되, 느린 작업이 단순히 처리 중인 경우는 재시도를 인위적으로 생성하지 마세요.

원본 편집용 정지 화면. 넓은 각도 쇼트는 발표자가 움직일 때도 얼굴 타이밍이 가독성을 유지하는지 테스트하지만, 어떤 정지 화면도 실제 입술 동기화를 입증할 수 없습니다.

샷 ID, 영상 및 음성 ID, 트레이스 ID, 생성된 video_id, 최종 URL, 검토 판정 등은 모두 읽기 쉬운 형태로 기록하세요. 이 검토 로그에는 절대 자격 증명을 저장하지 마세요. PixVerse 에이전트 워크플로 가이드에서는 전체 ‘요청서 → 샷’ 작업 흐름을 다룹니다.

입 움직임, 음성, 컷 경계 검토

최종 움직이는 파일을 정상 속도로 소리와 함께 재생한 후, 선택된 음절 주변에서 감속하여 다시 확인하세요. p, b, m처럼 눈에 띄는 양순음과 긴 개구모음이 포함된 문장을 선택하세요. 해당 자음 이전의 입 닫힘, 모음에서의 타당한 입 벌림, 그리고 주의를 산만하게 하지 않는 시작과 끝을 갖춘 발화를 확인하세요. 이는 보고된 벤치마크나 측정된 PixVerse 성공률을 주장하는 것이 아니라, 편집자 관점의 검사 방법입니다.

출력물을 소스와 비교하세요: 시선 방향, 정체성, 턱, 조명, 치아 등이 급격히 바뀌지 않아야 합니다. 클로즈업과 전체 클립 모두를 확인하세요. 이 정지 화면들은 PixVerse의 ‘비교 전/후’ 결과가 아닙니다.

원본 편집용 정지 화면. 측면 각도는 정면 썸네일이 숨길 수 있는 턱 및 입 윤곽 오류를 드러냅니다.

아래 재생 가능한 클립은 기존의 실제 움직이는 Seedance 대화 예시입니다. 이는 PixVerse API 및 도식화된 발표자와 독립적이며, 전신 움직임을 통한 입과 음성 검토를 구체적으로 하기 위해 포함된 것입니다. 이 클립은 PixVerse에서 생성한 입술 동기화 결과나 성능 비교를 보여주지 않습니다.

전신 움직임 기반 입과 음성 검토를 위한 독립적 Seedance 대화 샘플

전체 대사를 재생하고 입, 음성, 머리 움직임, 컷을 종합적으로 평가하세요. 이는 PixVerse 출력물이 아닙니다.

간단한 승인 카드를 사용하세요: 대사가 명확하고, 의도한 비트에서 시작하며, 화자 정체성을 유지하고, 정상 속도 재생 시 문제 없이 재생된다면 ‘통과’; 편집 경계나 오디오 트림만 잘못된 경우 ‘수정’; 입 모양, 얼굴, 타이밍 전반에 걸쳐 문제가 발생하면 ‘거부’. 승인은 포스터가 아닌 움직이는 파일을 기준으로 해야 합니다. 별도의 입술 동기화 워크플로 예시는 일반적인 검토 습관 비교에 도움이 될 수 있지만, 그 공급업체 제어 항목은 PixVerse API 필드와 상호 교환 가능하지 않습니다.

올바른 계층에서 문제 해결 및 전달 체계화

API가 요청을 거부할 경우, 응답과 매개변수 쌍을 점검하세요. 영상 ID 유형이 잘못 교차되었는지, 최종 오디오로 사용된 음성 샘플 ID가 잘못되었는지, 누락된 TTS 필드가 있는지, 또는 재사용된 트레이스 ID가 있는지 확인하세요. 인증, 크레딧, 미디어 유형, 제한 사항, 동시성 등을 검증하세요. 절대 API 키를 지원팀 스크린샷에 붙여넣지 마세요.작업은 성공했지만 출력 결과가 잘못된 경우, 엔드포인트를 변경해도 원본 기하학적 데이터의 품질 저하는 해결되지 않습니다. 더 안정적인 클립, 더 명확한 음성, 더 적은 가림(occlusion), 더 짧은 발화, 그리고 프레임 내에 지속적으로 유지되는 얼굴을 시도해 보세요. 타이밍 오류가 첫 단어에서만 발생한다면 오디오 리드인(audio lead-in)과 비디오 시작 프레임을 점검하세요. 컷(cut)에서만 오류가 발생한다면 편집 경계(edit boundary)와 룸 톤(room tone)을 조정하세요. 약한 라인만 다시 실행하면서, 승인된 최상의 테이크는 그대로 유지하세요.

Seedance Agent은 API 결과가 존재한 후에 적용됩니다: 승인된 베이스 클립, 음성 버전, 생성된 출력, 승인 메모, 어셈블리 결정을 함께 보관하세요. 전체 작업을 재구성하지 않고도 단일 샷을 계획하거나 교체할 수 있습니다. 참조 자료 정리 및 검토를 조율할 수는 있지만, 테스트되지 않은 PixVerse API 호출을 수행하거나 PixVerse 결과를 인증하지는 않습니다. 서로 다른 공급자로부터 생성된 출력을 결합할 때는 명확한 근거(provenance)를 유지하세요.

결론

신뢰할 수 있는 PixVerse 립 싱크 API 워크플로우는 하나의 비디오 ID 유형과 하나의 음성 모드를 선택하고, 필요한 미디어만 업로드하며, 새 trace ID를 포함해 잘 구성된 단일 요청을 전송합니다. 반환된 video_id가 완료될 때까지 기다린 후, 실제 움직이는 결과를 평가합니다. 제한 사항 및 과금 관련 권위 있는 자료로는 최신 PixVerse 문서를 참조하세요. 또한 편집 승인(editorial acceptance)은 작업 생성(task creation)과 별도로 관리해야 합니다. 여러 개의 승인된 라인이 하나의 일관된 최종 산출물로 통합되어야 할 경우, 참조 자료, 검토, 최종 어셈블리를 Seedance Agent에서 관리하세요.