본문으로 건너뛰기

개발자 · 2026년 10월 업데이트

OmniHuman 2 API: 입력, 제한, 작동 방식

제품에 OmniHuman 2 API 도입을 검토하고 있다면 요청 구조, 입력 제한, 결과가 반환되는 방식이 핵심이에요. 이 페이지에서는 호스팅 제공업체가 공개한 사양을 바탕으로 이 내용을 한곳에 정리하고, 요청을 보내기 전에 코드에서 처리해야 할 부분을 설명해요.

사진+목소리=영상

목소리
사진이 없나요? 이걸로 해 보세요:
  • 무료 미리보기
  • Google 로그인
  • 비공개 업로드
UGC 광고
노래
다인원
영상당
5분
출력
720p
장면 지원
다인원
개 언어
6

연동할 필요 없이 영상만 만들고 싶다면 개발 과정은 건너뛰어도 돼요. 저희 스튜디오는 같은 모델에 업로드 검증, 브라우저 녹음, 저장, 다운로드 기능을 더해 제공해요.

OmniHuman 2 API 요청에 들어가는 것

요청에는 필수 필드 두 개와 선택 필드 하나가 있어요. 이미지 URL은 움직일 인물(한 명 또는 여러 명)을, 오디오 URL은 퍼포먼스를 이끄는 말이나 노래를 가리키고, 선택 사항인 프롬프트는 움직임, 분위기, 장면 디테일, 카메라 움직임을 묘사해요. 결과는 보통 대기열을 통해 비동기로 전달돼요. 요청을 제출하면 요청 ID를 받고, 상태를 폴링하거나 영상이 준비되면 웹훅을 받는 방식이에요.

  • image_url — 필수. 움직일 정지 이미지.
  • audio_url — 필수. 길이와 립싱크를 결정하는 MP3 또는 WAV.
  • prompt — 선택. 영어, 중국어, 일본어, 한국어, 스페인어(멕시코), 인도네시아어 지원.

먼저 검증해야 할 입력 제한

거부된 요청은 시간을 낭비하고 때로는 비용도 들기 때문에, 모델을 호출하기 전에 직접 검증하세요. 이미지는 JPEG, PNG, WEBP, BMP, TIFF, GIF, HEIC 같은 일반적인 형식이어야 하고, 30MB 이하, 각 변 300~6000픽셀, 가로세로 비율 0.4~2.5여야 해요. 오디오는 WAV 또는 MP3, 최대 15MB, 길이 4~300초여야 해요.

브라우저 녹음은 보통 WebM이나 Opus 형식인데, 모델은 이를 받지 않아요. 업로드 전에 WAV나 MP3로 변환하세요. 저희 스튜디오는 녹음을 22.05kHz 모노 WAV로 다시 인코딩해서 5분짜리 클립도 용량 제한 안에 들어가게 해요.

출력과 과금

작업이 끝나면 영상 파일 URL과 과금 기준이 되는 길이가 반환되는데, 이 길이는 입력 오디오 길이와 같아요. 출력은 네이티브 720p MP4예요. 제공업체 URL은 만료될 수 있으니, 운영 시스템에서는 제공업체 링크를 직접 쓰지 말고 작업이 끝나는 즉시 파일을 자체 저장소로 복사하세요.

비용이 렌더링한 초 수에 비례하므로 오디오 길이는 서버에서 측정하고(브라우저가 보낸 길이는 절대 신뢰하지 마세요), 제출 전에 비용을 미리 예약해 동시 작업이 잔액을 초과해 쓰지 않게 하세요.

운영 환경에 맞는 처리 흐름

이 사이트의 모든 렌더링에 저희가 쓰는 패턴이에요.

  1. 1비공개 저장소에 업로드유효 시간이 짧은 서명된 업로드 URL을 발급하고, 사용자 사진에 대한 장기 공개 링크는 절대 노출하지 마세요.
  2. 2서버에서 검증과금 전에 오디오 길이를 다시 측정하고 두 파일이 모두 존재하는지 확인하세요.
  3. 3예약 후 제출크레딧을 원자적으로 예약하고 작업을 제출한 뒤, 제출에 실패하면 자동으로 환불하세요.
  4. 4멱등하게 마무리웹훅이나 폴링 시점에 결과를 가져와 MP4를 저장하고, 작업 완료 처리는 정확히 한 번만 하세요.

노코드 스튜디오가 더 나은 경우

위의 파이프라인을 구축하려면 저장소, 검증, 대기열, 웹훅, 재시도, 결제까지 며칠이 걸려요. 제품 기능이 아니라 콘텐츠가 목적이라면, 저희 스튜디오에서 이 모든 게 이미 갖춰진 상태로 같은 OmniHuman 2.0 결과물을 얻을 수 있어요. 저희는 공개 API를 직접 제공하지 않아요. 이 사이트는 완성된 영상이 필요한 크리에이터와 마케터를 위해 만들어졌어요.

실패와 재시도 처리

모든 작업은 실패할 수 있다고 가정하세요. 제공업체가 입력을 거부하거나, 부하로 시간이 초과되거나, 다운로드할 수 없는 결과를 반환할 수 있어요. 작업마다 상태 컬럼(queued, running, done, failed)을 두고, 중복 웹훅이 두 번 처리되지 않도록 마무리 단계를 멱등하게 만들고, 실패 시 예약한 잔액은 환불하세요.

웹훅을 쓰더라도 대비책으로 폴링을 함께 하세요. 로컬 개발 환경에서는 웹훅을 받을 수 없고, 운영 환경의 웹훅도 가끔 지연돼요.

  • 사용자에게 응답하기 전에 제공업체의 요청 ID를 저장하세요.
  • 입력 URL은 예상 대기 시간보다 긴 유효 기간으로 다시 서명하세요.
  • 제공업체 오류는 원문 그대로 기록하세요. 대개 어떤 제한을 초과했는지 정확히 알려 줘요.

자주 묻는 질문

omnihuman2.ai는 공개 API를 제공하나요?

아니요. 저희는 웹 스튜디오를 통해 크리에이터에게 모델을 제공해요. 개발자는 공식 모델 제공업체를 통해 OmniHuman 2를 이용할 수 있어요.

OmniHuman 2 API의 최대 오디오 길이는 얼마인가요?

300초예요. 최소 길이는 4초이고, 파일은 15MB 이하의 MP3 또는 WAV여야 해요.

API는 어떤 해상도로 반환하나요?

2.0 버전은 네이티브 720p로 렌더링하고 MP4 파일을 반환해요.

API는 동기 방식인가요?

일반적으로 아니에요. 작업에 몇 분이 걸리기 때문에 제공업체는 폴링이나 웹훅을 쓰는 대기열 방식을 사용해요.

WebM 녹음 파일을 보낼 수 있나요?

직접은 안 돼요. 먼저 WAV나 MP3로 변환하세요. 대부분의 브라우저 녹음은 다시 인코딩해야 해요.

사용량은 어떻게 과금되나요?

출력 영상의 초 수로 과금되며, 이는 입력 오디오 길이와 같아요.

출력 영상을 자체 저장소로 복사해야 하나요?

네. 제공업체의 결과 URL은 만료될 수 있으니 작업이 끝나는 즉시 MP4를 자체 저장소로 내려받으세요.

작업은 보통 얼마나 걸리나요?

클립 길이와 대기열 부하에 따라 달라요. 자체 테스트에서는 약 5초짜리 클립이 처음부터 끝까지 2분 정도 걸렸으니, UI는 초가 아니라 분 단위를 기준으로 설계하세요.

더 알아보기

내 사진을 말하게 하세요.

미리보기 무료.