Cómo usar Heygen AI a través de la API: Una guía completa

Heygen AI es una plataforma potente que permite a los usuarios crear vídeos realistas de avatares generados por IA de forma programática. Este completo tutorial le guiará a través del proceso de integración y aprovechamiento de la API de Heygen para una variedad de casos de uso, desde vídeos sencillos de avatares hasta la creación de contenido complejo basado en plantillas. Cada sección proporciona instrucciones detalladas paso a paso para ayudarle a dominar las capacidades de Heygen.

💡

¿Está buscando optimizar su flujo de trabajo de desarrollo de API? Apidog destaca como la alternativa definitiva a Postman, ofreciendo un conjunto completo de herramientas para el diseño, la depuración, las pruebas y la documentación de API, todo en una plataforma unificada.

button

Con su interfaz intuitiva, sus funciones de colaboración y sus potentes capacidades de automatización, Apidog reduce significativamente el tiempo de desarrollo al tiempo que mejora la calidad de la API.

button

Tanto si está construyendo una arquitectura de microservicios compleja como si se está integrando con API de terceros como Heygen, los servidores mock de Apidog, las variables de entorno y las amplias opciones de prueba lo convierten en la opción preferida para los desarrolladores que exigen eficiencia y fiabilidad. Pruebe Apidog hoy mismo y experimente la próxima evolución en herramientas de desarrollo de API.

button

Introducción a la API de Heygen

La API de Heygen permite a los desarrolladores crear vídeos de avatares impulsados por IA de forma programática e integrar las capacidades de Heygen en sus aplicaciones. La API ofrece varias funciones, incluyendo la generación de vídeo, la traducción y la creación de contenido basado en plantillas. Siguiendo este tutorial, aprenderá a aprovechar estas capacidades para crear contenido atractivo para marketing, educación, servicio al cliente y más.

La funcionalidad principal de la API gira en torno a la generación de vídeos con avatares de IA realistas que pueden hablar cualquier texto que proporcione o sincronizarse con archivos de audio. Además, puede personalizar los fondos, traducir vídeos a varios idiomas y trabajar con plantillas para producciones más complejas.

Más allá de la simple creación de vídeos básicos, la API de Heygen le permite crear aplicaciones sofisticadas que pueden generar automáticamente contenido personalizado para sus usuarios, crear experiencias interactivas o incluso traducir vídeos existentes a varios idiomas. Esto la hace invaluable para empresas globales, creadores de contenido, educadores y desarrolladores que buscan incorporar vídeo generado por IA en sus productos.

Primeros pasos con la API de Heygen

Creación de una cuenta para la API de Heygen

Siga estos pasos para crear su cuenta de Heygen:

Visite el sitio web oficial de Heygen en heygen website.
Haga clic en el botón "Sign Up" o "Get Started" en la esquina superior derecha
Elija su método de registro preferido (correo electrónico, Google, etc.)
Complete el formulario de registro con sus datos
Acepte los términos y la política de privacidad
Verifique su dirección de correo electrónico si es necesario
Inicie sesión en su nueva cuenta

Después del registro, tendrá acceso tanto a la interfaz web de Heygen como a las capacidades de la API. Los nuevos usuarios suelen recibir una prueba gratuita con funciones limitadas. La prueba gratuita incluye vídeos con marca de agua y cuotas de uso limitadas, pero es suficiente para probar la funcionalidad de la API antes de comprometerse con un plan de pago.

Durante el proceso de registro, Heygen podría preguntar sobre su caso de uso previsto. Proporcionar esta información puede ayudar a Heygen a adaptar las recomendaciones para sus necesidades específicas, aunque no es estrictamente necesario para el acceso a la API.

Obtención de su clave API

Para acceder a la API, siga estos pasos detallados para obtener su clave API:

Inicie sesión en su cuenta de Heygen
Haga clic en su foto de perfil o avatar en la esquina superior derecha
Seleccione "Settings" en el menú desplegable
Navegue a la pestaña "Subscriptions"
Desplácese hacia abajo hasta la sección "HeyGen API"
Haga clic en "Show" junto a "API Token"
Autentíquese si se le solicita
Copie su token API para usarlo en sus solicitudes

