📚 API Documentation & OpenAI Agent Builder Guide

Complete guide for integrating with HeyGen Video Creator

📋 Table of Contents

🚀 Quick Start

🟢 Server Status: Running at http://localhost:4005
📄 Pages: Home | Processing | Gallery

Essential Links

🤖 OpenAI Agent Builder Workflow for Automatic News Videos

💡 Use Case: Create an OpenAI Agent that automatically generates news videos when new articles are found. Perfect for news aggregation, content creation, and automated video production.

Setup Agent Configuration

In OpenAI Agent Builder, configure your agent with these settings:

  • Name: "News Video Creator"
  • Description: "Automatically creates HeyGen videos from news articles"
  • Instructions: "When you receive news content, create a professional video using the HeyGen API. Extract key points, create a script, and generate an engaging video."

Add Custom Function

Add this function schema to your OpenAI Agent:

{
  "name": "create_news_video",
  "description": "Creates a professional news video using HeyGen API",
  "parameters": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "Video title/headline"
      },
      "script": {
        "type": "string",
        "description": "Video script (what the avatar will say)"
      },
      "avatar_id": {
        "type": "string",
        "description": "HeyGen avatar ID",
        "default": "Brandon_Business_Sitting_Front_public"
      },
      "voice_id": {
        "type": "string", 
        "description": "HeyGen voice ID",
        "default": "73c0b6a2e29d4d38aca41454bf58c955"
      },
      "background_color": {
        "type": "string",
        "description": "Background color hex code",
        "default": "#1e3a8a"
      }
    },
    "required": ["title", "script"]
  }
}

Function Implementation

When the agent calls create_news_video, make this HTTP request:

POST http://localhost:4005/api/heygen/generate

Request Headers:

Content-Type: application/json

Request Body:

{
  "video_inputs": [
    {
      "character": {
        "type": "avatar",
        "avatar_id": "{{avatar_id}}",
        "avatar_style": "normal"
      },
      "voice": {
        "type": "text",
        "input_text": "{{script}}",
        "voice_id": "{{voice_id}}"
      },
      "background": {
        "type": "color",
        "value": "{{background_color}}"
      }
    }
  ],
  "dimension": {
    "width": 1280,
    "height": 720
  }
}

Handle Response & Polling

The generate endpoint returns a video_id. Poll for completion:

GET http://localhost:4005/api/heygen/status/{{video_id}}

Poll every 10-15 seconds until status is "completed":

{
  "code": 100,
  "data": {
    "status": "completed",
    "id": "video_id_here"
  }
}

Get Download URL

Once completed, get the video download URL:

GET http://localhost:4005/api/heygen/download/{{video_id}}

Returns:

{
  "data": {
    "url": "https://api.heygen.com/v1/video.download?video_id=..."
  }
}
💡 Pro Tip: Store the video metadata using the local video management endpoints for tracking and organization.

📡 API Endpoints

🎭 Avatar & Voice Management

Method Endpoint Description Response
GET /api/heygen/avatars List available avatars { data: { avatars: [...] } }
GET /api/heygen/voices List available voices { data: { voices: [...] } }

🎬 Video Generation

Method Endpoint Description Response
POST /api/heygen/generate Create new video { data: { video_id: "..." } }
GET /api/heygen/status/:videoId Check video status { data: { status: "processing|completed|failed" } }
GET /api/heygen/download/:videoId Get download URL { data: { url: "https://..." } }

📊 Local Video Management

Method Endpoint Description Purpose
GET /api/videos List all videos Get video history and status
POST /api/videos Create video record Track video metadata locally
PATCH /api/videos/:id Update video record Update status, add download URL
DELETE /api/videos/:id Delete video record Clean up archives

🧪 Testing Endpoints

Method Endpoint Description
POST /api/test/socoa Create test video with "Welcome to SOCOA" message
GET /api/debug/env Check environment configuration

🎬 Video Generation Details

HeyGen v2 Payload Structure

