HeyGen
HeyGen Avatar V
heygen-avatar-v
Construir um clone digital de uma pessoa real reutilizável a partir de um vídeo de referência de cerca de 15 segundos, transferindo os movimentos e gestos para novos roteiros e cenários e mantendo a consistência entre cenários
Experimentar heygen-avatar-v
Entrada
Criações
Ver todas as criaçõesSaída
videoPreços
heygen-avatar-v per second
| Preço unitário | $0.150 |
|---|
Visão geral do posicionamento
heygen-avatar-v é um modelo de avatar digital da HeyGen impulsionado por vídeo de referência: ele extrai características faciais, de movimento e de gestos a partir de um vídeo de referência de uma pessoa real com cerca de 15 segundos e as transfere para novos roteiros, roupas, cenários, enquadramentos de câmera e idiomas, gerando vídeos de avatar de alta resolução com duração extensível. É adequado para equipes que precisam que a mesma pessoa apareça de forma consistente em treinamentos, marketing, vendas e conteúdo de localização, e não para animações pontuais de fotos ou personagens fictícios.
Destaques principais
- Modelagem por vídeo de referência, identidade consistente entre cenários — extrai características de identidade a partir do contexto completo do vídeo, e não de um único quadro, reduzindo o desvio ao transferir para diferentes visuais e cenários.
- Movimentos e gestos reais migram junto com a identidade — as ações de atuação vêm do movimento real do vídeo de referência, proporcionando maior naturalidade na geração de vídeos de locução.
- Acionamento duplo por texto ou áudio — é possível inserir diretamente o texto do roteiro para que a síntese de voz integrada o leia, ou enviar um áudio para sincronização labial, alternando o fluxo de trabalho conforme a necessidade.
- Crie o avatar uma vez e reutilize em vários cenários — o mesmo avatar pode ser reutilizado em novos roteiros, roupas, enquadramentos e idiomas, reduzindo custos de regravação e de alinhamento em pós-produção.
Descrição das capacidades
Construção de avatar reutilizável por vídeo de referência: aprende características faciais e de movimento a partir de um vídeo de referência de uma pessoa real com cerca de 15 segundos, formando um avatar digital que pode ser chamado repetidamente, sem necessidade de recoletar materiais nas gerações seguintes.
Geração de locução por texto: insira um roteiro de até 5000 caracteres e escolha a voz; o modelo realiza a síntese de voz e a geração da atuação, produzindo diretamente um arquivo de vídeo com sincronização labial.
Sincronização labial por áudio: basta fornecer um endereço de áudio HTTPS para acionar a sincronização labial do avatar, com áudio de até 600 segundos; nesse caso, os parâmetros de roteiro e voz não têm efeito, sendo ideal para equipes que já possuem material de dublagem.
Controle de parâmetros de imagem e formato de entrega: suporta resoluções 720p, 1080p e 4k, proporções 16:9, 9:16, 4:5, 5:4, 1:1 e outras, permite trocar por fundo de cor sólida ou imagem, remover o fundo e exportar em mp4 ou webm.
Arquivo de legenda sidecar: ao ativar a opção de legendas, um arquivo SRT é retornado junto com o vídeo, facilitando a publicação em plataformas ou a substituição de legendas em vários idiomas.
Cenários de aplicação
- Equipes de treinamento corporativo: roteiro de curso + avatar de instrutor unificado — geração em lote de vídeos de conhecimento com o mesmo instrutor em cena, mantendo a imagem da pessoa consistente ao longo da série de cursos, para uso direto em plataformas de aprendizagem interna.
- Marketing e vendas: roteiro de locução de produto + avatar de personagem da marca — produção rápida de materiais de locução em várias versões, alternando proporção e fundo conforme o canal, para veiculação em redes sociais e páginas de acompanhamento de vendas.
- Equipes de localização: áudio de dublagem existente + mesmo avatar — usar áudios de dublagem em diferentes idiomas para acionar a sincronização labial do mesmo avatar, produzindo versões em vários idiomas e reduzindo custos de regravação.
- Comunicação externa: imagem de executivo + discurso formal — criar um avatar a partir de um vídeo de referência do executivo e gerar, a partir do texto, vídeos de pronunciamento externo e de endosso de marca, mantendo a imagem unificada em múltiplas publicações.
Limitações e recomendações de seleção
Este modelo exige um vídeo de referência de uma pessoa real como entrada de identidade e não pode ser iniciado apenas com uma única foto; animações pontuais de fotos ou personagens fictícios devem usar outro modelo. A geração é cobrada por segundo de saída, e vídeos longos exigem cálculo prévio de custos. O uso de avatares de pessoas reais deve obter autorização por escrito explícita e gerenciar bem as permissões da conta. Se a necessidade for de fala leve a partir de foto ou de imagens não humanas, recomenda-se usar linhas mais adequadas, como o Avatar IV.
Novidades
Ver o changelog →- Novo modelo Novo modelo: heygen-avatar-v, com suporte para gerar vídeos de avatares digitais em cena a partir de falas com vozes predefinidas ou áudio de condução; oferece 497 avatares digitais…
Criar uma tarefa de geração
https://api.hiapi.ai/v1/tasks Cabeçalhos
AuthorizationstringObrigatórioChave de API da conta. Obrigatória em toda requisição. Exemplo: Bearer YOUR_HIAPI_API_KEY. Obter chave de API
Content-TypestringOpcionalO corpo da requisição é sempre interpretado como JSON; se enviado, apenas application/json (charset opcional) é aceito — qualquer outro valor retorna 415. Exemplo: application/json.
Idempotency-KeystringOpcionalChave de idempotência, até 255 bytes. Retries com a mesma chave da mesma conta criam a tarefa apenas uma vez; replays retornam o taskId original.
Em timeouts de rede ou retries automáticos do cliente, a mesma chave cria a tarefa apenas uma vez, sem cobrança duplicada (escopo = a conta da chave de API). Use um identificador de negócio exclusivo (ex.: "order-42"); replays retornam o taskId original e as chaves expiram 24 h após a primeira requisição. A matriz completa de cenários está na introdução da API assíncrona unificada.
Corpo
modelstringObrigatórioValor fixo atual: heygen-avatar-v
routestringOpcionalValor fixo atual: default
inputobjectObrigatório
Objeto de parâmetros de negócio para heygen-avatar-v e a rota default — veja a tabela de parâmetros abaixo.
fitstringOpcionalPadrão: "cover"Controla o modo de ajuste do enquadramento do avatar, tipo string, padrão cover.
containcovervoicestringOpcionalPadrão: "Warm Pro Narrator"minLength 1Especifica o nome da voz de texto para fala, tipo string, padrão Warm Pro Narrator; este parâmetro é ignorado quando audio_url é fornecido.
Warm Pro NarratorChill BrianIvyJohn DoeMonika SogamHope Archer BrittneyMostrar tudo (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 BlackwoodGinnyHopeavatarstringOpcionalPadrão: "Abigail Sofa Front"minLength 1Especifica o nome do avatar predefinido do Avatar V, tipo string, padrão 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 SideMostrar tudo (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 SidepromptstringOpcionalminLength 1maxLength 5000O conteúdo de texto que o avatar irá narrar, tipo string; obrigatório quando audio_url não é fornecido.
captionbooleanOpcionalPadrão: falseSe deve retornar adicionalmente um arquivo de legenda SRT, tipo booleano, padrão false.
audio_urlstringOpcionalpattern ^https://Endereço HTTPS de áudio para sincronização labial, tipo string, áudio com duração máxima de 600 segundos; quando este parâmetro é fornecido, prompt e voice são ignorados.
backgroundobjectOpcional
Grupo de configuração de fundo, controla as definições de fundo do vídeo de saída, contendo os dois subcampos tipo e valor.
typestringObrigatórioEspecifica o tipo de fundo, tipo string, os valores concretos são determinados pela configuração do grupo background.
colorimagevaluestringObrigatóriominLength 1Especifica o valor do fundo, tipo string, usado em conjunto com background.type.
resolutionstringOpcionalPadrão: "720p"Controla a resolução do vídeo de saída, tipo string, padrão 720p.
720p1080p4kaspect_ratiostringOpcionalPadrão: "16:9"Controla a proporção de aspecto do vídeo de saída, tipo string, padrão 16:9.
16:99:164:55:41:1autooutput_formatstringOpcionalPadrão: "mp4"Controla o formato do arquivo de saída, tipo string, padrão mp4.
mp4webmremove_backgroundbooleanOpcionalPadrão: falseSe deve remover o fundo da imagem, tipo booleano, padrão false.
callbackobjectOpcional
Configuração de notificação de estado terminal. Se omitida, sem callback: consulte a tarefa por conta própria.
Informe callback.url na criação e o HiAPI fará POST no seu serviço no estado terminal, sem polling. O corpo do callback replica a estrutura do detalhe da tarefa; assinatura, retries e idempotência estão descritos na introdução da API assíncrona unificada.
urlstringObrigatórioObrigatória se callback estiver presente. No estado terminal é enviado um POST para esta URL; deve ser uma URL http(s) válida.
whenstringOpcionalPadrão: "final"Atualmente só há suporte a final — notifica tanto em success quanto em fail.
finalstoragestringOpcionalPadrão: "temp"Nível de armazenamento de artefatos: temp (padrão, ~7 dias) ou persistent (longo prazo, cobrado por tamanho). Saldo insuficiente ou limite excedido ⇒ rebaixamento silencioso para temp; o nível efetivo aparece na resposta de detalhes.
temppersistentExemplos de requisição
# Envia uma tarefa assíncrona; retorna um taskId imediatamente (sem esperar a geração)
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"
} Obter detalhes da tarefa
https://api.hiapi.ai/v1/tasks/:id Campos da resposta
taskIdstringObrigatórioID da tarefa, sempre com prefixo tk-hiapi-.
modelstringObrigatórioNome completo resolvido do modelo. Tarefas enviadas com o parâmetro route retornam base@route (ex.: gpt-image-2/text-to-image@ext); caso contrário, igual ao nome enviado.
routestringOpcionalPresente apenas se o parâmetro route explícito foi usado; ecoa o valor enviado.
statusstringObrigatórioEstado da tarefa.
queued Na fila, ainda não iniciada.
handling Em processamento.
archiving Processamento concluído, preparando artefatos.
success Terminal: concluído, artefatos disponíveis (retorna output).
fail Terminal: falha (retorna error).
Após o envio, acompanhe status: success e fail são terminais, os demais não. Faça polling a cada 1–3 s até o estado terminal. Em caso de sucesso, baixe os artefatos em output[].url e transfira antes de expireAt; para retenção longa, use storage: "persistent" na criação.
creatednumberObrigatórioMomento de criação da tarefa (segundos Unix).
completednumberObrigatórioSegundos Unix do estado terminal; 0 enquanto não terminal.
outputarrayOpcional
Presente apenas com status == success. Lista de artefatos — sempre um array; uma tarefa pode retornar vários types ao mesmo tempo (ex.: video + first_frame).
Array [ object ]
Itens do array
urlstringObrigatórioURL do artefato, baixável diretamente.
typestringObrigatórioValores possíveis no momento: video, image, audio, first_frame, last_frame, thumbnail; poderão ser ampliados.
expireAtnumberObrigatórioSegundos Unix de disponibilidade do artefato; baixe ou transfira antes da expiração.
errorobjectOpcional
Presente apenas com status == fail.
codestringObrigatórioCódigo de erro de negócio.
messagestringObrigatórioDescrição do erro.
Exemplos de resposta
Sucesso
{
"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
}
]
}
} Em processamento (não final)
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "archiving",
"created": 1777282033,
"completed": 0
}
} Falhou
{
"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"
}
}
} Artigos
Ver todos os artigos →-
Tutorial
recraft-v4.1-flash geração de imagens por texto na prática: 5 cenários de negócio de alto valor e pontos de integração
Partindo de um custo de US$ 0,01 por imagem, planeje como aplicar a geração de imagens em negócios reais
-
Tutorial
Como chamar hailuo-2.3-fast/image-to-video pela API HiAPI: curl e Python na prática
A primeira requisição executável do nível rápido e econômico de geração de vídeo a partir de imagem — do ID do modelo ao download do MP4
-
Avaliação comparativa
Comparação lado a lado do Recraft v4.1 Flash em text-to-image: guia de seleção e migração para desenvolvedores
Com um custo de $0.01 por imagem e capacidade de text-to-image pura, avalie se ele é adequado para seu pipeline de geração de imagens
-
Tutorial
Como chamar kling-4.0/image-to-video na HiAPI: curl, Python e polling
-
Tutorial
Como chamar hailuo-2.3/text-to-video pela API HiAPI: curl, Python e exemplos de requisição executáveis
-
Tutorial
Tutorial de kandinsky-6.0-pro/image-to-video na HiAPI: curl + Python
Faça uma requisição de imagem para vídeo funcional na HiAPI: do upload do primeiro quadro ao polling assíncrono e ao download final
-
Avaliação comparativa
hailuo-2.3-fast/image-to-video comparação lado a lado: como escolher modelos de imagem para vídeo e pontos de migração
-
Tutorial
Usar Kandinsky 6.0 Pro text-to-video na HiAPI: tutorial de curl e Python
Demonstração prática com foco na requisição: montar a chamada de prompt para clipe de vídeo, enviar a requisição, consultar o status de conclusão e baixar o resultado
-
Tutorial
Como usar kling-4.0/text-to-video através da API HiAPI: curl, Python e um exemplo de requisição executável
Guia prático para desenvolvedores: prompts cinematográficos, áudio sincronizado, polling assíncrono e download da saída
Modelos relacionados
Ver todos os modelos →Mesmo tipo
-
Vidu Q3 Vidu $0.149 /segundo -
PixVerse V6 PixVerse $0.036 /segundo -
Veo 3.1 Lite Google $0.060 /segundo -
Wan 3.0 Video Alibaba $0.040 /segundo -
Grok Imagine 1.5 Lite xAI $0.029 /segundo -
Ray 3.2 Luma $0.214 /vídeo -
Kling 3.0 Kuaishou $0.100 /segundo -
Veo 3.1 Google $0.290 /segundo -
Gemini Omni 1.1 Flash Google $0.450 /vídeo -
Gemini Omni Google -- -
MiniMax H3 MiniMax $0.072 /segundo -
Wan 2.6 Flash Alibaba $0.043 /segundo