Mantenga este token seguro, ya que proporciona acceso completo a la API bajo su cuenta. Nunca lo exponga en código del lado del cliente o repositorios públicos. Si sospecha que su clave API ha sido comprometida, puede generar una nueva desde la misma página de configuración.

Su clave API se utilizará en todas sus solicitudes a la API de Heygen. Normalmente, la incluirá en la cabecera X-Api-Key de sus solicitudes HTTP. Por ejemplo:

X-Api-Key: your-api-key-here

Los diferentes niveles de suscripción ofrecen diferentes límites de uso de la API. La prueba gratuita proporciona acceso básico con vídeos con marca de agua, mientras que los planes de pago (Pro, Scale y Enterprise) ofrecen límites de uso, funciones y opciones de calidad cada vez mayores. Consulte la página de precios de Heygen para obtener la información más actual sobre las funciones y limitaciones del plan.

Creación básica de vídeos de avatares con la API de Heygen

Listado de avatares disponibles con la API de Heygen

Para empezar a crear vídeos, primero necesita saber qué avatares están disponibles. Siga estos pasos:

Abra su terminal o cliente API
Realice la siguiente solicitud:

curl --request GET \\\\
  --url <https://api.heygen.com/v2/avatars> \\\\
  --header 'Accept: application/json' \\\\
  --header 'X-Api-Key: <your-api-key>'

Revise la respuesta, que tendrá el siguiente aspecto:

{
  "error": null,
  "data": {
    "avatars": [
      {
        "avatar_id": "Angela-inblackskirt-20220820",
        "avatar_name": "Angela in Black Dress",
        "gender": "female",
        "preview_image_url": "<preview_image_url>",
        "preview_video_url": "<preview_video_url>"
      },
      // More avatars...
    ]
  }
}

Elija un avatar y anote su avatar_id para su uso posterior

Cada avatar tiene diferentes apariencias y estilos. Algunos avatares están diseñados para contextos específicos como presentaciones de negocios, conversaciones informales o contenido educativo. Previsualice los avatares utilizando las URL proporcionadas para encontrar uno que coincida con su caso de uso previsto.

Si está utilizando Python, puede utilizar este fragmento de código en su lugar:

import requests

headers = {
    'Accept': 'application/json',
    'X-Api-Key': 'your-api-key'
}

response = requests.get('<https://api.heygen.com/v2/avatars>', headers=headers)
avatars = response.json()['data']['avatars']

# Print all available avatars
for avatar in avatars:
    print(f"ID: {avatar['avatar_id']}, Name: {avatar['avatar_name']}")

Los avatares tienen diferentes estilos disponibles, como "normal" o "casual". El estilo predeterminado es "normal", pero puede especificar otros al crear vídeos si el avatar admite varios estilos.

Listado de voces disponibles con la API de Heygen

A continuación, debe seleccionar una voz para su avatar. Siga estos pasos:

Realice la siguiente solicitud API:

curl --request GET \\\\
  --url <https://api.heygen.com/v2/voices> \\\\
  --header 'Accept: application/json' \\\\
  --header 'X-Api-Key: <your-api-key>'

Revise la respuesta para encontrar las voces disponibles:

{
  "error": null,
  "data": {
    "voices": [
      {
        "voice_id": "26b2064088674c80b1e5fc5ab1a068ec",
        "language": "English",
        "gender": "male",
        "name": "Rex",
        "preview_audio": "<https://resource.heygen.ai/text_to_speech/bCo7SFtTvcJz6udLqHmUKf.mp3>",
        "support_pause": false,
        "emotion_support": true,
        "support_interactive_avatar": true
      },
      // More voices...
    ]
  }
}

Elija una voz y anote su voice_id para su uso posterior

Las voces vienen en varios idiomas, acentos y géneros. Escuche el audio de vista previa para encontrar una voz que coincida con el tono y el estilo de su proyecto. Algunas voces admiten funciones adicionales como inflexiones emocionales o pausas, que pueden ser útiles para presentaciones más dinámicas.

