Errores comunes de la API de HeyGen y cómo solucionarlos en 2026
Has integrado la API de HeyGen en tu workflow para automatizar producción y, en algún momento, los errores aparecen. Una credencial caducada, un rate limit que tumba el pipeline, vídeos que se quedan en estado processing y no terminan, timeouts en peticiones largas. La diferencia entre frustrarse y resolver es saber qué error es cuál y cómo se diagnostica. Este post recoge los errores reales que vemos en clientes de Grouthers integrando HeyGen via API, con códigos concretos, causas más probables y soluciones que han funcionado en producción.
Los errores más comunes de la API de HeyGen en 2026 y sus soluciones rápidas son:
- Error 401 Unauthorized = API key inválida, caducada o mal cabecera (revisar X-API-KEY header y rotar key si necesario).
- Error 429 Too Many Requests = rate limit superado (HeyGen permite ~100 requests/min y ~10 vídeos concurrentes en planes pago; añadir backoff exponencial y queueing).
- Vídeos en estado processing que no terminan tras 30+ min = puede ser servidor saturado o problema con asset, hacer polling status con timeout máximo y reintentar tras 1h.
- Timeouts en peticiones largas = aumentar timeout del cliente HTTP a 60s+ y usar webhooks en lugar de espera síncrona.
- Polling mal configurado = no consultar status cada 1-2s, hacerlo cada 10-30s para no chocar con rate limit.
- Webhooks que no llegan = verificar URL pública accesible desde internet y firma del webhook.
- Inconsistencia entre API y web = la API puede tardar 1-5 min en reflejar cambios hechos vía web.
- Errores específicos de Avatar IV en API = verificar que el endpoint soporta IV (algunos solo III) y que tu plan tiene acceso.
La estrategia general de troubleshooting: revisar status code, log de respuesta, fecha de la key, plan activo, rate limit actual y polling rate. El desglose completo está abajo con casos concretos.
Si todavía no tienes el setup base de la API, API HeyGen cubre la configuración inicial. Para automatización avanzada, automatizar HeyGen API tiene los workflows típicos. Y si tu equipo está produciendo a gran escala, escalar contenido HeyGen 100 vídeos cubre los flujos de batch en producción.
Error 401 Unauthorized: cómo arreglar las credenciales
El error HTTP 401 Unauthorized indica que la API key no es válida o no se está enviando correctamente. Es el error número uno que ven los desarrolladores al integrar HeyGen por primera vez.
Causas más comunes del 401 en 2026:
- API key inválida o mal copiada: error trivial pero frecuente. Revisa que no hayas copiado espacios extra al inicio/final o que falte algún carácter.
- API key caducada o revocada: HeyGen permite rotar keys. Si la rotaste y olvidaste actualizar en tu código, las peticiones siguen llamando a la key vieja.
- Header incorrecto: HeyGen espera el header `X-API-KEY` (mayúsculas exactas). Algunos developers usan `Authorization: Bearer` por hábito de otras APIs — falla. La cabecera correcta es `X-API-KEY: tu_key`.
- Cuenta en plan Free sin acceso a API: la API requiere plan pago (Creador, Pro o Business). Si estás en Free, no hay key disponible o las peticiones devuelven 401.
- Endpoint incorrecto: si llamas a un endpoint de Sandbox con key de producción o viceversa, falla con 401. Asegúrate de coherencia entre key y URL.
- Key generada en cuenta diferente: si tienes varias cuentas HeyGen (personal, empresa), verifica que la key corresponde a la cuenta cuyo plan estás usando.
Flujo de troubleshooting paso a paso:
- Imprime la key tal cual la estás enviando (cuidado, no en logs de producción) y compárala con la que ves en HeyGen → Settings → API.
- Verifica el header: debe ser `X-API-KEY` exacto, no `x-api-key` ni `API-KEY` ni `Authorization`.
- Prueba con `curl` directo para descartar problema del cliente HTTP: `curl -H "X-API-KEY: tu_key" https://api.heygen.com/v2/voices`.
- Si funciona en curl pero falla en tu código, el problema es cómo tu cliente HTTP envía la cabecera.
- Si falla también en curl, regenera la key en HeyGen → Settings → API → Revoke + New Key, y actualiza en tu código.
- Verifica que tu plan tiene API habilitada y no está suspendido por incidencia de pago.
Recomendación de seguridad: nunca commitees la API key al repositorio. Usa variables de entorno (`HEYGEN_API_KEY`) y `.env.local` gitignored. Si por error commiteaste, rota la key inmediatamente.
Rate limits superados: gestión de carga
El error HTTP 429 Too Many Requests indica que has superado el rate limit de la API. HeyGen aplica límites para proteger su infraestructura y los límites concretos dependen de tu plan.
Rate limits típicos en 2026:
- Requests por minuto: típicamente 100 requests/min en planes Creador y Pro, 300+ en Business, ilimitado en Enterprise.
- Vídeos concurrentes: aproximadamente 10 vídeos en procesamiento simultáneo en planes pago. Si lanzas 20 a la vez, los 10 últimos se quedan en cola.
- Generaciones por hora: depende del plan pero típicamente 50-100 generaciones/hora en Pro.
- Webhooks por minuto: si HeyGen envía webhooks a tu URL, hay límite de cuántos puede mandar por minuto sin agruparlos.
Capta más clientes desde redes
Capta más clientes desde redes sin reinventar la rueda.
Más de 40 recursos: plantillas para duplicar, prompts probados y guías paso a paso. Acceso gratuito al acceder a los recursos.
Cómo gestionar rate limits correctamente:
- Backoff exponencial: si recibes 429, espera 1s, reintenta. Si falla, espera 2s, reintenta. Luego 4s, 8s, 16s. Después de 5 reintentos sin éxito, marca como error definitivo.
- Respeta el header `Retry-After`: HeyGen incluye este header en la respuesta 429 indicando segundos a esperar. Úsalo en lugar de calcular tu propio backoff.
- Queue de generación: en producción de volumen, no lances todas las generaciones a la vez. Encola y procesa con concurrencia limitada (típicamente 5-8 simultáneas).
- Throttle del cliente: en lugar de reaccionar a 429, prevén con throttling. Si tu cuota es 100 req/min, no excedas 80 req/min para tener margen.
- Monitoring del rate: loguea cuántas requests por minuto envías y configura alertas si te acercas al límite.
- Upgrade de plan si lo necesitas: si tu carga real supera el límite del plan, el upgrade puede ser solución más estructural que micro-optimización.
Para workflows complejos con muchas generaciones, automatizar HeyGen API cubre los patrones de queueing y orchestración.
Vídeos en estado processing que no terminan
Uno de los problemas más frustrantes: lanzas una generación, la API confirma el job, haces polling, y el estado se queda en `processing` indefinidamente. Aparenta que el vídeo está colgado pero técnicamente sigue en proceso desde el lado del servidor.
Causas más probables:
- Cola saturada en HeyGen: en picos de uso (horarios USA business hours), las colas se llenan y los vídeos esperan más de lo normal. Tiempo de espera de 30 min a 2h posible en peaks.
- Asset corrupto o muy pesado: si subiste audio o imagen de fondo muy pesados, el procesamiento puede atascarse. Revisa tamaños de assets.
- Guion demasiado largo para el plan: si excedes el límite de duración del plan (5 min en Creador, 30 min en Pro), el procesamiento puede fallar silenciosamente.
- Conflicto entre features: combinaciones de Avatar IV + Translation + voice clone custom + subtítulos pueden causar errores que se manifiestan como processing eterno.
- Error del servidor no reportado: en casos raros, el servidor falla pero no actualiza el estado a `failed` correctamente.
Cómo manejarlo:
- Timeout máximo: define tiempo máximo de espera razonable (30-60 min). Pasado ese tiempo, marca como error y trata como tal.
- Polling con intervalo creciente: empieza haciendo polling cada 30s, luego cada 1 min, luego cada 2 min. No pollees cada segundo o saturarás rate limit.
- Comprobar en la web: si el job lleva mucho tiempo en `processing`, abre HeyGen en navegador y mira tu biblioteca. A veces el vídeo está generado pero la API no se actualizó.
- Reintento tras timeout: si pasa más de 1h en `processing`, asume fallo y crea un job nuevo con los mismos parámetros.
- Contactar soporte si es recurrente: si el patrón se repite con frecuencia, hay algo en tu setup o en HeyGen que requiere intervención. Contacta soporte con IDs de vídeo afectados.
Timeouts en peticiones largas
Si tu cliente HTTP tiene timeout corto (típicamente 10-30s por defecto), las peticiones largas de HeyGen fallan con error de timeout antes de que el servidor responda. Especialmente notable en endpoints que devuelven respuestas pesadas o en operaciones síncronas.
Endpoints típicamente más lentos:
- Listar todos los avatares y voces: si tu cuenta tiene muchos custom avatares, el listing puede tardar 10-30s.
- Lanzar generación síncrona: aunque HeyGen recomienda usar webhooks o polling, algunos endpoints síncronos esperan respuesta del processing y exceden timeouts cortos.
- Descargar vídeo generado: descarga de archivos grandes puede exceder timeouts si conexión es lenta.
- Operaciones batch: si pides operación masiva (re-generar varios vídeos a la vez), respuesta inicial puede tardar.
Cómo configurar timeouts adecuados:
- Cliente HTTP con timeout extendido: configura tu librería (axios, requests, fetch) con timeout de al menos 60s. En operaciones de batch, hasta 120s.
- Operaciones asíncronas siempre que sea posible: en lugar de esperar respuesta de generación, lanza el job, recibe el ID, y consulta status después.
- Webhooks en lugar de polling síncrono: HeyGen llama a tu URL cuando el vídeo está listo. Sin polling, sin timeout. Más limpio en producción.
- Retry con backoff en timeout: si un timeout falla, reintenta una o dos veces. A veces es problema de red puntual.
- Logging detallado: registra tiempos de cada petición para identificar qué endpoints son más lentos y ajustar timeouts específicamente.
Problemas de polling y webhooks
Hay dos formas de saber cuándo tu vídeo está listo: hacer polling al endpoint de status o configurar webhook que HeyGen llame. Cada uno tiene problemas típicos.
Recursos gratuitos
Más de 40 recursos gratuitos disponibles.
Plantillas, prompts probados, guías paso a paso y bancos de ideas para captar más clientes desde redes sociales. Acceso gratuito.
Problemas comunes con polling:
- Polling demasiado frecuente: si pollas cada 1s, agotas tu rate limit rápidamente. Mínimo 10-30s entre polls según volumen.
- Polling indefinido sin timeout: si un job se cuelga, polling sigue para siempre. Define máximo de intentos.
- No hacer backoff ante 429: si polling provoca 429, esperar y reintentar sin penalizar el sistema.
- No tener manejo de error en polling: errores de red durante polling deben tratarse como retry, no como fallo definitivo.
Problemas comunes con webhooks:
- URL no pública: webhooks de HeyGen necesitan URL accesible desde internet. `localhost` no funciona. En desarrollo, usa ngrok, Cloudflare Tunnel o servicio similar para exponer localhost.
- Webhook que no responde 2xx: si tu endpoint devuelve error 5xx, HeyGen puede reintentar o marcar como fallo. Asegúrate de responder 200 inmediatamente y procesar asíncronamente.
- Verificación de firma: HeyGen firma sus webhooks. Si no verificas la firma, alguien puede falsificar requests. Implementa verificación en producción.
- Timeouts en tu webhook: si tu lógica de procesamiento tarda más de unos segundos, HeyGen puede marcar el webhook como fallido. Responde 200 inmediato y procesa en background job.
- Webhooks que no llegan: si configuraste webhook pero no recibes nada, verifica logs en HeyGen, firewall en tu servidor, y URL accesible desde fuera con `curl` desde otro servidor.
Recomendación: en producción, usa webhooks como mecanismo principal y polling como fallback si tras X tiempo no llegó webhook. Combinación robusta.
Inconsistencia entre API y web
Un problema sutil: cambios hechos en la web de HeyGen (crear avatar custom, subir voz clonada, modificar plantilla) pueden tardar minutos en aparecer disponibles via API. Y viceversa: contenido creado via API puede tardar en reflejarse en la web.
Casos comunes en 2026:
- Avatar custom nuevo no disponible en API: creas avatar en la web, intentas usarlo en API y obtienes "avatar not found". Espera 5-10 minutos y reintenta.
- Voice clone que aparece como "training" indefinido: el voice clone se entrenó en la web pero la API lo ve como aún en training. Refresca el listado tras 10-15 minutos.
- Vídeo generado via API que no aparece en biblioteca web: la API lo creó pero la web no lo refleja. Refresca la web o espera unos minutos.
- Cambios de configuración (idioma de voz, parámetros) no aplicados: si modificaste configuración via web, la API puede seguir usando configuración antigua durante un periodo de caché.
Soluciones:
- Esperar 5-15 minutos antes de usar contenido recién creado: dale tiempo a que se propague la sincronización entre sistemas.
- Refrescar listados regularmente: si tu app cachea avatares disponibles, invalida cache cada X minutos.
- Crear contenido programáticamente via API: si tu workflow es completamente API, evita crear vía web para minimizar inconsistencias.
- Contactar soporte si la inconsistencia persiste más de 1h: en ese caso es bug, no propagación normal.
Errores específicos de Avatar IV en API
Avatar IV via API tiene algunas particularidades que pueden generar errores específicos. Avatar IV es modelo más nuevo y la integración API ha tenido más iteraciones recientes.
- "Avatar IV not available in your plan": tu plan no incluye Avatar IV via API. Verifica que tienes Pro o superior con acceso a Avatar IV habilitado.
- Créditos insuficientes para Avatar IV: Avatar IV consume 20 créditos por minuto. Si tu cuenta no tiene créditos suficientes, la generación falla. Verifica créditos antes de lanzar batch.
- Endpoint mal configurado para IV: algunos endpoints antiguos solo soportan Avatar III. Verifica documentación oficial para el endpoint que estás usando.
- Parámetros adicionales requeridos: Avatar IV requiere algunos parámetros que Avatar III no (control de movimiento corporal, gestos). Revisa schema completo.
- Errores de configuración voice + Avatar IV: ciertas combinaciones de voz preconfigurada con Avatar IV pueden fallar. Si el error es ambiguo, prueba con voice clone propio o voz preconfigurada distinta.
Para profundizar en las diferencias técnicas entre Avatar III y IV en API, Avatar III vs IV HeyGen cubre los matices.
Logs y debugging para encontrar la causa
Sin logs detallados, debugging de problemas API es prácticamente imposible. El primer paso en cualquier troubleshooting serio es asegurarse de que tienes logs útiles.
Qué loguear obligatoriamente en producción:
- Request enviada: método HTTP, URL, headers (excepto API key por seguridad), body resumido o completo según contexto.
- Response recibida: status code, headers de respuesta (especialmente `Retry-After`, `X-RateLimit-Remaining`), body completo en errores, resumen en éxitos.
- Timing de cada petición: cuánto tardó desde que enviaste hasta que recibiste respuesta. Útil para identificar lentitud anormal.
- Estado de cada job a lo largo del tiempo: si haces polling, loguea cada cambio de estado con timestamp.
- Errores capturados con stack trace: tipo de error, contexto, datos relacionados.
- Rate limit usage: contador de cuántas requests has enviado en la ventana actual.
Kit operativo gratuito
El kit completo para captar más clientes desde redes.
Plantillas, prompts y guías probados con marcas reales. Más de 40 recursos listos para duplicar y aplicar desde la primera semana. Acceso gratuito.
Herramientas útiles para debugging:
- Postman / Insomnia: para reproducir peticiones manualmente y validar que la API responde como esperas.
- curl con `-v`: en terminal, muestra headers de request y response completos. Útil para ver exactamente qué se está enviando.
- Logs estructurados (JSON): en producción, formato estructurado permite filtrar y buscar mucho más eficientemente que texto plano.
- Sentry, Datadog, similar: para tracking de errores en producción y alertas automáticas.
- HeyGen dashboard: la sección API de HeyGen muestra estadísticas de uso, requests recientes, errores. Útil cuando sospechas problema desde su lado.
Para errores no listados en este post, errores comunes HeyGen cubre incidencias generales que no son específicas de la API.
Preguntas frecuentes
+¿Cuántos vídeos puedo procesar en paralelo?
En la API de HeyGen en 2026, el límite estándar es aproximadamente 10 vídeos en procesamiento concurrente en planes pago (Creador, Pro, Business). En plan Enterprise el límite es notablemente superior y se negocia con soporte según necesidades. La lógica del límite. HeyGen aplica concurrencia limitada para proteger su infraestructura de generación de vídeo (que es computacionalmente intensiva con GPUs). Si lanzas más de 10 vídeos a la vez via API, los 10 primeros se procesan inmediatamente y los siguientes entran en cola interna de HeyGen. La cola se procesa según se liberan slots. En la práctica esto significa: si lanzas 30 vídeos a las 9:00, los primeros 10 empiezan a procesarse, los siguientes 10 entran en cola y empiezan según terminen los primeros, y los últimos 10 esperan más. El throughput total dependerá del plan, del tipo de vídeo y de la carga general del sistema. Cómo gestionar la concurrencia correctamente. Primero: respeta el límite a nivel de tu cliente. No lances más de 10 generaciones simultáneas desde tu código. Usa una librería de concurrencia (p-limit en Node, asyncio.Semaphore en Python, similar) para controlar cuántas peticiones tienes en vuelo. Segundo: detecta cuando se acerca el límite y haz queueing. Si tienes 50 vídeos que generar, no lances los 50 a la vez. Procesa de 8 en 8 (margen de seguridad sobre el 10 oficial) y avanza según terminan. Tercero: maneja el error 429 con backoff. Si superas el rate limit por accidente, HeyGen devuelve 429 con header Retry-After. Espera lo que indica el header y reintenta. Cuarto: monitoriza el rate limit en tiempo real. Los headers de respuesta incluyen información del rate limit actual (X-RateLimit-Remaining, X-RateLimit-Reset). Usa esos valores para ajustar dinámicamente tu throughput. Patrones de producción común. Para producción batch nocturna (50-200 vídeos): empezar generación a las 22:00 hora USA (horario donde HeyGen tiene menos carga), concurrencia 8, esperar webhooks de finalización. Producción típicamente termina en 4-6h. Para producción continua durante el día: concurrencia 5-6, queue con prioridad si algunos vídeos son urgentes, monitoring de rate limit. Para emergencias o producción crítica: contactar soporte HeyGen antes para confirmar que tu plan puede manejar el pico, o considerar Enterprise. Si tu carga real requiere más de 10 vídeos en paralelo de forma sostenida, plantea upgrade a Enterprise con límites negociados. Para automatizaciones avanzadas y patrones de batch, automatizar HeyGen API cubre los workflows.
+¿La API tiene rate limit por minuto?
Sí, la API de HeyGen aplica rate limits a varios niveles en 2026, y conviene conocerlos para diseñar integraciones que no los exceden. Límite de requests por minuto. Aproximadamente 100 requests/min en planes Creador y Pro, 300+ en Business, ilimitado o muy alto en Enterprise. "Request" cuenta cualquier llamada a la API, no solo generaciones — listar avatares, consultar status, descargar metadatos, todo cuenta. Si tu integración hace polling agresivo (consultar status cada segundo de cada vídeo en procesamiento), te puedes acercar al límite rápidamente. Cómo se aplica el límite. HeyGen usa ventana deslizante: cada 60 segundos cuenta requests recibidas y bloquea si excedes el umbral. No es reset por minuto natural (00:00, 01:00, 02:00...) sino ventana móvil que considera los últimos 60s. Implicación: si haces 100 requests en 30s, las siguientes 30s estás bloqueado aunque sea "el siguiente minuto" calendario. Headers que devuelve la API. En cada respuesta HeyGen incluye headers que te informan del estado del rate limit. X-RateLimit-Limit: el límite total de tu plan. X-RateLimit-Remaining: cuántas requests te quedan en la ventana actual. X-RateLimit-Reset: timestamp cuando se reseteará la ventana. Cuando recibes 429 (Too Many Requests): Retry-After: segundos a esperar antes de reintentar (úsalo directamente sin calcular tu propio backoff). Estrategias para no exceder el límite. Primera: throttling proactivo en el cliente. Si tu plan tiene 100 req/min, configura tu cliente para no exceder 80 req/min. Mantén margen. Segunda: polling inteligente con intervalos crecientes. Empieza polling cada 30s, si pasan 5 min y no hay cambio, espacia a cada 1 min, luego cada 2 min. No hagas polling cada segundo. Tercera: batching donde sea posible. Si necesitas información de 100 vídeos, no hagas 100 requests individuales. Algunos endpoints permiten consulta múltiple en una sola request. Cuarta: webhooks en lugar de polling cuando es viable. Webhooks notifican cambios sin que tengas que preguntar repetidamente. Reducen drásticamente el consumo de rate limit. Quinta: caché local de información que cambia raramente. Lista de avatares disponibles, voces, configuraciones — cachéalos por horas o días, no consultes en cada request. Sexta: queue de requests con concurrencia limitada. Si lanzas operación masiva, no lances todas las peticiones a la vez. Procesa con concurrencia controlada (típicamente 5-10 simultáneas). Cuándo necesitas más rate limit. Si tu uso real supera consistentemente el límite de tu plan, considera upgrade o contacta a HeyGen para Enterprise. Otra opción: arquitectar el sistema para distribuir carga (caches, batching, reducción de polling). En la mayoría de casos hay optimizaciones de diseño antes de necesitar upgrade. Para entender los rate limits en el contexto de la integración completa, API HeyGen cubre los detalles técnicos.
+¿Por qué mi vídeo se queda procesando para siempre?
Si un vídeo en HeyGen se queda en estado processing más de lo razonable (30+ min) y no avanza, hay varias causas posibles y el flujo de troubleshooting depende del síntoma exacto. Causas más probables en 2026. Primera causa: cola saturada en HeyGen. En picos de uso del sistema (horarios USA business hours, 15:00-22:00 UTC, especialmente martes-jueves), la cola interna de generación puede acumular jobs y los tiempos se alargan notablemente. Tiempo normal de generación de un vídeo de 3 min con Avatar IV: 10-20 min. En picos puede ser 30-60 min. Si tu vídeo lleva 45 min, posiblemente sea cola normal en pico. Segunda: asset corrupto o muy pesado. Si subiste imagen de fondo, audio adicional o cualquier asset, su procesamiento puede atascarse si el archivo es muy pesado (>50MB) o tiene formato problemático. Verifica que tus assets cumplen recomendaciones técnicas de HeyGen. Tercera: guion excede límite del plan. Si tu guion genera un vídeo más largo que el límite (5 min en Creador, 30 min en Pro), el procesamiento puede fallar silenciosamente sin actualizar status. Verifica duración estimada antes de generar. Cuarta: conflicto entre features. Combinaciones complejas como Avatar IV + Translation con lipsync + voice clone custom + subtítulos automáticos pueden generar conflicts internos que se manifiestan como processing eterno. Si usas combinación inusual, simplifica y vuelve a probar. Quinta: error del servidor no reportado. En casos raros, el job falló pero el servidor no actualizó el estado a failed. El job se queda "colgado" técnicamente pero realmente está muerto. Sexta: tu API key tiene problema o tu plan está suspendido temporalmente. El job se aceptó cuando todo estaba OK pero algo cambió mid-procesamiento. Cómo manejarlo paso a paso. Paso 1: verifica que el vídeo realmente sigue en processing. A veces el bug es de polling — el vídeo terminó pero tu sistema no se enteró. Revisa via web en tu biblioteca de HeyGen. Si aparece como completado, fue problema de polling/webhook. Paso 2: si lleva menos de 30 min, espera. Es probable que sea cola normal especialmente en horario pico. Paso 3: si lleva 30-60 min, verifica si tu cuenta sigue activa y con créditos suficientes. Si hubo cobro fallido o agotamiento de créditos mid-procesamiento, esa puede ser causa. Paso 4: si lleva más de 1h, asume fallo y crea job nuevo con los mismos parámetros. No hay forma fiable de "despertar" un job colgado. Paso 5: si esto se repite con frecuencia (más de 2-3 veces por semana), hay algo sistemático mal. Contacta soporte de HeyGen con: IDs de los jobs afectados, configuración de generación, tipo de assets usados, hora exacta de envío, plan activo. Soporte puede revisar logs internos y encontrar el patrón. Paso 6: mientras debuggeas, considera workflow de fallback: si un job lleva más de X tiempo en processing, lánzalo de nuevo automáticamente. No bloqueas producción esperando jobs colgados. Cómo prevenir el problema. Genera vídeos en horarios de menos carga (madrugada/mañana hora USA). Verifica límite de duración antes de enviar. Simplifica combinaciones de features cuando sea posible. Usa Avatar III para iteraciones (más rápido y menos propenso a problemas) y reserva Avatar IV para versiones finales.
+¿Hay sandbox para testear sin gastar créditos?
HeyGen ofrece capacidades limitadas de testing sin consumir créditos premium pero no es un sandbox completo equivalente al de producción. La situación en 2026. No hay un entorno sandbox completamente separado donde puedas probar la API sin consumir créditos. La cuenta de desarrollo y producción son la misma cuenta. Sin embargo, hay varias formas de minimizar el consumo de créditos durante testing. Opción 1: usa el plan Free para testing inicial. El plan gratuito de HeyGen da 3 vídeos al mes con watermark. Para validar que tu integración funciona técnicamente (autenticación, polling, webhooks, parseo de respuestas), 3 vídeos al mes son suficientes. Cuando todo funciona, pasas a plan pago para producción real. Opción 2: usa Avatar III para iteraciones. Avatar III no consume créditos premium en planes pago. Si estás probando lógica de generación, configuración de avatares, polling, webhooks — todo eso lo puedes hacer con Avatar III ilimitadamente. Cuando la integración está validada, cambias a Avatar IV solo para los vídeos finales que realmente necesitas. Opción 3: usa endpoints de información (no generación) que son gratuitos. Listar avatares, listar voces, consultar status de jobs, descargar metadatos — ninguno de estos consume créditos. Puedes ejecutar tests automatizados sobre esos endpoints sin coste. Opción 4: vídeos muy cortos para testing. Si necesitas validar generación completa, hazlo con vídeos de 10-15 segundos en lugar de 2-3 minutos. Consumo proporcional menor. Avatar IV en vídeo de 15s = 5 créditos, vs 60 créditos en vídeo de 3 min. Opción 5: mock responses en tests automatizados. Para tests unitarios y de integración que no requieren llamar a la API real, usa mocks. Validas tu lógica de parseo, manejo de errores, retry logic, etc., sin consumir nada. Opción 6: cuenta separada para testing. Algunas empresas mantienen cuenta HeyGen específica para QA/staging con plan Creador básico, y reservan la cuenta de producción con plan superior para producción real. Permite testing realista sin afectar créditos de producción. Lo que sería ideal pero NO existe en 2026. Sandbox separado con API key específica que devuelva respuestas dummy sin consumir créditos. Generación simulada sin coste pero con respuestas equivalentes. Lo más cercano es la combinación de Avatar III ilimitado + plan Free + endpoints de info. HeyGen ha mencionado en su roadmap mejorar las opciones de testing pero no hay sandbox formal lanzado en 2026. Workflow de testing recomendado para integraciones serias. Fase 1 (desarrollo local): mocks para tests unitarios, Avatar III en cuenta personal Free para validación end-to-end. Fase 2 (staging): cuenta separada Creador, Avatar III para todos los flujos, Avatar IV en 2-3 casos límite para confirmar que funciona. Fase 3 (producción): cuenta principal con plan adecuado al volumen real. Monitoring de créditos consumidos vs lo planeado. Para automatización avanzada con buenas prácticas, automatizar HeyGen API cubre patrones de producción.
+¿Cómo contacto con soporte técnico de la API?
El soporte técnico de la API de HeyGen está disponible vía varios canales en 2026, con tiempos de respuesta variables según el plan y la urgencia. Canales oficiales disponibles. Canal 1: email a support@heygen.com. Es el canal estándar para todos los planes pago. Tiempo de respuesta típico 24-48h hábiles para planes Creador y Pro, más rápido para Business y Enterprise. Útil para problemas no urgentes pero complejos que requieren investigación. Canal 2: chat en vivo desde el dashboard. Disponible para usuarios con sesión activa. Tiempo de respuesta inmediato o pocas horas según hora y disponibilidad. Útil para preguntas relativamente rápidas o aclaraciones. Canal 3: portal de soporte / centro de ayuda. HeyGen tiene base de conocimiento con FAQ, tutoriales y guías técnicas. Antes de contactar soporte, busca ahí — muchos problemas comunes están documentados. Canal 4: comunidad y foros oficiales. HeyGen tiene Discord oficial y a veces foros de comunidad. Útil para preguntas técnicas donde otros developers pueden haber resuelto el mismo problema. Tiempo de respuesta variable. Canal 5: account manager dedicado (Enterprise). Si tu plan es Enterprise, tienes account manager asignado con respuesta rápida y soporte prioritario. Qué información incluir cuando contactes soporte API. Primero: descripción clara del problema. "La API devuelve 500 al llamar a /v2/videos" es mejor que "la API no funciona". Sé específico. Segundo: ID de cuenta y plan activo. Permite a soporte localizar tu setup. Tercero: timestamp exacto cuando ocurrió el problema. Soporte revisa logs internos por timestamp. Cuarto: request específica que falló: método, URL, headers (sin API key), body. Si es problema recurrente, varios ejemplos. Quinto: respuesta exacta recibida: status code, headers de respuesta, body completo. Sexto: comportamiento esperado vs comportamiento observado. Séptimo: pasos para reproducir si es posible (si soporte puede replicar el error, soluciona más rápido). Octavo: stack trace o logs si tienes integración compleja. Noveno: capturas de pantalla si aplica. Décimo: si el problema es bloqueante para tu producción, indícalo claramente. Soporte prioriza casos bloqueantes. Cuándo escalar más allá de soporte. Si soporte estándar no resuelve en 3-5 días y el problema es crítico para tu negocio, las opciones son: contactar a tu account manager si tienes plan Business+ con uno asignado. Pedir escalado a soporte técnico de segundo nivel (engineering). Abrir caso público en redes sociales (Twitter/LinkedIn) mencionando a HeyGen — a veces acelera respuesta cuando el equipo de marketing/social ve un usuario frustrado. Considerar consultora externa especializada en HeyGen si tu integración es muy compleja y necesitas soporte experto inmediato. Lo que no funciona bien con soporte. Reportar problema sin información técnica suficiente. Asumir que soporte adivinará el contexto. Esperar que soporte resuelva problemas que son de tu lado (lógica de tu aplicación, errores tipográficos en tu código). Para problemas no específicos de la API, errores comunes HeyGen cubre incidencias generales que también pueden afectar a tu integración.
En Content Society compartimos los snippets de código que usamos en Grouthers para integraciones HeyGen API en producción (manejo de errores, retry con backoff, queue de concurrencia), los checklists de troubleshooting paso a paso para diagnosticar errores rápidamente, los workflows de monitoring que detectan problemas antes de que afecten producción, y las plantillas de email a soporte técnico que aceleran la respuesta. [Accede a los recursos](/recursos-gratis).
Sobre el autor
Adrián García
@AdrianGarmeFundador de Grouthers, agencia especializada en creación de contenido para marcas personales. He ayudado a más de 50 marcas personales en España, Estados Unidos y Latinoamérica a crecer en redes sociales. Ahora estoy construyendo Content Society, la comunidad para marcas personales que quieren captar más clientes desde redes.
Ahorra horas de producción
Ahorra horas de producción con plantillas que ya funcionan.
Plantillas duplicables, prompts probados, guías paso a paso. Lo que llevas tiempo intentando armar tú solo, listo para usar desde el primer día. Acceso gratuito.
Sigue leyendo
Otros posts del blog que conectan con este tema.
API de HeyGen: para qué sirve y cuándo necesitas usarla en 2026
Guía sobre la API de HeyGen: precios pay-as-you-go, casos de uso reales, requisitos técnicos y cuándo realmente la necesitas en tu negocio.
Cómo automatizar producción de vídeos con HeyGen y la API en 2026
Cómo automatizar la producción de vídeos con HeyGen usando API, Zapier y workflows. Casos reales de escalado a producción industrial.
Los 10 errores más comunes al usar HeyGen (y cómo evitarlos) en 2026
Evita los 10 errores más comunes al usar HeyGen: créditos malgastados, guiones mal estructurados, avatares mal elegidos y más. Aprende de los fallos típicos.