@memberjunction/ai-heygen 3.4.0 → 4.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.turbo/turbo-build.log +2 -2
- package/CHANGELOG.md +29 -0
- package/README.md +93 -0
- package/dist/index.d.ts +0 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +16 -22
- package/dist/index.js.map +1 -1
- package/package.json +8 -7
- package/readme.md +58 -339
- package/src/index.ts +0 -4
- package/tsconfig.json +8 -15
package/.turbo/turbo-build.log
CHANGED
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,34 @@
|
|
|
1
1
|
# @memberjunction/ai-heygen
|
|
2
2
|
|
|
3
|
+
## 4.1.0
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- @memberjunction/ai@4.1.0
|
|
8
|
+
- @memberjunction/global@4.1.0
|
|
9
|
+
|
|
10
|
+
## 4.0.0
|
|
11
|
+
|
|
12
|
+
### Major Changes
|
|
13
|
+
|
|
14
|
+
- 8366d44: we goin' to 4.0!
|
|
15
|
+
- fe73344: Angular 21/Node 24/ESM everywhere, and more
|
|
16
|
+
- 5f6306c: 4.0
|
|
17
|
+
|
|
18
|
+
### Minor Changes
|
|
19
|
+
|
|
20
|
+
- e06f81c: changed SO much!
|
|
21
|
+
|
|
22
|
+
### Patch Changes
|
|
23
|
+
|
|
24
|
+
- Updated dependencies [8366d44]
|
|
25
|
+
- Updated dependencies [718b0ee]
|
|
26
|
+
- Updated dependencies [fe73344]
|
|
27
|
+
- Updated dependencies [5f6306c]
|
|
28
|
+
- Updated dependencies [e06f81c]
|
|
29
|
+
- @memberjunction/ai@4.0.0
|
|
30
|
+
- @memberjunction/global@4.0.0
|
|
31
|
+
|
|
3
32
|
## 3.4.0
|
|
4
33
|
|
|
5
34
|
### Patch Changes
|
package/README.md
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# @memberjunction/ai-heygen
|
|
2
|
+
|
|
3
|
+
MemberJunction AI provider for HeyGen's AI video generation platform. This package implements the `BaseVideoGenerator` interface to create avatar-based videos with customizable characters, voices, and backgrounds.
|
|
4
|
+
|
|
5
|
+
## Architecture
|
|
6
|
+
|
|
7
|
+
```mermaid
|
|
8
|
+
graph TD
|
|
9
|
+
A["HeyGenVideoGenerator<br/>(Provider)"] -->|extends| B["BaseVideoGenerator<br/>(@memberjunction/ai)"]
|
|
10
|
+
A -->|uses| C["Axios HTTP Client"]
|
|
11
|
+
A -->|calls| D["HeyGen Video API<br/>(api.heygen.com/v2)"]
|
|
12
|
+
D -->|generates| E["Avatar Videos"]
|
|
13
|
+
A -->|queries| F["HeyGen Avatars API"]
|
|
14
|
+
F -->|returns| G["Available Avatars"]
|
|
15
|
+
B -->|registered via| H["@RegisterClass"]
|
|
16
|
+
|
|
17
|
+
style A fill:#7c5295,stroke:#563a6b,color:#fff
|
|
18
|
+
style B fill:#2d6a9f,stroke:#1a4971,color:#fff
|
|
19
|
+
style C fill:#2d8659,stroke:#1a5c3a,color:#fff
|
|
20
|
+
style D fill:#2d8659,stroke:#1a5c3a,color:#fff
|
|
21
|
+
style E fill:#b8762f,stroke:#8a5722,color:#fff
|
|
22
|
+
style F fill:#2d8659,stroke:#1a5c3a,color:#fff
|
|
23
|
+
style G fill:#b8762f,stroke:#8a5722,color:#fff
|
|
24
|
+
style H fill:#b8762f,stroke:#8a5722,color:#fff
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Features
|
|
28
|
+
|
|
29
|
+
- **Avatar Video Generation**: Create videos with AI avatars synchronized to audio
|
|
30
|
+
- **Avatar Management**: Browse available avatars with preview images and videos
|
|
31
|
+
- **Customizable Layout**: Control avatar scale, position (offset X/Y), and style
|
|
32
|
+
- **Custom Backgrounds**: Use image assets as video backgrounds
|
|
33
|
+
- **Audio Integration**: Sync avatar lip movements with audio assets
|
|
34
|
+
- **Resolution Control**: Set custom output width and height
|
|
35
|
+
|
|
36
|
+
## Installation
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npm install @memberjunction/ai-heygen
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Usage
|
|
43
|
+
|
|
44
|
+
### Create Avatar Video
|
|
45
|
+
|
|
46
|
+
```typescript
|
|
47
|
+
import { HeyGenVideoGenerator } from '@memberjunction/ai-heygen';
|
|
48
|
+
|
|
49
|
+
const generator = new HeyGenVideoGenerator('your-heygen-api-key');
|
|
50
|
+
|
|
51
|
+
const result = await generator.CreateAvatarVideo({
|
|
52
|
+
avatarId: 'avatar-id',
|
|
53
|
+
avatarStyle: 'normal',
|
|
54
|
+
scale: 1.0,
|
|
55
|
+
offsetX: 0,
|
|
56
|
+
offsetY: 0,
|
|
57
|
+
audioAssetId: 'audio-asset-id',
|
|
58
|
+
imageAssetId: 'background-asset-id',
|
|
59
|
+
outputWidth: 1920,
|
|
60
|
+
outputHeight: 1080
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
if (result.success) {
|
|
64
|
+
console.log('Video ID:', result.videoId);
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### List Avatars
|
|
69
|
+
|
|
70
|
+
```typescript
|
|
71
|
+
const avatars = await generator.GetAvatars();
|
|
72
|
+
for (const avatar of avatars) {
|
|
73
|
+
console.log(`${avatar.name} (${avatar.gender}): ${avatar.previewImageUrl}`);
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Supported Methods
|
|
78
|
+
|
|
79
|
+
| Method | Description |
|
|
80
|
+
|--------|-------------|
|
|
81
|
+
| `CreateAvatarVideo` | Generate an avatar video with audio and background |
|
|
82
|
+
| `GetAvatars` | List available avatars with preview media |
|
|
83
|
+
| `CreateVideoTranslation` | Translate existing video (not yet implemented) |
|
|
84
|
+
|
|
85
|
+
## Class Registration
|
|
86
|
+
|
|
87
|
+
Registered as `HeyGenVideoGenerator` via `@RegisterClass(BaseVideoGenerator, 'HeyGenVideoGenerator')`.
|
|
88
|
+
|
|
89
|
+
## Dependencies
|
|
90
|
+
|
|
91
|
+
- `@memberjunction/ai` - Core AI abstractions (BaseVideoGenerator)
|
|
92
|
+
- `@memberjunction/global` - Class registration
|
|
93
|
+
- `axios` - HTTP client for API communication
|
package/dist/index.d.ts
CHANGED
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,WAAW,EAAiB,MAAM,oBAAoB,CAAC;AAGnH,qBACa,oBAAqB,SAAQ,kBAAkB;IACxD,OAAO,CAAC,YAAY,CAAsD;IAC1E,OAAO,CAAC,WAAW,CAA+C;gBAEtD,MAAM,EAAE,MAAM;IAIb,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IA6ClE,sBAAsB,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,WAAW,CAAC;IAIzD,UAAU,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAsBnC,mBAAmB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAGxD
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,WAAW,EAAiB,MAAM,oBAAoB,CAAC;AAGnH,qBACa,oBAAqB,SAAQ,kBAAkB;IACxD,OAAO,CAAC,YAAY,CAAsD;IAC1E,OAAO,CAAC,WAAW,CAA+C;gBAEtD,MAAM,EAAE,MAAM;IAIb,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IA6ClE,sBAAsB,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,WAAW,CAAC;IAIzD,UAAU,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAsBnC,mBAAmB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAGxD"}
|
package/dist/index.js
CHANGED
|
@@ -1,28 +1,25 @@
|
|
|
1
|
-
"use strict";
|
|
2
1
|
var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
|
|
3
2
|
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
4
3
|
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
|
|
5
4
|
else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
|
|
6
5
|
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
7
6
|
};
|
|
8
|
-
var
|
|
9
|
-
|
|
7
|
+
var __metadata = (this && this.__metadata) || function (k, v) {
|
|
8
|
+
if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
|
|
10
9
|
};
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
const axios_1 = __importDefault(require("axios"));
|
|
16
|
-
let HeyGenVideoGenerator = class HeyGenVideoGenerator extends ai_1.BaseVideoGenerator {
|
|
10
|
+
import { RegisterClass } from "@memberjunction/global";
|
|
11
|
+
import { AvatarInfo, BaseVideoGenerator, VideoResult, ErrorAnalyzer } from "@memberjunction/ai";
|
|
12
|
+
import axios from "axios";
|
|
13
|
+
let HeyGenVideoGenerator = class HeyGenVideoGenerator extends BaseVideoGenerator {
|
|
17
14
|
constructor(apiKey) {
|
|
18
15
|
super(apiKey);
|
|
19
16
|
this._generateUrl = "https://api.heygen.com/v2/video/generate";
|
|
20
17
|
this._avatarsUrl = "https://api.heygen.com/v2/avatars";
|
|
21
18
|
}
|
|
22
19
|
async CreateAvatarVideo(params) {
|
|
23
|
-
const videoResult = new
|
|
20
|
+
const videoResult = new VideoResult();
|
|
24
21
|
try {
|
|
25
|
-
const response = await
|
|
22
|
+
const response = await axios.post(this._generateUrl, {
|
|
26
23
|
video_inputs: [
|
|
27
24
|
{
|
|
28
25
|
character: {
|
|
@@ -53,7 +50,7 @@ let HeyGenVideoGenerator = class HeyGenVideoGenerator extends ai_1.BaseVideoGene
|
|
|
53
50
|
videoResult.success = true;
|
|
54
51
|
}
|
|
55
52
|
catch (error) {
|
|
56
|
-
const errorInfo =
|
|
53
|
+
const errorInfo = ErrorAnalyzer.analyzeError(error, 'HeyGen');
|
|
57
54
|
videoResult.success = false;
|
|
58
55
|
videoResult.errorMessage = error?.message || 'Unknown error occurred';
|
|
59
56
|
console.error('HeyGen CreateAvatarVideo error:', error, errorInfo);
|
|
@@ -66,11 +63,11 @@ let HeyGenVideoGenerator = class HeyGenVideoGenerator extends ai_1.BaseVideoGene
|
|
|
66
63
|
async GetAvatars() {
|
|
67
64
|
const result = [];
|
|
68
65
|
try {
|
|
69
|
-
const response = await
|
|
66
|
+
const response = await axios.get(this._avatarsUrl, {
|
|
70
67
|
headers: { Accept: 'application/json', 'X-Api-Key': this.apiKey }
|
|
71
68
|
});
|
|
72
69
|
for (const avatar of response.data.data.avatars) {
|
|
73
|
-
const avatarInfo = new
|
|
70
|
+
const avatarInfo = new AvatarInfo();
|
|
74
71
|
avatarInfo.id = avatar.avatar_id;
|
|
75
72
|
avatarInfo.name = avatar.avatar_name;
|
|
76
73
|
avatarInfo.gender = avatar.gender;
|
|
@@ -80,7 +77,7 @@ let HeyGenVideoGenerator = class HeyGenVideoGenerator extends ai_1.BaseVideoGene
|
|
|
80
77
|
}
|
|
81
78
|
}
|
|
82
79
|
catch (error) {
|
|
83
|
-
const errorInfo =
|
|
80
|
+
const errorInfo = ErrorAnalyzer.analyzeError(error, 'HeyGen');
|
|
84
81
|
console.error('HeyGen GetAvatars error:', errorInfo);
|
|
85
82
|
}
|
|
86
83
|
return result;
|
|
@@ -89,12 +86,9 @@ let HeyGenVideoGenerator = class HeyGenVideoGenerator extends ai_1.BaseVideoGene
|
|
|
89
86
|
return ["CreateAvatarVideo", "CreateVideoTranslation", "GetAvatars"];
|
|
90
87
|
}
|
|
91
88
|
};
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
(
|
|
89
|
+
HeyGenVideoGenerator = __decorate([
|
|
90
|
+
RegisterClass(BaseVideoGenerator, "HeyGenVideoGenerator"),
|
|
91
|
+
__metadata("design:paramtypes", [String])
|
|
95
92
|
], HeyGenVideoGenerator);
|
|
96
|
-
|
|
97
|
-
// does nothing, avoid tree shaking that will get rid of this class since there is no static link to this class in the code base as it is loaded dynamically
|
|
98
|
-
}
|
|
99
|
-
exports.LoadHeyGenVideoGenerator = LoadHeyGenVideoGenerator;
|
|
93
|
+
export { HeyGenVideoGenerator };
|
|
100
94
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,24 +1,25 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@memberjunction/ai-heygen",
|
|
3
|
-
"
|
|
3
|
+
"type": "module",
|
|
4
|
+
"version": "4.1.0",
|
|
4
5
|
"description": "MemberJunction Wrapper for HeyGen Video Generation",
|
|
5
6
|
"main": "dist/index.js",
|
|
6
7
|
"scripts": {
|
|
7
8
|
"start": "ts-node-dev src/index.ts",
|
|
8
|
-
"build": "tsc",
|
|
9
|
+
"build": "tsc && tsc-alias -f",
|
|
9
10
|
"test": "echo \"Error: no test specified\" && exit 1"
|
|
10
11
|
},
|
|
11
12
|
"author": "MemberJunction.com",
|
|
12
13
|
"license": "ISC",
|
|
13
14
|
"devDependencies": {
|
|
14
15
|
"ts-node-dev": "^2.0.0",
|
|
15
|
-
"typescript": "^5.
|
|
16
|
+
"typescript": "^5.9.3"
|
|
16
17
|
},
|
|
17
18
|
"dependencies": {
|
|
18
|
-
"@memberjunction/ai": "
|
|
19
|
-
"@memberjunction/global": "
|
|
20
|
-
"axios": "^1.
|
|
21
|
-
"@elevenlabs/elevenlabs-js": "^2.
|
|
19
|
+
"@memberjunction/ai": "4.1.0",
|
|
20
|
+
"@memberjunction/global": "4.1.0",
|
|
21
|
+
"axios": "^1.13.4",
|
|
22
|
+
"@elevenlabs/elevenlabs-js": "^2.34.0"
|
|
22
23
|
},
|
|
23
24
|
"repository": {
|
|
24
25
|
"type": "git",
|
package/readme.md
CHANGED
|
@@ -1,24 +1,37 @@
|
|
|
1
1
|
# @memberjunction/ai-heygen
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
3
|
+
MemberJunction AI provider for HeyGen's AI video generation platform. This package implements the `BaseVideoGenerator` interface to create avatar-based videos with customizable characters, voices, and backgrounds.
|
|
4
|
+
|
|
5
|
+
## Architecture
|
|
6
|
+
|
|
7
|
+
```mermaid
|
|
8
|
+
graph TD
|
|
9
|
+
A["HeyGenVideoGenerator<br/>(Provider)"] -->|extends| B["BaseVideoGenerator<br/>(@memberjunction/ai)"]
|
|
10
|
+
A -->|uses| C["Axios HTTP Client"]
|
|
11
|
+
A -->|calls| D["HeyGen Video API<br/>(api.heygen.com/v2)"]
|
|
12
|
+
D -->|generates| E["Avatar Videos"]
|
|
13
|
+
A -->|queries| F["HeyGen Avatars API"]
|
|
14
|
+
F -->|returns| G["Available Avatars"]
|
|
15
|
+
B -->|registered via| H["@RegisterClass"]
|
|
16
|
+
|
|
17
|
+
style A fill:#7c5295,stroke:#563a6b,color:#fff
|
|
18
|
+
style B fill:#2d6a9f,stroke:#1a4971,color:#fff
|
|
19
|
+
style C fill:#2d8659,stroke:#1a5c3a,color:#fff
|
|
20
|
+
style D fill:#2d8659,stroke:#1a5c3a,color:#fff
|
|
21
|
+
style E fill:#b8762f,stroke:#8a5722,color:#fff
|
|
22
|
+
style F fill:#2d8659,stroke:#1a5c3a,color:#fff
|
|
23
|
+
style G fill:#b8762f,stroke:#8a5722,color:#fff
|
|
24
|
+
style H fill:#b8762f,stroke:#8a5722,color:#fff
|
|
25
|
+
```
|
|
12
26
|
|
|
13
27
|
## Features
|
|
14
28
|
|
|
15
|
-
- **Avatar Video Generation**: Create videos with AI
|
|
16
|
-
- **Avatar Management**:
|
|
17
|
-
- **
|
|
18
|
-
- **
|
|
19
|
-
- **
|
|
20
|
-
- **
|
|
21
|
-
- **Type-Safe Implementation**: Full TypeScript support with proper typing throughout
|
|
29
|
+
- **Avatar Video Generation**: Create videos with AI avatars synchronized to audio
|
|
30
|
+
- **Avatar Management**: Browse available avatars with preview images and videos
|
|
31
|
+
- **Customizable Layout**: Control avatar scale, position (offset X/Y), and style
|
|
32
|
+
- **Custom Backgrounds**: Use image assets as video backgrounds
|
|
33
|
+
- **Audio Integration**: Sync avatar lip movements with audio assets
|
|
34
|
+
- **Resolution Control**: Set custom output width and height
|
|
22
35
|
|
|
23
36
|
## Installation
|
|
24
37
|
|
|
@@ -26,349 +39,55 @@ The HeyGen provider enables you to:
|
|
|
26
39
|
npm install @memberjunction/ai-heygen
|
|
27
40
|
```
|
|
28
41
|
|
|
29
|
-
## Requirements
|
|
30
|
-
|
|
31
|
-
- Node.js 16 or higher
|
|
32
|
-
- TypeScript 5.4.5 or higher
|
|
33
|
-
- A valid HeyGen API key (obtain from [HeyGen Dashboard](https://app.heygen.com/))
|
|
34
|
-
- MemberJunction Core dependencies:
|
|
35
|
-
- `@memberjunction/ai` (same version)
|
|
36
|
-
- `@memberjunction/global` (same version)
|
|
37
|
-
|
|
38
|
-
## Configuration
|
|
39
|
-
|
|
40
|
-
Before using the HeyGen provider, ensure you have:
|
|
41
|
-
|
|
42
|
-
1. A valid HeyGen API key from your [HeyGen account](https://app.heygen.com/)
|
|
43
|
-
2. Pre-uploaded audio and image assets in your HeyGen account (these will provide you with asset IDs)
|
|
44
|
-
3. Selected an avatar ID from the available options
|
|
45
|
-
|
|
46
42
|
## Usage
|
|
47
43
|
|
|
48
|
-
###
|
|
44
|
+
### Create Avatar Video
|
|
49
45
|
|
|
50
46
|
```typescript
|
|
51
47
|
import { HeyGenVideoGenerator } from '@memberjunction/ai-heygen';
|
|
52
48
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
avatars.forEach(avatar => {
|
|
66
|
-
console.log(`Avatar: ${avatar.name} (ID: ${avatar.id})`);
|
|
67
|
-
console.log(`Gender: ${avatar.gender}`);
|
|
68
|
-
console.log(`Preview Image: ${avatar.previewImageUrl}`);
|
|
69
|
-
console.log(`Preview Video: ${avatar.previewVideoUrl}`);
|
|
70
|
-
console.log('---');
|
|
49
|
+
const generator = new HeyGenVideoGenerator('your-heygen-api-key');
|
|
50
|
+
|
|
51
|
+
const result = await generator.CreateAvatarVideo({
|
|
52
|
+
avatarId: 'avatar-id',
|
|
53
|
+
avatarStyle: 'normal',
|
|
54
|
+
scale: 1.0,
|
|
55
|
+
offsetX: 0,
|
|
56
|
+
offsetY: 0,
|
|
57
|
+
audioAssetId: 'audio-asset-id',
|
|
58
|
+
imageAssetId: 'background-asset-id',
|
|
59
|
+
outputWidth: 1920,
|
|
60
|
+
outputHeight: 1080
|
|
71
61
|
});
|
|
72
62
|
|
|
73
|
-
// Find a specific avatar by name
|
|
74
|
-
const femaleAvatar = avatars.find(a => a.gender === 'female' && a.name.includes('Professional'));
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
### Create an Avatar Video
|
|
78
|
-
|
|
79
|
-
Generate a video with an avatar speaking your content:
|
|
80
|
-
|
|
81
|
-
```typescript
|
|
82
|
-
import { AvatarVideoParams, VideoResult } from '@memberjunction/ai';
|
|
83
|
-
|
|
84
|
-
// Configure video parameters
|
|
85
|
-
const videoParams: AvatarVideoParams = {
|
|
86
|
-
avatarId: 'avatar-id-from-getavatars', // Use an ID from GetAvatars()
|
|
87
|
-
audioAssetId: 'your-audio-asset-id', // Pre-uploaded audio asset ID from HeyGen
|
|
88
|
-
imageAssetId: 'your-background-image-id', // Pre-uploaded background image ID
|
|
89
|
-
outputWidth: 1280, // Video width in pixels
|
|
90
|
-
outputHeight: 720, // Video height in pixels
|
|
91
|
-
scale: 1.0, // Avatar scale (1.0 = 100%)
|
|
92
|
-
avatarStyle: 'normal', // Avatar presentation style
|
|
93
|
-
offsetX: 0, // Horizontal position offset
|
|
94
|
-
offsetY: 0 // Vertical position offset
|
|
95
|
-
};
|
|
96
|
-
|
|
97
|
-
// Generate the video
|
|
98
|
-
const result: VideoResult = await heyGen.CreateAvatarVideo(videoParams);
|
|
99
|
-
|
|
100
63
|
if (result.success) {
|
|
101
|
-
|
|
102
|
-
console.log('Video ID:', result.videoId);
|
|
103
|
-
// The video ID can be used to check status or download via HeyGen's API
|
|
104
|
-
} else {
|
|
105
|
-
console.error('Error generating video:', result.errorMessage);
|
|
106
|
-
}
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
### Complete Example
|
|
110
|
-
|
|
111
|
-
Here's a complete example that demonstrates the full workflow:
|
|
112
|
-
|
|
113
|
-
```typescript
|
|
114
|
-
import { HeyGenVideoGenerator } from '@memberjunction/ai-heygen';
|
|
115
|
-
import { AvatarVideoParams, VideoResult } from '@memberjunction/ai';
|
|
116
|
-
|
|
117
|
-
async function createProfessionalVideo() {
|
|
118
|
-
try {
|
|
119
|
-
// Initialize the HeyGen client
|
|
120
|
-
const heyGen = new HeyGenVideoGenerator(process.env.HEYGEN_API_KEY);
|
|
121
|
-
|
|
122
|
-
// Get available avatars
|
|
123
|
-
const avatars = await heyGen.GetAvatars();
|
|
124
|
-
console.log(`Found ${avatars.length} available avatars`);
|
|
125
|
-
|
|
126
|
-
// Select the first professional avatar
|
|
127
|
-
const professionalAvatar = avatars.find(a =>
|
|
128
|
-
a.name.toLowerCase().includes('professional')
|
|
129
|
-
) || avatars[0];
|
|
130
|
-
|
|
131
|
-
console.log(`Using avatar: ${professionalAvatar.name}`);
|
|
132
|
-
|
|
133
|
-
// Create video with the selected avatar
|
|
134
|
-
const videoParams: AvatarVideoParams = {
|
|
135
|
-
avatarId: professionalAvatar.id,
|
|
136
|
-
audioAssetId: 'audio_asset_123', // Your pre-uploaded audio
|
|
137
|
-
imageAssetId: 'image_asset_456', // Your pre-uploaded background
|
|
138
|
-
outputWidth: 1920,
|
|
139
|
-
outputHeight: 1080,
|
|
140
|
-
scale: 1.2, // Slightly larger avatar
|
|
141
|
-
avatarStyle: 'normal',
|
|
142
|
-
offsetX: 100, // Move avatar 100px to the right
|
|
143
|
-
offsetY: 0
|
|
144
|
-
};
|
|
145
|
-
|
|
146
|
-
const result: VideoResult = await heyGen.CreateAvatarVideo(videoParams);
|
|
147
|
-
|
|
148
|
-
if (result.success) {
|
|
149
|
-
console.log(`Video created successfully! ID: ${result.videoId}`);
|
|
150
|
-
// Use the video ID to check status or download the video
|
|
151
|
-
} else {
|
|
152
|
-
console.error(`Failed to create video: ${result.errorMessage}`);
|
|
153
|
-
}
|
|
154
|
-
|
|
155
|
-
} catch (error) {
|
|
156
|
-
console.error('Unexpected error:', error);
|
|
157
|
-
}
|
|
158
|
-
}
|
|
159
|
-
|
|
160
|
-
// Run the example
|
|
161
|
-
createProfessionalVideo();
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
### Check Supported Methods
|
|
165
|
-
|
|
166
|
-
Check which methods are supported by the current implementation:
|
|
167
|
-
|
|
168
|
-
```typescript
|
|
169
|
-
const supportedMethods = await heyGen.GetSupportedMethods();
|
|
170
|
-
console.log('Supported methods:', supportedMethods);
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
## API Reference
|
|
174
|
-
|
|
175
|
-
### HeyGenVideoGenerator Class
|
|
176
|
-
|
|
177
|
-
The main class that extends `BaseVideoGenerator` to provide HeyGen-specific video generation functionality. This class is registered with MemberJunction's global class registry using the `@RegisterClass` decorator.
|
|
178
|
-
|
|
179
|
-
#### Constructor
|
|
180
|
-
|
|
181
|
-
```typescript
|
|
182
|
-
constructor(apiKey: string)
|
|
183
|
-
```
|
|
184
|
-
|
|
185
|
-
**Parameters:**
|
|
186
|
-
- `apiKey` - Your HeyGen API key for authentication
|
|
187
|
-
|
|
188
|
-
#### Methods
|
|
189
|
-
|
|
190
|
-
##### `CreateAvatarVideo(params: AvatarVideoParams): Promise<VideoResult>`
|
|
191
|
-
Generates a video with an AI avatar speaking the provided audio content.
|
|
192
|
-
|
|
193
|
-
**Parameters:**
|
|
194
|
-
- `params` - Configuration object for the avatar video (see AvatarVideoParams below)
|
|
195
|
-
|
|
196
|
-
**Returns:**
|
|
197
|
-
- `Promise<VideoResult>` - Result object containing success status and video ID or error message
|
|
198
|
-
|
|
199
|
-
##### `GetAvatars(): Promise<AvatarInfo[]>`
|
|
200
|
-
Retrieves a list of all available avatars from HeyGen.
|
|
201
|
-
|
|
202
|
-
**Returns:**
|
|
203
|
-
- `Promise<AvatarInfo[]>` - Array of avatar information objects
|
|
204
|
-
|
|
205
|
-
##### `GetSupportedMethods(): Promise<string[]>`
|
|
206
|
-
Returns a list of method names supported by this implementation.
|
|
207
|
-
|
|
208
|
-
**Returns:**
|
|
209
|
-
- `Promise<string[]>` - Array of supported method names
|
|
210
|
-
|
|
211
|
-
##### `CreateVideoTranslation(params: any): Promise<VideoResult>`
|
|
212
|
-
**Note:** This method is not yet implemented and will throw an error if called.
|
|
213
|
-
|
|
214
|
-
### Type Definitions
|
|
215
|
-
|
|
216
|
-
#### AvatarVideoParams
|
|
217
|
-
|
|
218
|
-
Configuration parameters for creating an avatar video:
|
|
219
|
-
|
|
220
|
-
```typescript
|
|
221
|
-
interface AvatarVideoParams {
|
|
222
|
-
avatarId: string; // ID of the avatar (from GetAvatars)
|
|
223
|
-
audioAssetId: string; // ID of pre-uploaded audio asset
|
|
224
|
-
imageAssetId: string; // ID of pre-uploaded background image
|
|
225
|
-
outputWidth: number; // Video width in pixels
|
|
226
|
-
outputHeight: number; // Video height in pixels
|
|
227
|
-
scale: number; // Avatar scale factor (1.0 = 100%)
|
|
228
|
-
avatarStyle: string; // Avatar style (e.g., 'normal')
|
|
229
|
-
offsetX: number; // Horizontal position offset in pixels
|
|
230
|
-
offsetY: number; // Vertical position offset in pixels
|
|
231
|
-
}
|
|
232
|
-
```
|
|
233
|
-
|
|
234
|
-
#### VideoResult
|
|
235
|
-
|
|
236
|
-
Result object returned from video generation operations:
|
|
237
|
-
|
|
238
|
-
```typescript
|
|
239
|
-
interface VideoResult {
|
|
240
|
-
success: boolean; // Whether the operation succeeded
|
|
241
|
-
videoId?: string; // ID of the generated video (if successful)
|
|
242
|
-
errorMessage?: string; // Error details (if unsuccessful)
|
|
64
|
+
console.log('Video ID:', result.videoId);
|
|
243
65
|
}
|
|
244
66
|
```
|
|
245
67
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
Information about an available avatar:
|
|
68
|
+
### List Avatars
|
|
249
69
|
|
|
250
70
|
```typescript
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
gender: string; // Avatar's gender
|
|
255
|
-
previewImageUrl: string; // URL to avatar preview image
|
|
256
|
-
previewVideoUrl: string; // URL to avatar preview video
|
|
71
|
+
const avatars = await generator.GetAvatars();
|
|
72
|
+
for (const avatar of avatars) {
|
|
73
|
+
console.log(`${avatar.name} (${avatar.gender}): ${avatar.previewImageUrl}`);
|
|
257
74
|
}
|
|
258
75
|
```
|
|
259
76
|
|
|
260
|
-
##
|
|
261
|
-
|
|
262
|
-
### HeyGen API Endpoints
|
|
263
|
-
|
|
264
|
-
This package integrates with the following HeyGen API v2 endpoints:
|
|
77
|
+
## Supported Methods
|
|
265
78
|
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
- Used by `GetAvatars()` method
|
|
272
|
-
- Returns available avatars with preview assets
|
|
79
|
+
| Method | Description |
|
|
80
|
+
|--------|-------------|
|
|
81
|
+
| `CreateAvatarVideo` | Generate an avatar video with audio and background |
|
|
82
|
+
| `GetAvatars` | List available avatars with preview media |
|
|
83
|
+
| `CreateVideoTranslation` | Translate existing video (not yet implemented) |
|
|
273
84
|
|
|
274
|
-
|
|
85
|
+
## Class Registration
|
|
275
86
|
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
### Error Handling
|
|
279
|
-
|
|
280
|
-
The package implements comprehensive error handling:
|
|
281
|
-
- Network errors are caught and logged
|
|
282
|
-
- API errors are returned in the `VideoResult.errorMessage` field
|
|
283
|
-
- All methods return predictable result objects rather than throwing exceptions
|
|
87
|
+
Registered as `HeyGenVideoGenerator` via `@RegisterClass(BaseVideoGenerator, 'HeyGenVideoGenerator')`.
|
|
284
88
|
|
|
285
89
|
## Dependencies
|
|
286
90
|
|
|
287
|
-
|
|
288
|
-
- `@memberjunction/
|
|
289
|
-
-
|
|
290
|
-
- `axios` - HTTP client for API communication (Note: This needs to be added to package.json)
|
|
291
|
-
|
|
292
|
-
### Development Dependencies
|
|
293
|
-
- `typescript` ^5.4.5 - TypeScript compiler
|
|
294
|
-
- `ts-node-dev` ^2.0.0 - Development server with auto-reload
|
|
295
|
-
|
|
296
|
-
## Build and Development
|
|
297
|
-
|
|
298
|
-
### Building the Package
|
|
299
|
-
|
|
300
|
-
```bash
|
|
301
|
-
# From the package directory
|
|
302
|
-
npm run build
|
|
303
|
-
|
|
304
|
-
# From the repository root
|
|
305
|
-
npm run build -- --filter="@memberjunction/ai-heygen"
|
|
306
|
-
```
|
|
307
|
-
|
|
308
|
-
### Development Mode
|
|
309
|
-
|
|
310
|
-
```bash
|
|
311
|
-
# Run in watch mode with auto-reload
|
|
312
|
-
npm run start
|
|
313
|
-
```
|
|
314
|
-
|
|
315
|
-
### Package Structure
|
|
316
|
-
|
|
317
|
-
```
|
|
318
|
-
packages/AI/Providers/HeyGen/
|
|
319
|
-
├── src/
|
|
320
|
-
│ └── index.ts # Main implementation file
|
|
321
|
-
├── dist/ # Compiled JavaScript output
|
|
322
|
-
├── package.json # Package configuration
|
|
323
|
-
├── tsconfig.json # TypeScript configuration
|
|
324
|
-
├── typedoc.json # Documentation generation config
|
|
325
|
-
└── readme.md # This file
|
|
326
|
-
```
|
|
327
|
-
|
|
328
|
-
## Integration with MemberJunction
|
|
329
|
-
|
|
330
|
-
This package follows MemberJunction's architectural patterns:
|
|
331
|
-
|
|
332
|
-
1. **Class Registration**: Uses `@RegisterClass` decorator for automatic registration with the global class registry
|
|
333
|
-
2. **Abstract Implementation**: Extends `BaseVideoGenerator` from `@memberjunction/ai`
|
|
334
|
-
3. **Consistent API**: Follows MemberJunction's standardized patterns for AI providers
|
|
335
|
-
4. **Type Safety**: Full TypeScript implementation with proper typing
|
|
336
|
-
|
|
337
|
-
### Using with MemberJunction's AI System
|
|
338
|
-
|
|
339
|
-
The HeyGen provider can be dynamically loaded through MemberJunction's AI provider system:
|
|
340
|
-
|
|
341
|
-
```typescript
|
|
342
|
-
import { AIEngine } from '@memberjunction/ai';
|
|
343
|
-
|
|
344
|
-
// The HeyGen provider will be automatically available if installed
|
|
345
|
-
const aiEngine = new AIEngine();
|
|
346
|
-
const videoGenerator = await aiEngine.GetVideoGenerator('HeyGenVideoGenerator', apiKey);
|
|
347
|
-
```
|
|
348
|
-
|
|
349
|
-
## Contributing
|
|
350
|
-
|
|
351
|
-
When contributing to this package:
|
|
352
|
-
|
|
353
|
-
1. Follow the MemberJunction code style guide
|
|
354
|
-
2. Ensure all TypeScript compiles without errors
|
|
355
|
-
3. Update this README if adding new features
|
|
356
|
-
4. Add appropriate error handling for all API calls
|
|
357
|
-
5. Maintain backward compatibility
|
|
358
|
-
|
|
359
|
-
## Known Limitations
|
|
360
|
-
|
|
361
|
-
1. `CreateVideoTranslation()` is not yet implemented
|
|
362
|
-
2. Requires pre-uploaded assets (audio and images) in HeyGen
|
|
363
|
-
3. No webhook support for video completion notifications
|
|
364
|
-
4. The package.json is missing the `axios` dependency (needs to be added)
|
|
365
|
-
|
|
366
|
-
## Additional Resources
|
|
367
|
-
|
|
368
|
-
- [HeyGen API Documentation](https://docs.heygen.com/)
|
|
369
|
-
- [HeyGen Dashboard](https://app.heygen.com/)
|
|
370
|
-
- [MemberJunction AI Documentation](https://docs.memberjunction.org/ai)
|
|
371
|
-
|
|
372
|
-
## License
|
|
373
|
-
|
|
374
|
-
ISC - See LICENSE file in the repository root for details.
|
|
91
|
+
- `@memberjunction/ai` - Core AI abstractions (BaseVideoGenerator)
|
|
92
|
+
- `@memberjunction/global` - Class registration
|
|
93
|
+
- `axios` - HTTP client for API communication
|
package/src/index.ts
CHANGED
|
@@ -85,8 +85,4 @@ export class HeyGenVideoGenerator extends BaseVideoGenerator {
|
|
|
85
85
|
public async GetSupportedMethods(): Promise<string[]> {
|
|
86
86
|
return ["CreateAvatarVideo", "CreateVideoTranslation", "GetAvatars"];
|
|
87
87
|
}
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
export function LoadHeyGenVideoGenerator() {
|
|
91
|
-
// does nothing, avoid tree shaking that will get rid of this class since there is no static link to this class in the code base as it is loaded dynamically
|
|
92
88
|
}
|
package/tsconfig.json
CHANGED
|
@@ -1,16 +1,9 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
"sourceMap": true,
|
|
11
|
-
"outDir": "dist",
|
|
12
|
-
"skipLibCheck": true
|
|
13
|
-
},
|
|
14
|
-
"include": ["src/**/*", "test.ts"],
|
|
15
|
-
"exclude": ["node_modules", "**/*.spec.ts"]
|
|
16
|
-
}
|
|
2
|
+
"extends": "../../../../tsconfig.server.json",
|
|
3
|
+
"compilerOptions": {
|
|
4
|
+
"outDir": "dist",
|
|
5
|
+
"rootDir": "src"
|
|
6
|
+
},
|
|
7
|
+
"include": ["src/**/*"],
|
|
8
|
+
"exclude": ["node_modules"]
|
|
9
|
+
}
|