Preste atención a la propiedad support_interactive_avatar si planea utilizar avatares interactivos más adelante, ya que no todas las voces admiten esta función.

Equivalente en Python:

response = requests.get('<https://api.heygen.com/v2/voices>', headers=headers)
voices = response.json()['data']['voices']

# Print all available voices
for voice in voices:
    print(f"ID: {voice['voice_id']}, Name: {voice['name']}, Language: {voice['language']}")

# Filter for English voices only
english_voices = [v for v in voices if v['language'] == 'English']
print(f"Found {len(english_voices)} English voices")

Generación de un vídeo de avatar sencillo con la API de Heygen

Ahora que ha seleccionado un avatar y una voz, siga estos pasos para crear un vídeo:

Prepare su carga útil de solicitud con el avatar y la voz elegidos:

{
  "video_inputs": [
    {
      "character": {
        "type": "avatar",
        "avatar_id": "Angela-inTshirt-20220820",
        "avatar_style": "normal"
      },
      "voice": {
        "type": "text",
        "input_text": "Welcome to the HeyGen API! This is a demonstration of how easy it is to create engaging avatar videos programmatically.",
        "voice_id": "1bd001e7e50f421d891986aad5158bc8",
        "speed": 1.1
      },
      "background": {
        "type": "color",
        "value": "#87CEEB"
      }
    }
  ],
  "dimension": {
    "width": 1280,
    "height": 720
  }
}

Envíe la solicitud para generar el vídeo:

curl -X POST <https://api.heygen.com/v2/video/generate> \\\\
-H 'X-Api-Key: <your-api-key>' \\\\
-H 'Content-Type: application/json' \\\\
-d '<your-prepared-json>'

Guarde el video_id de la respuesta:

{
  "error": null,
  "data": {
    "video_id": "abcdef123456"
  }
}

Desglosemos los parámetros de la solicitud:

video_inputs: Una matriz de configuraciones de escena
character: Especifica el avatar a utilizar
type: "avatar" para avatares estándar de Heygen
avatar_id: El ID de su avatar elegido
avatar_style: El estilo visual del avatar (por ejemplo, "normal", "casual")
voice: Configuración para el habla
type: "text" para la conversión de texto a voz
input_text: El guion que dirá el avatar
voice_id: El ID de su voz elegida
speed: Velocidad de habla (1.0 es normal, más alto es más rápido)
background: Configuración de fondo
type: "color" para fondos de color sólido
value: Código de color hexadecimal
dimension: Dimensiones del vídeo de salida
width: Ancho del vídeo en píxeles
height: Altura del vídeo en píxeles

Puede ajustar estos parámetros para personalizar su vídeo. Por ejemplo, cambiar el valor de speed afecta a la rapidez con la que habla el avatar, mientras que dimension controla la resolución del vídeo.

Implementación en Python:

import json
import requests

payload = {
    "video_inputs": [
        {
            "character": {
                "type": "avatar",
                "avatar_id": "Angela-inTshirt-20220820",
                "avatar_style": "normal"
            },
            "voice": {
                "type": "text",
                "input_text": "Welcome to the HeyGen API! This is a demonstration of how easy it is to create engaging avatar videos programmatically.",
                "voice_id": "1bd001e7e50f421d891986aad5158bc8",
                "speed": 1.1
            },
            "background": {
                "type": "color",
                "value": "#87CEEB"
            }
        }
    ],
    "dimension": {
        "width": 1280,
        "height": 720
    }
}

response = requests.post(
    '<https://api.heygen.com/v2/video/generate>',
    headers={
        'X-Api-Key': 'your-api-key',
        'Content-Type': 'application/json'
    },
    data=json.dumps(payload)
)

video_id = response.json()['data']['video_id']
print(f"Video generation initiated! Video ID: {video_id}")

Comprobación del estado de generación de vídeo con la API de Heygen

Después de iniciar la generación de vídeo, siga estos pasos para comprobar su estado:

