HeyGen
HeyGen Avatar V
heygen-avatar-v
약 15초 분량의 참조 영상으로 재사용 가능한 실사 아바타를 구축하고, 동작과 제스처를 새로운 스크립트와 장면에 이전하면서 장면 간 일관성을 유지합니다
heygen-avatar-v 사용해 보기
입력
작품 갤러리
모든 작품 보기출력
video가격
heygen-avatar-v per second
| 단가 | $0.150 |
|---|
포지셔닝 소개
heygen-avatar-v는 HeyGen이 선보인 영상 참조 기반 디지털 아바타 모델입니다. 약 15초 분량의 실제 인물 참조 영상에서 얼굴, 동작과 제스처 특징을 추출한 뒤 새로운 스크립트, 의상, 장면, 카메라 앵글 및 언어로 전이하여 길이를 확장할 수 있는 고해상도 아바타 영상을 생성합니다. 일회성 사진 애니메이션이나 가상 캐릭터가 아니라, 동일 인물이 교육, 마케팅, 영업 및 현지화 콘텐츠에서 안정적으로 출연해야 하는 팀에 적합합니다.
핵심 하이라이트
- 영상 참조 모델링, 장면 간 일관된 정체성——단일 프레임이 아닌 전체 영상 컨텍스트로 정체성 특징을 추출하여 다양한 스타일과 장면으로 전이할 때 드리프트를 줄입니다.
- 실제 동작과 제스처가 정체성과 함께 전이——연기 동작은 참조 영상의 실제 움직임에서 비롯되어 구두 발표 영상을 생성할 때 자연스러움이 더 높습니다.
- 텍스트 또는 오디오 이중 구동——스크립트 텍스트를 직접 입력하면 내장 음성 합성으로 낭독하거나, 오디오를 업로드하여 립싱크할 수 있어 필요에 따라 워크플로를 전환할 수 있습니다.
- 한 번 아바타 구축, 다중 장면 재사용——동일 아바타를 새로운 스크립트, 의상, 카메라 앵글 및 언어에 재사용하여 반복 촬영과 후반 정렬 비용을 줄입니다.
능력 설명
영상 참조로 재사용 가능한 아바타 구축: 약 15초 분량의 실제 인물 참조 영상에서 얼굴과 동작 특징을 학습하여 반복 호출 가능한 디지털 아바타를 형성하며, 이후 생성 시 소재를 다시 수집할 필요가 없습니다.
텍스트 기반 구두 발표 생성: 최대 5000자 스크립트를 입력하고 음성을 선택하면 모델이 음성 합성과 연기 생성을 완료하여 립싱크가 포함된 영상 파일을 바로 산출합니다.
오디오 기반 립싱크: HTTPS 오디오 주소를 제공하면 아바타의 립싱크를 구동할 수 있으며 오디오는 최대 600초입니다. 이때 스크립트와 음성 파라미터는 적용되지 않으므로 이미 더빙 소재가 있는 팀에 적합합니다.
화면 파라미터 및 전달 형식 제어: 720p, 1080p, 4k 해상도와 16:9, 9:16, 4:5, 5:4, 1:1 등의 화면 비율을 지원하며, 단색 또는 이미지 배경으로 교체하거나 배경을 제거할 수 있고 mp4 또는 webm으로 출력합니다.
자막 사이드카 파일: 자막 옵션을 켜면 영상과 함께 SRT 자막 파일이 반환되어 이후 플랫폼 업로드나 다국어 자막 교체에 편리합니다.
적용 시나리오
- 기업 교육 팀: 강의 스크립트 + 통일된 강사 아바타——동일 강사가 출연하는 지식 영상을 대량 생성하고 시리즈 강좌에서 인물 이미지를 일관되게 유지하여 내부 학습 플랫폼에 바로 사용합니다.
- 마케팅 및 영업: 제품 구두 발표 스크립트 + 브랜드 인물 아바타——다양한 버전의 인물 구두 발표 소재를 빠르게 제작하고 채널에 따라 화면 비율과 배경을 전환하여 소셜 미디어 광고와 영업 후속 페이지에 사용합니다.
- 현지화 팀: 기존 더빙 오디오 + 동일 인물 아바타——다른 언어의 더빙 오디오로 동일 아바타의 립싱크를 구동하여 다국어 버전 영상을 제작하고 재촬영 비용을 줄입니다.
- 대외 커뮤니케이션: 임원 이미지 + 공식 발언 원고——임원 참조 영상으로 아바타를 구축하고 원고에 따라 대외 인사말과 브랜드 앰버서더 영상을 생성하여 여러 차례 발표에서도 이미지를 통일되게 유지합니다.
제한 및 선택 가이드
이 모델은 정체성 입력으로 실제 인물 참조 영상이 필요하며 단일 사진만으로는 시작할 수 없으므로, 일회성 사진 애니메이션이나 가상 캐릭터에는 다른 모델을 선택해야 합니다. 생성은 출력 초 단위로 과금되므로 긴 영상은 사전에 비용을 산정해야 합니다. 실제 인물 아바타를 사용할 때는 명확한 서면 승인을 받고 계정 권한을 잘 관리해야 합니다. 경량 사진 발화나 비실제 인물 이미지가 필요하다면 Avatar IV 등 더 적합한 라인으로 전환할 것을 권장합니다.
새소식
변경 이력 보기 →- 새 모델 신규 모델 추가: heygen-avatar-v, 대사와 프리셋 음성 또는 드라이빙 오디오로 출연 디지털 휴먼 영상 생성 지원; 497개의 디지털 휴먼 아바타 제공…
생성 작업 제출
https://api.hiapi.ai/v1/tasks 헤더
Authorizationstring필수계정 API 키. 모든 요청에 필수입니다. 예: Bearer YOUR_HIAPI_API_KEY. API 키 받기
Content-Typestring선택요청 본문은 항상 JSON으로 파싱됩니다. 전송 시 application/json(charset 포함 가능)만 허용되며, 다른 값은 415를 반환합니다. 예: application/json.
Idempotency-Keystring선택멱등 키. 최대 255바이트. 같은 계정에서 같은 키의 재시도는 태스크를 한 번만 생성하며, 재전송 시 최초의 taskId를 반환합니다.
네트워크 타임아웃이나 클라이언트 자동 재시도 시 같은 키로는 태스크를 한 번만 생성하고 이중 과금되지 않습니다(범위 = API 키의 계정). 업무 고유 식별자(예: "order-42")를 키로 사용할 것을 권장합니다. 같은 키 재전송 시 최초 taskId를 반환하며, 키는 첫 제출 후 24시간 뒤 만료됩니다. 자세한 시나리오 표는 통합 비동기 API 소개 페이지를 참고하세요.
본문
modelstring필수현재 고정 값: heygen-avatar-v
routestring선택현재 고정 값: default
inputobject필수
heygen-avatar-v 및 루트 default의 비즈니스 파라미터 객체. 아래 파라미터 표를 참조하세요.
fitstring선택기본값: "cover"아바타 화면 맞춤 방식을 제어하며, 문자열 유형이고 기본값은 cover입니다.
containcovervoicestring선택기본값: "Warm Pro Narrator"minLength 1텍스트 음성 변환 음색 이름을 지정하며, 문자열 유형이고 기본값은 Warm Pro Narrator입니다. audio_url이 제공되면 이 매개변수는 무시됩니다.
Warm Pro NarratorChill BrianIvyJohn DoeMonika SogamHope Archer Brittney전체 보기(94개)
PatrickDavid CastlemoreMichael CAdam Stone JuniperCassidy Jessica Anne BogartArabellaAndrewSpuds Oxley Grace ElderHelenCanyon RiversDerya - Lifelike - ExcitedMellow MarcusJack Sterling - BroadcasterBrenda - UGC - 1.mp4ReidReaganTerryJennyRadio RickDeniseTim in car - ExcitedIskanderThompsonDelicate Daisy - ExcitedKingstonGeorge UGC 1Bold BlakeJaneExpressive EvanMarianne - IAAaronModern Recipe Host - Voice 1WillowCute Chloe - FriendlyRafaelJune - LifelikeCrisp ChloeSlick SimonNassim - InformativeBaritone BenMaxwellEllie Faye - ExcitedMilaniFeisty Fiona - ExcitedProfessor DeanRose - UGC - 1.mp4ShonaHudson WilderAnn - IAAlastair KensingtonOxleyChristinaAndrew Rizz PeytonGerardo - OutdoorChloe - LifelikeStephanieAnthony - IASignal - Voice 1LucaLisa - Voice 1T.W.TuckerJack Sullivan - SeriousWinterMireia - LifelikeGeorgiaStellaMasha - LifelikeCharming Charles - FriendlySerenityAnnie - ExcitedRalphBethanyDominicMason FinnLeenaVeteran VictorTamaraNik PublicCalm ChloeSevikReillyRaulImposing IanRelaxed RayDexter - ProfessionalRelaxed RickEdwinRupert BlackwoodGinnyHopeavatarstring선택기본값: "Abigail Sofa Front"minLength 1Avatar V 프리셋 아바타 이름을 지정하며, 문자열 유형이고 기본값은 Abigail Sofa Front입니다.
Abigail Office FrontAbigail Office SideAbigail Sofa FrontAbigail Sofa SideAmelia Business Training Front 2Amelia Business Training FrontAmelia Business Training Side 2Amelia Business Training Side전체 보기(489개)
Amelia Lounge Front 2Amelia Lounge FrontAmelia Lounge Side 2Amelia Lounge SideAmelia Yoga Front 2Amelia Yoga FrontAmelia Yoga Side 2Amelia Yoga SideAnja Office FrontAnja Office Side Anja Sofa FrontAnja Sofa Side Ann Doctor SittingAnn Doctor StandingAnn TherapistAnnie Bar Sitting FrontAnnie Bar Sitting SideAnnie Bar Standing Front 2Annie Bar Standing Front 3Annie Bar Standing FrontAnnie Bar Standing Side 2Annie Bar Standing Side 3Annie Bar Standing SideAnnie Business Casual Standing Front 2Annie Business Casual Standing FrontAnnie Business Casual Standing Side 2Annie Business Casual Standing SideAnnie Casual Sitting Front 2Annie Casual Sitting FrontAnnie Casual Sitting Side 2Annie Casual Sitting SideAnnie Casual Standing Front 2Annie Casual Standing FrontAnnie Casual Standing Side 2Annie Casual Standing SideAnnie Desk Sitting Front 2Annie Desk Sitting FrontAnnie Desk Sitting Side 2Annie Desk Sitting SideAnnie Lounge Standing FrontAnnie Lounge Standing SideAnnie Office Sitting Front 2Annie Office Sitting FrontAnnie Office Sitting Side 2Annie Office Sitting SideAnnie Office Standing FrontAnnie Office Standing SideAnnie Sofa Sitting Front 3Annie Sofa Sitting FrontAnnie Sofa Sitting Side 2Annie Sofa Sitting Side 3Annie Sofa Sitting SideAnnie Sofa Sitting Front 2Annie Studio Pink Sitting FrontAnnie Studio Pink Sitting SideAnnie Studio Pink Standing FrontAnnie Studio Pink Standing SideArtur Office Front 2Artur Office FrontArtur Office Side 2Artur Office SideArtur Sofa Casual Front 2Artur Sofa Casual FrontArtur Sofa Casual Side 2Artur Sofa Causal SideAubrey Sofa SideAubrey Night Scene FrontAubrey Outdoor Sport FrontAubrey Outdoor Sport SideAubrey Sofa FrontBlanka Lounge FrontBlanka Lounge SideBlanka Outdoor Business FrontBlanka Outdoor Business SideBlanka Outdoor Reading FrontBlanka Outdoor Reading SideBlanka Picnic FrontBlanka Picnic SideBojan Business Training Front 2Bojan Business Training FrontBojan Business Training Side 2Bojan Business Training SideBojan Lounge Front 2Bojan Lounge FrontBojan Lounge Side 2Bojan Lounge SideBojan Sport Front 2Bojan Sport FrontBojan Sport Side 2Bojan Sport SideBrandon Business Sitting FrontBrandon Business Sitting SideBrandon Business Standing FrontBrandon Business Standing SideBrandon Casual Sitting FrontBrandon Casual Sitting SideBrandon Kitchen Standing FrontBrandon Kitchen Standing SideBrandon Lobby Sitting FrontBrandon Lobby Sitting SideBrandon Lobby Standing FrontBrandon Lobby Standing SideBrandon Office Sitting FrontBrandon Office Sitting SideBrandon Office Standing FrontBrandon Office Standing SideBrandon Sofa Sitting FrontBrandon Sofa Sitting SideBrent Office Front 2Brent Office FrontBrent Office Side 2Brent Office SideBrent Sofa Front 2Brent Sofa FrontBrent Sofa Side 2Brent Sofa SideBryan Fitness CoachBryan Tech ExpertCaroline Business Sitting FrontCaroline Business Sitting SideCaroline Business Standing FrontCaroline Business Standing SideCaroline Casual Sitting FrontCaroline Casual Sitting SideCaroline Kitchen Standing FrontCaroline Kitchen Standing SideCaroline Lobby Sitting FrontCaroline Lobby Sitting SideCaroline Lobby Standing FrontCaroline Lobby Standing SideCaroline Office Sitting FrontCaroline Office Sitting SideCaroline Office Standing FrontCaroline Office Standing SideCaroline Sofa Sitting FrontCaroline Sofa Sitting SideChloe Lounge FrontChloe Lounge SideChloe Outdoor SideConrad House FrontConrad House SideConrad Sofa FrontConrad Sofa SideDerya Indoor Front 2Derya Indoor FrontDerya Indoor Side 2Derya Indoor SideDerya Office Front 2Derya Office FrontDerya Office Side 2Derya Office SideDexter Doctor SittingDexter Doctor StandingDexter LawyerElenora Fitness CoachElenora Fitness Coach 2Elenora Tech ExpertEmanuel Office FrontEmanuel Office SideEmanuel Sofa FrontEmanuel Sofa SideEmilia Outdoor Business FrontEmilia Outdoor Business SideEmilia Outdoor Yoga Front 2Emilia Outdoor Yoga FrontEmilia Outdoor Yoga SideEmilia Picnic FrontEmilia Picnic SideFernando Business Indoor FrontFernando Business Indoor SideFernando OutdoorChair Front 2Fernando Outdoor Chair FrontFernando Outdoor Chair SideFernando Outdoor FrontFernando Outdoor SideFernando Outdoor Table FrontFernando Outdoor Table SideGala Bedroom FrontGala Business Sofa Front 2Gala Business Sofa Front 3Gala Business Sofa FrontGala Business Sofa Side 2Gala Business Sofa Side 3Gala Business Sofa SideGala Casual Sofa with iPad FrontGala Casual Sofa with iPad Side 2Gala Casual Sofa with iPad SideGala Office FrontGala Office SideGala Sofa Front 2Gala Sofa Front 3Gala Sofa FrontGala Sofa Side 2Gala Sofa Side 3Gala Sofa SideGeorgia Casual FrontGeorgia Casual SideGeorgia Office FrontGeorgia Office SideGerardo Sofa SideGerardo Indoor FrontGerardo Indoor SideGerardo Night Scene Front 2Gerardo Night Scene FrontGerardo Outdoor Sport FrontGerardo Outdoor Sport SideGerardo Sofa FrontGiulia Office Front 2Giulia Office FrontGiulia Office Side 2Giulia Office SideGiulia Sofa FrontGiulia Sofa SideGiulia Sofa Front 2Giulia Sofa Side 3Ida Lounge Front 2Ida Lounge FrontIda Lounge Side 2Ida Lounge SideIda Sofa Front 2Ida Sofa FrontIda Sofa Side 2Ida Sofa SideJocelyn Office Front 2Jocelyn Office FrontJocelyn Office Side 2Jocelyn Office SideJocelyn Sofa Front 2Jocelyn Sofa FrontJocelyn Sofa Side 2Jocelyn Sofa SideJoel Couch FrontJoel Couch SideJoel Gym FrontJoel Gym SideJoel Mountain FrontJoel Mountain SideJonas Gym Front 2Jonas Gym FrontJonas Gym Side 2Jonas Gym Side June Office Front 2Juan Office FrontJuan Office Side 2Juan Office SideJuan Sofa Front 2Juan Sofa FrontJuan Sofa Side 2Juan Sofa SideJudita Yoga Front 2Judita Yoga FrontJudita Yoga Side 2Judita Yoga SideJudy Doctor SittingJudy Doctor StandingJudy LawyerJudy Teacher SittingJudy HRJudy Teacher StandingJune HRJune Office FrontJune Office Side 2June Office SideJune Sofa Casual Front 2June Sofa Casual FrontJune Sofa Casual Side 2June Sofa Casual SideKavya Indoor FrontKavya Indoor SideKavya Outdoor SideKavya Outdoor Sport FrontKavya Outdoor Sport SideKavya Sofa FrontKavya Sofa SideLeos Office Front 2Leos Office FrontLeos Office Side 2Leos Office SideLeos Sofa Front 2Leos Sofa FrontLeos Sofa Side 2Leos Sofa SideLeszek Lounge FrontLeszek Lounge SideLeszek Outdoor Business FrontLeszek Outdoor Business SideLeszek Outdoor Casual FrontLeszek Outdoor Casual SideLeszek Sofa FrontLeszek Sofa SideMartina Office Front 2Martina Office FrontMartina Office Side 2Martina Office SideMartina Sofa Front 2Martina Sofa FrontMartina Sofa Side 2Martina Sofa SideMasha Office Front 2Masha Office FrontMasha Office Side 2Masha Office SideMasha Sofa Casual Front 2Masha Sofa Casual FrontMasha Sofa Casual Side 2Masha Sofa Casual SideMatteo Office Front 2Matteo Office FrontMatteo Office Side 2Matteo Office SideMatteo Sofa Front 2Matteo Sofa FrontMatteo Sofa Side 2Matteo Sofa SideMax Indoor FrontMax Indoor SideMax Outdoor Sport FrontMax Outdoor Sport SideMilena Office Front 2Milena Office FrontMilena Office Side 2Milena Office SideMilena Sofa Front 2Milena Sofa FrontMilena Sofa Side 2Milena Sofa SideMiles Outdoor FrontMiles Outdoor SideMiles Sofa Front 2Miles Sofa FrontMiles Sofa Side 2Miles Sofa SideMireia Business Indoor FrontMireia Business Indoor SideMireia Outdoor Chair FrontMireia Outdoor FrontMireia Outdoor SideMireia Outdoor Table FrontMireia Outdoor Table SideMiyu Office Front 2Miyu Office FrontMiyu Office Side 2Miyu Office SideMiyu Sofa Business FrontMiyu Sofa Business SideMiyu Sofa Casual Front 2Miyu Sofa Casual FrontMiyu Sofa Casual Side 2 Miyu Sofa Casual SideNoah Lobby Front 2Noah Lobby FrontNoah Lobby Side 2Noah Lobby SideNoah Office Front 2Noah Office FrontNoah Office Side 2Noah Office SideNoah Sofa Front 2Noah Sofa Front Noah Sofa Side 2Noah Sofa SideOxana Gym Front 2Oxana Gym FrontOxana Gym Side 2Oxana Gym SideOxana Office Front 2Oxana Office FrontOxana Office Side 2Oxana Office SideOxana Sofa Front 2Oxana Sofa FrontOxana Sofa Side 2Oxana Sofa SideOxana Yoga Front 2Oxana Yoga FrontOxana Yoga Side 2Oxana Yoga SidePatrizio Business Training FrontPatrizio Business Training SidePatrizio Office FrontPatrizio Office Side 2Patrizio Office SidePatrizio Sofa FrontPatrizio Sofa SidePiper Business Sofa FrontPiper Business Sofa SidePiper Education FrontPiper Education SideRasmus Lounge Front 2Rasmus Lounge FrontRasmus Lounge Side 2Rasmus Lounge SideRasmus Sofa Front 2Rasmus Sofa FrontRasmus Sofa Side 2Rasmus Sofa SideRaul Business Sofa Front 2Raul Business Sofa FrontRaul Business Sofa Side 2Raul Business Sofa SideRaul Casual Sofa Front 2Raul Casual Sofa FrontRaul Casual Sofa Side 2Raul Casual Sofa SideRaul Casual Sofa no iPad FrontRaul Casual Sofa no iPad SideRaul Casual Sofa with iPad FrontRaul Casual Sofa with iPad SideRaul Office Front 2Raul Office FrontRaul Office SideRaul Sofa Front 2Raul Sofa FrontRaul Sofa Side 2Raul Sofa SideRen Office Front 2Ren Office FrontRen Office Side 2Ren Office SideRen Sofa Business FrontRen Sofa Business SideRen Sofa Casual Front 2Ren Sofa Casual FrontRen Sofa Casual Side 2 Ren Sofa Casual SideRiley Casual FrontRiley Casual SideRiley Office FrontRiley Office SideRoman Outdoor Sport FrontRoman Outdoor Sport SideSabine Office Front 2Sabine Office FrontSabine Office SideSabine Sofa SideSanta Fireplace FrontSanta Fireplace SideScarlett Couch Front 2Scarlett Couch FrontScarlett Couch Side 2Scarlett Couch SideScarlett Fireplace FrontScarlett Fireplace SideScarlett Hall FrontScarlett Hall SideScarlett Yoga FrontScarlett Yoga SideShawn TherapistSilas Customer SupportSilas HRSilas Lounge FrontSilas Lounge SideSilas Sofa Side 2Silas Sofa SideTeodor Office Front 2Teodor Office FrontTeodor Office Side 2Teodor Office SideTeodor Sofa Front 2Teodor Sofa FrontTeodor Sofa Side 2Teodor Sofa SideTimothy Casual FrontTimothy Casual SideTimothy Office FrontTimothy Office SideVeit Office FrontVeit Office SideVeit Sofa FrontVeit Sofa SideVernon Office Front 2Vernon Office FrontVernon Office Side 2Vernon Office SideVerena Office FrontVerena Office SideVerena Sofa FrontVerena Sofa SideVernon Lounge Front 2Vernon Lounge Side 2Vernon Lounge SideVince Business Sofa FrontVince Business Training FrontVince Business Training Side 2Vince Business Training SideVince Sofa Casual Front 2Vince Sofa Casual FrontVince Sofa Casual Side 2Vince Sofa Casual Sidepromptstring선택minLength 1maxLength 5000아바타가 낭독할 텍스트 내용이며, 문자열 유형입니다. audio_url이 제공되지 않으면 필수입니다.
captionboolean선택기본값: false추가로 SRT 자막 파일을 반환할지 여부이며, 불리언 유형이고 기본값은 false입니다.
audio_urlstring선택pattern ^https://립싱크에 사용할 HTTPS 오디오 주소이며, 문자열 유형이고 오디오 최대 길이는 600초입니다. 이 매개변수를 제공하면 prompt와 voice는 모두 무시됩니다.
backgroundobject선택
배경 구성 그룹으로, 출력 영상의 배경 설정을 제어하며 유형과 값 두 개의 하위 필드를 포함합니다.
typestring필수배경 유형을 지정하며, 문자열 유형이고 구체적인 값은 background 그룹 구성에 따라 결정됩니다.
colorimagevaluestring필수minLength 1배경 값을 지정하며, 문자열 유형이고 background.type과 함께 사용됩니다.
resolutionstring선택기본값: "720p"출력 영상 해상도를 제어하며, 문자열 유형이고 기본값은 720p입니다.
720p1080p4kaspect_ratiostring선택기본값: "16:9"출력 영상 화면 가로세로 비율을 제어하며, 문자열 유형이고 기본값은 16:9입니다.
16:99:164:55:41:1autooutput_formatstring선택기본값: "mp4"출력 파일 형식을 제어하며, 문자열 유형이고 기본값은 mp4입니다.
mp4webmremove_backgroundboolean선택기본값: false화면 배경을 제거할지 여부이며, 불리언 유형이고 기본값은 false입니다.
callbackobject선택
종료 상태 알림 설정. 생략하면 콜백이 전송되지 않으며 호출 측에서 폴링합니다.
생성 시 callback.url을 지정하면 태스크 종료 시 HiAPI가 서비스로 POST하여 폴링이 필요 없습니다. 콜백 본문은 태스크 상세와 동일한 구조입니다. 서명 검증·재시도·멱등에 대한 자세한 내용은 통합 비동기 API 소개 페이지의 콜백 설명을 참고하세요.
urlstring필수callback 사용 시 필수. 태스크 종료 후 이 URL로 POST됩니다. 유효한 http(s) URL이어야 합니다.
whenstring선택기본값: "final"현재는 final만 지원(success / fail 모두 알림).
finalstoragestring선택기본값: "temp"산출물 저장 등급: temp(기본·약 7일) 또는 persistent(장기 보관·용량 과금). 잔액 부족이나 저장 한도 초과 시 자동으로 temp로 강등됩니다. 실제 적용된 등급은 태스크 상세 응답에서 확인할 수 있습니다.
temppersistent요청 예시
# 비동기 태스크 제출. 성공 시 즉시 taskId 반환(생성 완료 대기 없음)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "heygen-avatar-v",
"input": {
"fit": "cover",
"voice": "Warm Pro Narrator",
"avatar": "Abigail Sofa Front",
"caption": false,
"resolution": "720p",
"aspect_ratio": "16:9",
"output_format": "mp4",
"remove_background": false
}
}' const res = await fetch("https://api.hiapi.ai/v1/tasks", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "heygen-avatar-v",
input: {
"fit": "cover",
"voice": "Warm Pro Narrator",
"avatar": "Abigail Sofa Front",
"caption": false,
"resolution": "720p",
"aspect_ratio": "16:9",
"output_format": "mp4",
"remove_background": false
}
}),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } } import os, requests
res = requests.post(
"https://api.hiapi.ai/v1/tasks",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "heygen-avatar-v",
"input": {
"fit": "cover",
"voice": "Warm Pro Narrator",
"avatar": "Abigail Sofa Front",
"caption": False,
"resolution": "720p",
"aspect_ratio": "16:9",
"output_format": "mp4",
"remove_background": False
}
},
)
print(res.json()) # { code, message, data: { taskId } } 200 OK
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
}
} 400 Bad Request
{
"code": 400,
"message": "invalid request",
"data": null,
"error_code": "INVALID_REQUEST"
} 작업 상세 조회
https://api.hiapi.ai/v1/tasks/:id 응답 필드
taskIdstring필수태스크 ID. 접두사는 항상 tk-hiapi-.
modelstring필수확인된 전체 모델명. route 파라미터로 제출한 태스크는 base@route(예: gpt-image-2/text-to-image@ext)를 반환하며, 그 외에는 제출 시의 모델명과 동일합니다.
routestring선택route 파라미터를 명시해 제출한 태스크에만 나타나며, 제출한 값을 그대로 반환합니다.
statusstring필수태스크 상태.
queued 대기 중, 아직 시작되지 않음.
handling 처리 중.
archiving 처리 완료, 산출물 준비 중.
success 종료: 완료. 산출물 사용 가능(output 반환).
fail 종료: 실패(error 반환).
제출 후 status로 판단합니다: success와 fail이 종료 상태이며 나머지는 비종료입니다. 1~3초 간격으로 종료까지 폴링하세요. 성공 시 output[].url에서 산출물을 다운로드하고 expireAt 전에 옮기세요. 장기 보관이 필요하면 생성 시 storage: "persistent"를 사용하세요.
creatednumber필수태스크 생성 시각(Unix 초).
completednumber필수종료 상태가 된 Unix 초. 비종료 상태에서는 0.
outputarray선택
status == success일 때만 나타납니다. 산출물 목록 — 항상 배열이며, 하나의 태스크에서 여러 type을 동시에 반환할 수 있습니다(예: video + first_frame).
Array [ object ]
배열 항목
urlstring필수산출물 URL. 바로 다운로드할 수 있습니다.
typestring필수현재 가능한 값: video, image, audio, first_frame, last_frame, thumbnail. 이후 확장될 수 있습니다.
expireAtnumber필수산출물 접근 가능 기한(Unix 초). 만료 전에 다운로드하거나 이전하세요.
errorobject선택
status == fail일 때만 나타납니다.
codestring필수비즈니스 오류 코드.
messagestring필수오류 설명.
응답 예시
성공
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
"model": "happyhorse-1-0",
"status": "success",
"created": 1777282033,
"completed": 1777282099,
"output": [
{
"url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
"type": "video",
"expireAt": 1777886899
}
]
}
} 처리 중(비종료)
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "archiving",
"created": 1777282033,
"completed": 0
}
} 실패
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "fail",
"created": 1777282033,
"completed": 1777282099,
"error": {
"code": "TASK_FAILED",
"message": "task failed"
}
}
} 아티클
모든 아티클 보기 →-
튜토리얼
HiAPI API로 kling-4.0/text-to-video를 사용하는 방법: curl, Python 및 실행 가능한 요청 예제
개발자를 위한 실전 가이드: 영화적 프롬프트, 동기화 오디오, 비동기 폴링 및 출력 다운로드
-
튜토리얼
recraft-v4.1-flash 텍스트-이미지 생성 실전: 5가지 고부가가치 비즈니스 시나리오와 연동 핵심 포인트
장당 $0.01의 비용에서 출발해, 이미지 생성이 실제 비즈니스에서 어떻게 안착할지 계획하기
-
비교 평가
Recraft v4.1 Flash 텍스트 투 이미지 횡적 비교: 개발자 선정 및 마이그레이션 가이드
이미지당 $0.01의 비용과 순수 텍스트 투 이미지 기능으로 귀하의 이미지 생성 파이프라인에 적합한지 판단하세요
-
튜토리얼
HiAPI API로 hailuo-2.3-fast/image-to-video 호출하는 방법: curl과 Python 실전
빠르고 저렴한 이미지-투-비디오 등급의 첫 실행 요청 — 모델 ID부터 MP4 다운로드까지
-
튜토리얼
HiAPI API로 hailuo-2.3/text-to-video를 호출하는 방법: curl, Python 및 실행 가능한 요청 예시
-
튜토리얼
HiAPI에서 Kandinsky 6.0 Pro 텍스트-투-비디오 사용하기: curl 및 Python 튜토리얼
요청 우선 실전 데모: 프롬프트에서 비디오 클립까지의 호출 구성, 요청 제출, 완료 상태 폴링 및 결과 다운로드
-
튜토리얼
HiAPI에서 kling-4.0/image-to-video를 호출하는 방법: curl, Python 및 폴링
-
튜토리얼
HiAPI에서 kandinsky-6.0-pro/image-to-video 튜토리얼: curl + Python
HiAPI에서 사용 가능한 이미지-투-비디오 요청 보내기: 첫 프레임 업로드부터 비동기 폴링, 최종 다운로드까지
-
비교 평가
hailuo-2.3-fast/image-to-video横向对比:이미지 투 비디오 모델 선택 방법과 마이그레이션 핵심 포인트
관련 모델
모든 모델 보기 →동일 유형
-
Gemini Omni Google -- -
Ray 3.2 Luma $0.214 /동영상 -
Veo 3.1 Fast Google $0.170 /초 -
Kling 4.0 Kuaishou $0.330 /초 -
MiniMax H3 MiniMax $0.072 /초 -
Vidu Q4 Preview Vidu $0.051 /초 -
HappyHorse 1.1 Alibaba $0.160 /초 -
Hailuo 2.3 MiniMax $0.270 /동영상 -
HappyHorse 1.0 Alibaba $0.168 /초 -
Kling 3.0 Kuaishou $0.100 /초 -
Seedance 2.5 ByteDance $0.121 /초 -
Gemini Omni 1.1 Flash Google $0.450 /동영상