The server accepts the correct HeyGen v2 format with nested objects:

{
  "video_inputs": [
    {
      "character": {
        "type": "avatar",
        "avatar_id": "Brandon_Business_Sitting_Front_public",
        "avatar_style": "normal"
      },
      "voice": {
        "type": "text",
        "input_text": "Your script text here...",
        "voice_id": "73c0b6a2e29d4d38aca41454bf58c955"
      },
      "background": {
        "type": "color",
        "value": "#1e3a8a"
      }
    }
  ],
  "dimension": {
    "width": 1280,
    "height": 720
  }
}

Available Avatar IDs

Popular avatar options (get full list from /api/heygen/avatars):

Available Voice IDs

Popular voice options (get full list from /api/heygen/voices):

📰 News Video Automation Workflow

Complete Automation Pipeline: From news detection to video publication

1. News Detection Trigger

Your OpenAI Agent can be triggered by:

2. Content Processing

Agent should extract and process:

{
  "headline": "Breaking: Major Tech Company Announces AI Breakthrough",
  "summary": "Company XYZ revealed their new AI system...",
  "key_points": [
    "Revolutionary AI technology announced",
    "Expected to impact multiple industries", 
    "Available to public in Q2 2024"
  ],
  "source": "TechNews Today",
  "publish_date": "2024-01-15"
}

3. Script Generation

Transform news content into video script:

Good morning, I'm bringing you the latest tech news. 

[Headline]: Company XYZ has just announced a revolutionary AI breakthrough that could transform multiple industries.

[Key Points]: The new system promises unprecedented capabilities and will be available to the public in Q2 2024.

[Closing]: This is a developing story, and we'll continue to monitor these exciting developments.

Thank you for watching, and stay tuned for more updates.

4. Video Creation Request

Agent makes API call with processed content:

POST /api/videos
{
  "title": "Tech News: AI Breakthrough Announcement",
  "status": "queued",
  "payload": {
    "source": "TechNews Today",
    "headline": "Breaking: Major Tech Company Announces AI Breakthrough",
    "script": "Good morning, I'm bringing you the latest tech news..."
  }
}

POST /api/heygen/generate
{
  "video_inputs": [
    {
      "character": {
        "type": "avatar",
        "avatar_id": "Brandon_Business_Sitting_Front_public",
        "avatar_style": "normal"
      },
      "voice": {
        "type": "text",
        "input_text": "Good morning, I'm bringing you the latest tech news...",
        "voice_id": "73c0b6a2e29d4d38aca41454bf58c955"
      },
      "background": {
        "type": "color",
        "value": "#1e3a8a"
      }
    }
  ],
  "dimension": {
    "width": 1280,
    "height": 720
  }
}

5. Monitoring & Completion

Agent polls for completion and handles the result:

1. Poll /api/heygen/status/{video_id} every 15 seconds
2. When status = "completed", get download URL
3. Update local record with download URL
4. Optionally: Upload to social media, send notifications, etc.
Result: Fully automated news video creation pipeline that can process multiple news sources and generate professional videos without human intervention.

🔧 Troubleshooting

Common Issues

401 Unauthorized
• Check HEYGEN_API_KEY in .env file
• Restart the server after updating API key
• Verify key is valid in HeyGen dashboard
400 Bad Request on Generate
• Ensure payload follows HeyGen v2 structure
• Verify avatar_id and voice_id are valid
• Check that input_text is not empty
No video_id returned
• Check response body for HeyGen error details
• Verify account has sufficient credits
• Ensure avatar and voice IDs exist

Debug Endpoints

OpenAI Agent Debugging

🎯 Quick Test Commands

Test your setup with these curl commands:

Test Avatar List

curl http://localhost:4005/api/heygen/avatars

Test Voice List

curl http://localhost:4005/api/heygen/voices

Test Video Generation

curl -X POST http://localhost:4005/api/test/socoa

Check Environment

curl http://localhost:4005/api/debug/env