Utilice el video_id del paso anterior para realizar una solicitud de comprobación de estado:

curl --request GET \\\\
  --url <https://api.heygen.com/v1/video_status.get?video_id=><video_id> \\\\
  --header 'Accept: application/json' \\\\
  --header 'X-Api-Key: <your-api-key>'

Supervise el estado en la respuesta:

{
  "code": 100,
  "data": {
    "id": "<id>",
    "status": "processing",
    "thumbnail_url": null,
    "video_url": null,
    "caption_url": null,
    "gif_url": null,
    "error": null,
    "duration": null,
    "callback_id": null,
    "video_url_caption": null
  },
  "message": "Success"
}

Repita la comprobación hasta que el estado cambie a "completed" o "failed"

La generación de vídeo suele tardar entre 30 segundos y varios minutos, dependiendo de:

Longitud del texto de entrada
Carga del servidor
Complejidad del vídeo
Su nivel de suscripción

Valores de estado que puede encontrar:

pending: Su solicitud ha sido recibida pero el procesamiento aún no ha comenzado
processing: Su vídeo se está generando actualmente
completed: Su vídeo está listo para ser descargado
failed: Hubo un error al generar su vídeo

Cuando un vídeo falla, la respuesta incluirá un mensaje de error explicando el problema:

{
  "code": 100,
  "data": {
    "id": "<id>",
    "status": "failed",
    "error": {
      "code": 40119,
      "message": "Video is too long",
      "detail": "Video is too long (> 3600.0s). Please upgrade your plan to generate longer videos"
    },
    "thumbnail_url": null,
    "video_url": null,
    "caption_url": null,
    "gif_url": null,
    "duration": null,
    "callback_id": null,
    "video_url_caption": null
  },
  "message": "Success"
}

Implementación en Python con sondeo:

import time
import requests

def check_video_status(video_id, api_key):
    headers = {
        'Accept': 'application/json',
        'X-Api-Key': api_key
    }

    max_attempts = 30  # Avoid infinite loops
    attempt = 0

    while attempt < max_attempts:
        response = requests.get(
            f'<https://api.heygen.com/v1/video_status.get?video_id={video_id}>',
            headers=headers
        )

        data = response.json()['data']
        status = data['status']

        if status == 'completed':
            print("Video generation complete!")
            return {
                'video_url': data['video_url'],
                'thumbnail_url': data['thumbnail_url'],
                'duration': data['duration']
            }
        elif status == 'failed':
            error = data['error']
            print(f"Video generation failed: {error}")
            return None
        else:
            print(f"Video status: {status}. Checking again in 5 seconds...")
            attempt += 1
            time.sleep(5)

    print("Maximum attempts reached. Video still not ready.")
    return None

# Usage
result = check_video_status("abcdef123456", "your-api-key")
if result:
    print(f"Video URL: {result['video_url']}")
    print(f"Duration: {result['duration']} seconds")

Descarga de su vídeo generado con la API de Heygen

Una vez que el estado del vídeo sea "completed", siga estos pasos para descargar su vídeo:

Extraiga la video_url de la respuesta de estado
Descargue el vídeo utilizando la URL:

curl <video_url> --output my_avatar_video.mp4

Verifique que el archivo descargado funciona correctamente

Implementación en Python:

import requests

def download_video(video_url, output_filename="my_avatar_video.mp4"):
    response = requests.get(video_url)

    if response.status_code == 200:
        with open(output_filename, 'wb') as file:
            file.write(response.content)

        print(f"Video downloaded successfully to {output_filename}")
        print(f"File size: {len(response.content) / (1024 * 1024):.2f} MB")
        return True
    else:
        print(f"Failed to download video. Status code: {response.status_code}")
        return False

# Usage
success = download_video("<https://storage.googleapis.com/heygen-videos/>...")

Nota importante: La URL del vídeo caduca después de 7 días. Asegúrese de descargar su vídeo antes de que caduque o implemente un sistema para regenerar o volver a recuperar la URL del vídeo según sea necesario.

Para los sistemas de producción, considere:

