HeyGen
HeyGen Avatar V
heygen-avatar-v
Crear un clon digital de una persona real reutilizable a partir de un vídeo de referencia de unos 15 segundos, transferir los gestos y movimientos a un nuevo guion y escenario, y mantener la coherencia entre escenarios
Probar heygen-avatar-v
Entrada
Creaciones
Ver todas las creacionesSalida
videoPrecios
heygen-avatar-v per second
| Precio unitario | $0.150 |
|---|
Descripción general
heygen-avatar-v es un modelo de avatar digital impulsado por video de referencia lanzado por HeyGen: extrae rasgos faciales, movimientos y gestos a partir de un video de referencia de una persona real de unos 15 segundos, y luego los transfiere a un nuevo guion, vestuario, escenario, ángulo de cámara e idioma, generando videos de avatar de alta resolución de duración ampliable. Es adecuado para equipos que necesitan que la misma persona aparezca de forma estable en formación, marketing, ventas y contenido de localización, no para animaciones puntuales a partir de fotos ni personajes ficticios.
Puntos clave
- Modelado a partir de video de referencia, identidad coherente entre escenarios: extrae rasgos de identidad a partir del contexto completo de un video en lugar de un solo fotograma, reduciendo la deriva al transferir a distintos estilos y escenarios.
- Movimientos y gestos reales que se transfieren junto con la identidad: las acciones interpretativas provienen del movimiento real del video de referencia, lo que aporta mayor naturalidad al generar videos con locución.
- Impulso dual por texto o audio: se puede introducir directamente el texto del guion para que lo lea la síntesis de voz integrada, o subir un audio para sincronizar los labios, cambiando de flujo de trabajo según se necesite.
- Crear el avatar una vez y reutilizarlo en múltiples escenarios: el mismo avatar se puede reutilizar con nuevos guiones, vestuario, ángulos de cámara e idiomas, reduciendo el coste de rodajes repetidos y de ajuste en postproducción.
Descripción de capacidades
Creación de avatares reutilizables a partir de video de referencia: aprende rasgos faciales y de movimiento de un video de referencia de una persona real de unos 15 segundos, formando un avatar digital que puede invocarse repetidamente, sin necesidad de volver a capturar material en generaciones posteriores.
Generación de locución impulsada por texto: se introduce un guion de hasta 5000 caracteres y se selecciona una voz; el modelo realiza la síntesis de voz y la generación de la interpretación, produciendo directamente un archivo de video con sincronización labial.
Sincronización labial impulsada por audio: basta con proporcionar una URL HTTPS de audio para impulsar la sincronización labial del avatar, con un audio de hasta 600 segundos; en este caso, los parámetros de guion y voz no surten efecto, lo que resulta adecuado para equipos que ya disponen de material de doblaje.
Control de parámetros de imagen y formato de entrega: admite resoluciones de 720p, 1080p y 4k, relaciones de aspecto como 16:9, 9:16, 4:5, 5:4 y 1:1, permite cambiar a fondo de color sólido o imagen, eliminar el fondo y exportar en mp4 o webm.
Archivo adicional de subtítulos: al activar la opción de subtítulos, se devuelve junto con el video un archivo de subtítulos SRT, lo que facilita su publicación posterior en plataformas o la sustitución por subtítulos en varios idiomas.
Escenarios de aplicación
- Equipos de formación corporativa: guion de curso + avatar de instructor unificado: genera por lotes videos de conocimiento con el mismo instructor en pantalla, manteniendo la imagen de la persona coherente a lo largo de la serie de cursos, para usarlos directamente en la plataforma de aprendizaje interna.
- Marketing y ventas: guion de locución de producto + avatar de personaje de marca: produce rápidamente material de locución con personaje en varias versiones, cambiando la relación de aspecto y el fondo según el canal, para su uso en campañas en redes sociales y páginas de seguimiento comercial.
- Equipos de localización: audio de doblaje existente + avatar del mismo personaje: utiliza audios de doblaje en distintos idiomas para impulsar la sincronización labial del mismo avatar y producir versiones en varios idiomas, reduciendo el coste de nuevos rodajes.
- Comunicación externa: imagen de directivos + discurso formal: crea un avatar a partir de un video de referencia de un directivo y genera, según el texto, videos de discursos externos y de embajador de marca, manteniendo una imagen uniforme en múltiples publicaciones.
Limitaciones y recomendaciones de selección
Este modelo requiere un video de referencia de una persona real como entrada de identidad y no puede iniciarse solo con una foto; para animaciones puntuales a partir de fotos o personajes ficticios conviene elegir otro modelo. La generación se factura por segundos de salida, por lo que en videos largos hay que calcular el coste de antemano. Al usar avatares de personas reales debe obtenerse una autorización por escrito explícita y gestionar bien los permisos de la cuenta. Si la necesidad es una foto hablando de forma ligera o una imagen no real, se recomienda usar una vía más adecuada como Avatar IV.
Novedades
Ver el registro de cambios →- Nuevo modelo Nuevo modelo: heygen-avatar-v, genera videos de avatares digitales en pantalla a partir de un guion con voces predefinidas o audio de conducción; ofrece 497 avatares digitales...
Crear una tarea de generación
https://api.hiapi.ai/v1/tasks Encabezados
AuthorizationstringObligatorioClave API de la cuenta. Obligatoria en cada solicitud. Ejemplo: Bearer YOUR_HIAPI_API_KEY. Obtener clave API
Content-TypestringOpcionalEl cuerpo de la solicitud siempre se analiza como JSON; si se envía, solo se acepta application/json (charset opcional) — cualquier otro valor devuelve 415. Ejemplo: application/json.
Idempotency-KeystringOpcionalClave de idempotencia, hasta 255 bytes. Los reintentos con la misma clave de la misma cuenta crean la tarea una sola vez; las repeticiones devuelven el taskId original.
Ante timeouts de red o reintentos automáticos del cliente, la misma clave crea la tarea una sola vez, sin doble cobro (alcance = la cuenta de la clave API). Usa un identificador de negocio único (p. ej. "order-42"); las repeticiones devuelven el taskId original y las claves caducan 24 h después de la primera solicitud. La matriz completa de escenarios está en la introducción de la API asíncrona unificada.
Cuerpo
modelstringObligatorioValor fijo actual: heygen-avatar-v
routestringOpcionalValor fijo actual: default
inputobjectObligatorio
Objeto de parámetros de negocio para heygen-avatar-v y la ruta default; consulta la tabla de parámetros a continuación.
fitstringOpcionalPredeterminado: "cover"Controla el modo de ajuste de la imagen del avatar; tipo cadena, valor predeterminado cover.
containcovervoicestringOpcionalPredeterminado: "Warm Pro Narrator"minLength 1Especifica el nombre de la voz de texto a voz; tipo cadena, valor predeterminado Warm Pro Narrator; este parámetro se ignora cuando se proporciona audio_url.
Warm Pro NarratorChill BrianIvyJohn DoeMonika SogamHope Archer BrittneyMostrar todo (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 BlackwoodGinnyHopeavatarstringOpcionalPredeterminado: "Abigail Sofa Front"minLength 1Especifica el nombre del avatar predefinido de Avatar V; tipo cadena, valor predeterminado 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 todo (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 5000Contenido de texto que el avatar va a leer; tipo cadena; obligatorio cuando no se proporciona audio_url.
captionbooleanOpcionalPredeterminado: falseSi se devuelve además un archivo de subtítulos SRT; tipo booleano, valor predeterminado false.
audio_urlstringOpcionalpattern ^https://Dirección de audio HTTPS para la sincronización labial; tipo cadena, audio de hasta 600 segundos; cuando se proporciona este parámetro, se ignoran tanto prompt como voice.
backgroundobjectOpcional
Grupo de configuración del fondo; controla la configuración del fondo del vídeo de salida e incluye dos subcampos: tipo y valor.
typestringObligatorioEspecifica el tipo de fondo; tipo cadena; los valores concretos los determina la configuración del grupo background.
colorimagevaluestringObligatoriominLength 1Especifica el valor del fondo; tipo cadena; se usa junto con background.type.
resolutionstringOpcionalPredeterminado: "720p"Controla la resolución del vídeo de salida; tipo cadena, valor predeterminado 720p.
720p1080p4kaspect_ratiostringOpcionalPredeterminado: "16:9"Controla la relación de aspecto de la imagen del vídeo de salida; tipo cadena, valor predeterminado 16:9.
16:99:164:55:41:1autooutput_formatstringOpcionalPredeterminado: "mp4"Controla el formato del archivo de salida; tipo cadena, valor predeterminado mp4.
mp4webmremove_backgroundbooleanOpcionalPredeterminado: falseSi se elimina el fondo de la imagen; tipo booleano, valor predeterminado false.
callbackobjectOpcional
Configuración de notificación de estado terminal. Si se omite, no hay callback: consulta la tarea por tu cuenta.
Indica callback.url al crear y HiAPI hará POST a tu servicio en el estado terminal, sin necesidad de sondeo. El cuerpo del callback replica la estructura del detalle de la tarea; firma, reintentos e idempotencia se detallan en la introducción de la API asíncrona unificada.
urlstringObligatorioObligatorio si se incluye callback. Al estado terminal se envía un POST a esta URL; debe ser una URL http(s) válida.
whenstringOpcionalPredeterminado: "final"Actualmente solo se admite final: notifica tanto en success como en fail.
finalstoragestringOpcionalPredeterminado: "temp"Nivel de almacenamiento de artefactos: temp (por defecto, ~7 días) o persistent (largo plazo, facturado por tamaño). Saldo insuficiente o exceso de límite ⇒ degradación silenciosa a temp; el nivel efectivo se muestra en la respuesta del detalle.
temppersistentEjemplos de solicitud
# Envía una tarea asíncrona; devuelve un taskId de inmediato (sin esperar la generación)
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"
} Obtener el detalle de la tarea
https://api.hiapi.ai/v1/tasks/:id Campos de respuesta
taskIdstringObligatorioID de tarea, siempre con prefijo tk-hiapi-.
modelstringObligatorioNombre completo resuelto del modelo. Las tareas enviadas con el parámetro route devuelven base@route (p. ej. gpt-image-2/text-to-image@ext); si no, coincide con el nombre enviado.
routestringOpcionalSolo aparece si se usó el parámetro route explícito; repite el valor enviado.
statusstringObligatorioEstado de la tarea.
queued En cola, sin iniciar.
handling Procesando.
archiving Proceso terminado, preparando artefactos.
success Terminal: completado, artefactos disponibles (se devuelve output).
fail Terminal: error (se devuelve error).
Tras el envío, guíate por status: success y fail son terminales; el resto, no. Sondea cada 1–3 s hasta el estado terminal. Con éxito, descarga los artefactos desde output[].url y transfiérelos antes de expireAt; para retención larga usa storage: "persistent" al crear.
creatednumberObligatorioHora de creación de la tarea (segundos Unix).
completednumberObligatorioSegundos Unix al alcanzar estado terminal; 0 mientras no sea terminal.
outputarrayOpcional
Solo con status == success. Lista de artefactos — siempre un array; una tarea puede devolver varios types a la vez (p. ej. video + first_frame).
Array [ object ]
Elementos del array
urlstringObligatorioURL del artefacto, descargable directamente.
typestringObligatorioValores posibles actuales: video, image, audio, first_frame, last_frame, thumbnail; podrían ampliarse más adelante.
expireAtnumberObligatorioSegundos Unix hasta los que el artefacto es accesible; descárgalo o transfiérelo antes.
errorobjectOpcional
Solo con status == fail.
codestringObligatorioCódigo de error de negocio.
messagestringObligatorioDescripción del error.
Ejemplos de respuesta
Éxito
{
"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
}
]
}
} En proceso (no terminal)
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "archiving",
"created": 1777282033,
"completed": 0
}
} Fallido
{
"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"
}
}
} Artículos
Ver todos los artículos →-
Tutorial
Cómo llamar a hailuo-2.3/text-to-video mediante la API de HiAPI: curl, Python y ejemplos de solicitud ejecutables
-
Comparativa
hailuo-2.3-fast/image-to-video comparativa horizontal: cómo elegir un modelo de imagen a video y puntos clave para migrar
-
Tutorial
Uso de Kandinsky 6.0 Pro texto a video en HiAPI: tutorial con curl y Python
Demostración práctica centrada en la solicitud: construir la llamada de prompt a clip de video, enviar la solicitud, sondear el estado de finalización y descargar el resultado
-
Tutorial
Tutorial de kandinsky-6.0-pro/image-to-video en HiAPI: curl + Python
Realiza una solicitud de imagen a video funcional en HiAPI: desde la carga del primer fotograma hasta el sondeo asíncrono y la descarga final
-
Tutorial
Cómo usar kling-4.0/text-to-video a través de la API de HiAPI: curl, Python y un ejemplo de solicitud ejecutable
Guía práctica para desarrolladores: prompts cinematográficos, audio sincronizado, sondeo asíncrono y descarga de resultados
-
Tutorial
Cómo llamar a hailuo-2.3-fast/image-to-video a través de la API de HiAPI: práctica con curl y Python
La primera solicitud ejecutable del nivel rápido y de bajo coste de imagen a vídeo: del ID del modelo a la descarga del MP4
-
Comparativa
Recraft v4.1 Flash comparativa horizontal de texto a imagen: guía de selección y migración para desarrolladores
Con un coste de $0.01 por imagen y capacidad pura de texto a imagen, evalúa si encaja en tu pipeline de generación de imágenes
-
Tutorial
Cómo llamar a kling-4.0/image-to-video en HiAPI: curl, Python y sondeo
Modelos relacionados
Ver todos los modelos →Mismo tipo
-
FLUX 3 Video Black Forest Labs $0.090 /segundo -
Vidu Q4 Preview Vidu $0.051 /segundo -
Kling 3.0 Turbo Kuaishou $0.130 /segundo -
Grok Imagine 1.5 xAI $0.011 /segundo -
Runway Gen 4.5 Runway $0.172 /segundo -
HappyHorse 1.1 Alibaba $0.160 /segundo -
Veo 3.1 Lite Google $0.060 /segundo -
PixVerse V6 PixVerse $0.036 /segundo -
Veo 3.1 Google $0.290 /segundo -
Wan 2.7 Video Alibaba $0.100 /segundo -
Wan 3.0 Video Alibaba $0.040 /segundo -
Veo 3.1 Fast Google $0.170 /segundo