Configurar un trabajo programado para descargar vídeos rápidamente después de la generación
Almacenar vídeos en su propio almacenamiento en la nube para un acceso a largo plazo
Implementar una base de datos para rastrear los ID de vídeo, las fechas de generación y las fechas de caducidad

API de Heygen: Trabajo con plantillas

Las plantillas ofrecen más flexibilidad que los vídeos de avatares simples, lo que le permite personalizar texto, imágenes, vídeos, audios y avatares dentro de un diseño prediseñado.

Plantillas de la API de Heygen vs. Vídeos de avatares simples

Aquí hay una comparación de las diferencias clave:

Vídeos de avatares:

Se centran únicamente en un avatar hablando
Limitado a una sola escena con un avatar
Opciones de fondo simples
Lo mejor para vídeos sencillos de cabezas parlantes
Creado completamente a través de llamadas API

Vídeos de plantillas:

Múltiples escenas con varios elementos
Marcadores de posición personalizables para texto, imágenes, vídeos, avatares y audio
Transiciones y animaciones complejas
Soporte para múltiples avatares en un solo vídeo
Las plantillas se crean a través de la interfaz web de Heygen
La API se utiliza para generar vídeos basados en plantillas

Las plantillas son particularmente útiles para crear series consistentes de vídeos o generar vídeos personalizados a escala. Por ejemplo, podría crear una plantilla para demostraciones de productos y luego generar versiones personalizadas para diferentes productos cambiando solo el texto, las imágenes y los detalles del producto relevantes.

API de Heygen Creación de plantillas con marcadores de posición

Las plantillas se crean a través de la interfaz web de Heygen:

Inicie sesión en su cuenta de Heygen
Navegue a la sección Plantillas
Haga clic en "Create Template"
Utilice el editor para diseñar su plantilla con estos componentes:

Elementos de texto: Agregue textos que se pueden personalizar más adelante
Escenas de avatar: Agregue avatares que dirán contenido personalizable
Marcadores de posición de imagen: Agregue espacios para imágenes personalizadas
Marcadores de posición de vídeo: Agregue espacios para videoclips personalizados
Elementos de audio: Agregue música de fondo o efectos de sonido

Para cada elemento que desee hacer personalizable, defina un marcador de posición utilizando dobles llaves rizadas:

Ejemplo de texto: {{product_name}}
Ejemplo de guion de avatar: {{product_description}}
Marcador de posición de imagen: Seleccione una imagen y márquela como una variable

Organice los elementos como desee y previsualice la plantilla
Guarde su plantilla con un nombre descriptivo

Por ejemplo, si crea una plantilla de anuncio de producto, podría incluir:

Un texto de apertura con {{company_name}} y {{product_name}}
Un avatar que dice "Estamos emocionados de presentar {{product_name}}, que ofrece {{key_benefit}}"
Una imagen de marcador de posición para {{product_image}}
Música de fondo que se puede reemplazar

Los marcadores de posición pueden ser de diferentes tipos:

Texto: Para reemplazar texto escrito o guiones de avatar
Imagen: Para reemplazar elementos de imagen
Vídeo: Para reemplazar videoclips
Avatar: Para cambiar qué avatar aparece
Voz: Para cambiar la voz utilizada por los avatares
Audio: Para reemplazar música de fondo o efectos de sonido

Listado de sus plantillas con la API de Heygen

Para recuperar todas las plantillas que ha creado:

curl --location '<https://api.heygen.com/v2/templates>' \\\\
  --header 'accept: application/json' \\\\
  --header 'x-api-key: <your-api-key>'

Esto devuelve información sobre todas sus plantillas, incluyendo sus ID y URL de miniaturas:

{
  "error": null,
  "data": {
    "templates": [
      {
        "template_id": "abcdef123456",
        "title": "Product Announcement",
        "thumbnail_url": "<https://storage.googleapis.com/heygen-templates/thumbnails/>...",
        "created_at": "2023-09-15T14:25:30Z"
      },
      {
        "template_id": "ghijkl789012",
        "title": "Weekly Update",
        "thumbnail_url": "<https://storage.googleapis.com/heygen-templates/thumbnails/>...",
        "created_at": "2023-09-18T09:12:45Z"
      }
    ]
  }
}

Implementación en Python:

import requests

headers = {
    'accept': 'application/json',
    'x-api-key': 'your-api-key'
}

response = requests.get('<https://api.heygen.com/v2/templates>', headers=headers)
templates = response.json()['data']['templates']

print(f"Found {len(templates)} templates:")
for template in templates:
    print(f"ID: {template['template_id']}, Title: {template['title']}, Created: {template['created_at']}")

Recuperación de elementos de plantilla con la API de Heygen

Para ver las variables disponibles en una plantilla específica:

curl --location '<https://api.heygen.com/v2/template/><template_id>' \\\\
  --header 'accept: application/json' \\\\
  --header 'x-api-key: <your-api-key>'

Esto muestra todos los elementos personalizables en su plantilla:

{
  "error": null,
  "data": {
    "template_id": "abcdef123456",
    "title": "Product Announcement",
    "variables": {
      "company_name": {
        "name": "company_name",
        "type": "text",
        "properties": {
          "default_content": "Company Name"
        }
      },
      "product_name": {
        "name": "product_name",
        "type": "text",
        "properties": {
          "default_content": "Product Name"
        }
      },
      "key_benefit": {
        "name": "key_benefit",
        "type": "text",
        "properties": {
          "default_content": "amazing benefits to users"
        }
      },
      "product_image": {
        "name": "product_image",
        "type": "image",
        "properties": {
          "default_url": "<https://example.com/default-image.jpg>"
        }
      }
    }
  }
}

Comprender la estructura de las variables de su plantilla es crucial para generar vídeos correctamente. Tenga en cuenta el tipo de cada variable (texto, imagen, vídeo, etc.) y cualquier valor predeterminado proporcionado.

Implementación en Python:

def get_template_details(template_id, api_key):
    headers = {
        'accept': 'application/json',
        'x-api-key': api_key
    }

    response = requests.get(
        f'<https://api.heygen.com/v2/template/{template_id}>',
        headers=headers
    )

    if response.status_code == 200:
        template = response.json()['data']
        variables = template['variables']

        print(f"Template: {template['title']} (ID: {template['template_id']})")
        print("\\\\nVariables:")
        for var_name, var_details in variables.items():
            var_type = var_details['type']
            print(f"- {var_name} ({var_type})")

            if var_type == 'text' and 'default_content' in var_details['properties']:
                print(f"  Default: \\\\"{var_details['properties']['default_content']}\\\\"")
            elif var_type == 'image' and 'default_url' in var_details['properties']:
                print(f"  Default image: {var_details['properties']['default_url']}")

        return variables
    else:
        print(f"Failed to get template details. Status code: {response.status_code}")
        return None

# Usage
template_variables = get_template_details("abcdef123456", "your-api-key")

Generación de vídeos a partir de plantillas con la API de Heygen

Para crear un vídeo utilizando su plantilla:

curl --location '<https://api.heygen.com/v2/template/><template_id>/generate' \\\\
  --header 'X-Api-Key: <your-api-key>' \\\\
  --header 'Content-Type: application/json' \\\\
  --data '{
  "caption": false,
  "title": "Personalized Welcome",
  "variables": {
    "company_name": {
      "name": "company_name",
      "type": "text",
      "properties": {
        "content": "Acme Corporation"
      }
    },
    "product_name": {
      "name": "product_name",
      "type": "text",
      "properties": {
        "content": "Super Widget Pro"
      }
    },
    "key_benefit": {
      "name": "key_benefit",
      "type": "text",
      "properties": {
        "content": "30% faster productivity and seamless integration"
      }
    },
    "product_image": {
      "name": "product_image",
      "type": "image",
      "properties": {
        "url": "<https://example.com/product-image.jpg>"
      }
    }
  }
}'

Esto devuelve un video_id que puede utilizar para comprobar el estado y descargar el vídeo como