vargai 0.4.0-alpha101 → 0.4.0-alpha102

package/package.json

@@ -104,7 +104,7 @@
   "license": "Apache-2.0",
   "author": "varg.ai <hello@varg.ai> (https://varg.ai)",
   "sideEffects": false,
-  "version": "0.4.0-alpha101",
+  "version": "0.4.0-alpha102",
   "exports": {
     ".": "./src/index.ts",
     "./ai": "./src/ai-sdk/index.ts",

package/src/ai-sdk/index.ts

@@ -78,6 +78,12 @@ export {
   type GoogleProviderSettings,
   google,
 } from "./providers/google";
+export {
+  createHeyGen,
+  type HeyGenProvider,
+  type HeyGenProviderSettings,
+  heygen,
+} from "./providers/heygen";
 export {
   createHiggsfield,
   type HiggsfieldImageModelSettings,

package/src/ai-sdk/providers/heygen.ts

@@ -0,0 +1,436 @@
+/**
+ * HeyGen AI SDK provider for avatar video generation.
+ *
+ * Exposes heygen.videoModel("avatar-iv") for use in JSX composition:
+ *
+ *   import { heygen } from "vargai/ai-sdk";
+ *
+ *   const talking = Video({
+ *     prompt: { text: "Hello world", images: [portrait] },
+ *     model: heygen.videoModel("avatar-iv"),
+ *     providerOptions: {
+ *       heygen: { voice_id: "abc123", expressiveness: "medium" }
+ *     },
+ *   });
+ */
+
+import {
+  type EmbeddingModelV3,
+  type ImageModelV3,
+  type LanguageModelV3,
+  NoSuchModelError,
+  type ProviderV3,
+  type SharedV3Warning,
+  type SpeechModelV3,
+} from "@ai-sdk/provider";
+import type {
+  VideoModelV3,
+  VideoModelV3CallOptions,
+  VideoModelV3File,
+} from "../video-model";
+
+const HEYGEN_API_BASE = "https://api.heygen.com";
+const HEYGEN_UPLOAD_BASE = "https://upload.heygen.com";
+
+// ---------------------------------------------------------------------------
+// HeyGen response types
+// ---------------------------------------------------------------------------
+
+interface HeyGenVideoStatusData {
+  id: string;
+  status: string;
+  video_url?: string;
+  duration?: number;
+  error?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function getMediaType(file: VideoModelV3File): string | undefined {
+  if ("mediaType" in file && file.mediaType) return file.mediaType;
+  return undefined;
+}
+
+async function fileToBytes(file: VideoModelV3File): Promise<Uint8Array> {
+  if ("data" in file) {
+    if (file.data instanceof Uint8Array) return file.data;
+    if (typeof file.data === "string") return Buffer.from(file.data, "base64");
+  }
+  throw new Error("HeyGen: file has no data");
+}
+
+/**
+ * Upload a file to HeyGen's asset endpoint and return the asset_id.
+ */
+async function uploadAssetToHeyGen(
+  apiKey: string,
+  data: Uint8Array,
+  contentType: string,
+): Promise<string> {
+  const res = await fetch(`${HEYGEN_UPLOAD_BASE}/v1/asset`, {
+    method: "POST",
+    headers: {
+      "X-Api-Key": apiKey,
+      "Content-Type": contentType,
+    },
+    body: data,
+  });
+
+  if (!res.ok) {
+    const errorText = await res.text();
+    throw new Error(`HeyGen asset upload failed (${res.status}): ${errorText}`);
+  }
+
+  const json = (await res.json()) as {
+    data?: { id?: string };
+  };
+  const assetId = json.data?.id;
+  if (!assetId) throw new Error("HeyGen asset upload returned no asset id");
+  return assetId;
+}
+
+/**
+ * Upload an image as a HeyGen talking photo and return the talking_photo_id.
+ * This allows any image to be used as a character in Studio V2 videos.
+ */
+async function uploadTalkingPhoto(
+  apiKey: string,
+  data: Uint8Array,
+  contentType: string,
+): Promise<string> {
+  const res = await fetch(`${HEYGEN_UPLOAD_BASE}/v1/talking_photo`, {
+    method: "POST",
+    headers: {
+      "X-Api-Key": apiKey,
+      "Content-Type": contentType,
+    },
+    body: data,
+  });
+
+  if (!res.ok) {
+    const errorText = await res.text();
+    throw new Error(
+      `HeyGen talking photo upload failed (${res.status}): ${errorText}`,
+    );
+  }
+
+  const json = (await res.json()) as {
+    data?: { talking_photo_id?: string };
+  };
+  const talkingPhotoId = json.data?.talking_photo_id;
+  if (!talkingPhotoId)
+    throw new Error("HeyGen talking photo upload returned no talking_photo_id");
+  return talkingPhotoId;
+}
+
+/**
+ * Build the `background` object for a Studio V2 scene.
+ * Accepts a URL string (image), a hex color, or a structured object.
+ */
+function buildBackground(bg: unknown): Record<string, unknown> | undefined {
+  if (!bg) return undefined;
+  if (typeof bg === "string") {
+    if (bg.startsWith("#")) return { type: "color", value: bg };
+    return { type: "image", url: bg, fit: "cover" };
+  }
+  if (typeof bg === "object") return bg as Record<string, unknown>;
+  return undefined;
+}
+
+/**
+ * Poll HeyGen video status until completed or failed.
+ */
+async function pollVideoStatus(
+  apiKey: string,
+  videoId: string,
+  signal?: AbortSignal,
+): Promise<HeyGenVideoStatusData> {
+  const maxWait = 600_000; // 10 minutes
+  const pollInterval = 5_000; // 5 seconds
+  const start = Date.now();
+
+  while (Date.now() - start < maxWait) {
+    if (signal?.aborted) throw new Error("HeyGen: aborted");
+
+    const res = await fetch(
+      `${HEYGEN_API_BASE}/v1/video_status.get?video_id=${videoId}`,
+      {
+        headers: {
+          "X-Api-Key": apiKey,
+          Accept: "application/json",
+        },
+        signal,
+      },
+    );
+
+    if (!res.ok) {
+      throw new Error(`HeyGen status check failed (${res.status})`);
+    }
+
+    const body = (await res.json()) as {
+      data?: HeyGenVideoStatusData;
+    };
+    const status = body.data?.status?.toLowerCase();
+
+    if (status === "completed") {
+      if (!body.data?.video_url) {
+        throw new Error("HeyGen video completed but no video_url in response");
+      }
+      return body.data;
+    }
+
+    if (status === "failed") {
+      throw new Error(
+        `HeyGen video generation failed: ${body.data?.error ?? "unknown error"}`,
+      );
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, pollInterval));
+  }
+
+  throw new Error(`HeyGen video generation timed out after ${maxWait / 1000}s`);
+}
+
+// ---------------------------------------------------------------------------
+// Video model
+// ---------------------------------------------------------------------------
+
+class HeyGenVideoModel implements VideoModelV3 {
+  readonly specificationVersion = "v3" as const;
+  readonly provider = "heygen";
+  readonly modelId: string;
+  readonly maxVideosPerCall = 1;
+
+  private apiKey: string;
+
+  constructor(modelId: string, apiKey: string) {
+    this.modelId = modelId;
+    this.apiKey = apiKey;
+  }
+
+  async doGenerate(options: VideoModelV3CallOptions) {
+    const { prompt, files, providerOptions, abortSignal } = options;
+    const warnings: SharedV3Warning[] = [];
+
+    const heygenOpts = (providerOptions?.heygen ?? {}) as Record<
+      string,
+      unknown
+    >;
+
+    // ---- Resolve character source ----
+    const avatarId = heygenOpts.avatar_id as string | undefined;
+    const talkingPhotoId = heygenOpts.talking_photo_id as string | undefined;
+    const voiceId = heygenOpts.voice_id as string | undefined;
+
+    // If an image file is provided and no avatar/talking_photo specified,
+    // upload it as a talking photo for use in Studio V2
+    let resolvedTalkingPhotoId = talkingPhotoId;
+    if (!avatarId && !talkingPhotoId) {
+      const imageFile = files?.find((f) =>
+        getMediaType(f)?.startsWith("image/"),
+      );
+      if (imageFile) {
+        const bytes = await fileToBytes(imageFile);
+        const contentType = getMediaType(imageFile) ?? "image/jpeg";
+        resolvedTalkingPhotoId = await uploadTalkingPhoto(
+          this.apiKey,
+          bytes,
+          contentType,
+        );
+      }
+    }
+
+    // Upload audio file if present (external audio mode)
+    let audioAssetId: string | undefined;
+    const audioFile = files?.find((f) => getMediaType(f)?.startsWith("audio/"));
+    if (audioFile) {
+      const audioBytes = await fileToBytes(audioFile);
+      const audioContentType = getMediaType(audioFile) ?? "audio/mpeg";
+      audioAssetId = await uploadAssetToHeyGen(
+        this.apiKey,
+        audioBytes,
+        audioContentType,
+      );
+    }
+
+    if (prompt && voiceId === undefined && !audioFile) {
+      warnings.push({
+        type: "other",
+        message:
+          "HeyGen requires voice_id when using script mode. Pass it via providerOptions.heygen.voice_id",
+      });
+    }
+
+    // ---- Always use Studio V2 (POST /v2/video/generate) ----
+    // Works for both pre-registered avatars and uploaded talking photos.
+
+    // Build character object
+    const character: Record<string, unknown> = {};
+    if (avatarId) {
+      character.type = "avatar";
+      character.avatar_id = avatarId;
+      character.avatar_style = (heygenOpts.avatar_style as string) ?? "normal";
+    } else if (resolvedTalkingPhotoId) {
+      character.type = "talking_photo";
+      character.talking_photo_id = resolvedTalkingPhotoId;
+      if (heygenOpts.talking_style)
+        character.talking_style = heygenOpts.talking_style;
+      if (heygenOpts.use_avatar_iv_model)
+        character.use_avatar_iv_model = heygenOpts.use_avatar_iv_model;
+      if (heygenOpts.matting) character.matting = heygenOpts.matting;
+    }
+
+    // Build voice object
+    const voice: Record<string, unknown> = {};
+    if (audioAssetId) {
+      voice.type = "audio";
+      voice.audio_asset_id = audioAssetId;
+    } else if (prompt && voiceId) {
+      voice.type = "text";
+      voice.input_text = prompt;
+      voice.voice_id = voiceId;
+      if (heygenOpts.speed) voice.speed = heygenOpts.speed;
+      if (heygenOpts.emotion) voice.emotion = heygenOpts.emotion;
+    }
+
+    // Build background object
+    const background = buildBackground(heygenOpts.background);
+
+    // Build scene
+    const scene: Record<string, unknown> = { character, voice };
+    if (background) scene.background = background;
+
+    // Aspect ratio → dimension
+    const aspectRatio =
+      (heygenOpts.aspect_ratio as string | undefined) ?? options.aspectRatio;
+    const dim =
+      aspectRatio === "9:16"
+        ? { width: 720, height: 1280 }
+        : { width: 1280, height: 720 };
+
+    const studioPayload: Record<string, unknown> = {
+      video_inputs: [scene],
+      dimension: dim,
+    };
+    if (heygenOpts.callback_url)
+      studioPayload.callback_url = heygenOpts.callback_url;
+    if (heygenOpts.title) studioPayload.title = heygenOpts.title;
+    if (heygenOpts.caption) studioPayload.caption = heygenOpts.caption;
+
+    const submitUrl = `${HEYGEN_API_BASE}/v2/video/generate`;
+    const submitBody = JSON.stringify(studioPayload);
+
+    // ---- Submit ----
+    const submitRes = await fetch(submitUrl, {
+      method: "POST",
+      headers: {
+        "X-Api-Key": this.apiKey,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: submitBody,
+      signal: abortSignal,
+    });
+
+    if (!submitRes.ok) {
+      const errorText = await submitRes.text();
+      throw new Error(
+        `HeyGen video generation failed (${submitRes.status}): ${errorText}`,
+      );
+    }
+
+    const submitData = (await submitRes.json()) as {
+      data?: { video_id?: string };
+      video_id?: string;
+    };
+    const videoId = submitData.data?.video_id ?? submitData.video_id;
+    if (!videoId) throw new Error("HeyGen returned no video_id");
+
+    // ---- Poll for completion ----
+    const statusData = await pollVideoStatus(this.apiKey, videoId, abortSignal);
+
+    // ---- Download video ----
+    const videoRes = await fetch(statusData.video_url!, {
+      signal: abortSignal,
+    });
+    if (!videoRes.ok) {
+      throw new Error(`Failed to download HeyGen video (${videoRes.status})`);
+    }
+    const videoBytes = new Uint8Array(await videoRes.arrayBuffer());
+
+    return {
+      videos: [videoBytes],
+      warnings,
+      response: {
+        timestamp: new Date(),
+        modelId: this.modelId,
+        headers: undefined,
+      },
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Provider factory
+// ---------------------------------------------------------------------------
+
+export interface HeyGenProviderSettings {
+  apiKey?: string;
+}
+
+export interface HeyGenProvider extends ProviderV3 {
+  videoModel(modelId?: string): VideoModelV3;
+}
+
+export function createHeyGen(
+  settings: HeyGenProviderSettings = {},
+): HeyGenProvider {
+  const apiKey = settings.apiKey ?? process.env.HEYGEN_API_KEY;
+  if (!apiKey) {
+    throw new Error("HEYGEN_API_KEY not set");
+  }
+
+  return {
+    specificationVersion: "v3",
+    videoModel(modelId = "avatar-iv") {
+      return new HeyGenVideoModel(modelId, apiKey);
+    },
+    languageModel(modelId: string): LanguageModelV3 {
+      throw new NoSuchModelError({
+        modelId,
+        modelType: "languageModel",
+      });
+    },
+    embeddingModel(modelId: string): EmbeddingModelV3 {
+      throw new NoSuchModelError({
+        modelId,
+        modelType: "embeddingModel",
+      });
+    },
+    imageModel(modelId: string): ImageModelV3 {
+      throw new NoSuchModelError({
+        modelId,
+        modelType: "imageModel",
+      });
+    },
+    speechModel(modelId: string): SpeechModelV3 {
+      throw new NoSuchModelError({
+        modelId,
+        modelType: "speechModel",
+      });
+    },
+  };
+}
+
+// Lazy singleton (same pattern as elevenlabs)
+let _heygen: HeyGenProvider | undefined;
+export const heygen = new Proxy({} as HeyGenProvider, {
+  get(_, prop) {
+    if (!_heygen) {
+      _heygen = createHeyGen();
+    }
+    return _heygen[prop as keyof HeyGenProvider];
+  },
+});

package/src/definitions/models/heygen.ts

@@ -0,0 +1,61 @@
+/**
+ * HeyGen avatar video model
+ * Generates talking avatar videos from script + voice + image/avatar
+ */
+
+import { z } from "zod";
+import type { ModelDefinition, ZodSchema } from "../../core/schema/types";
+
+const heygenInputSchema = z.object({
+  script: z.string().describe("Script text for the avatar to speak"),
+  voice_id: z.string().describe("HeyGen voice ID"),
+  avatar_id: z.string().optional().describe("Pre-registered HeyGen avatar ID"),
+  image_url: z
+    .string()
+    .optional()
+    .describe("Image URL to animate (alternative to avatar_id)"),
+  motion_prompt: z
+    .string()
+    .optional()
+    .describe("Natural language motion control prompt"),
+  expressiveness: z
+    .enum(["low", "medium", "high"])
+    .optional()
+    .default("medium")
+    .describe("Expressiveness level of the avatar"),
+  aspect_ratio: z
+    .enum(["16:9", "9:16"])
+    .optional()
+    .default("16:9")
+    .describe("Video aspect ratio"),
+  resolution: z
+    .enum(["720p", "1080p"])
+    .optional()
+    .default("1080p")
+    .describe("Video resolution"),
+});
+
+const heygenOutputSchema = z.object({
+  videoUrl: z.string(),
+  duration: z.number().optional(),
+});
+
+const schema: ZodSchema<typeof heygenInputSchema, typeof heygenOutputSchema> = {
+  input: heygenInputSchema,
+  output: heygenOutputSchema,
+};
+
+export const definition: ModelDefinition<typeof schema> = {
+  type: "model",
+  name: "heygen-avatar",
+  description:
+    "HeyGen Avatar IV model for generating talking avatar videos from script and voice",
+  providers: ["heygen"],
+  defaultProvider: "heygen",
+  providerModels: {
+    heygen: "avatar-iv",
+  },
+  schema,
+};
+
+export default definition;

package/src/definitions/models/index.ts

@@ -4,6 +4,7 @@
 
 export { definition as elevenlabsTts } from "./elevenlabs";
 export { definition as flux } from "./flux";
+export { definition as heygenAvatar } from "./heygen";
 export { definition as kling } from "./kling";
 export { definition as llama } from "./llama";
 export { definition as ltxA2v } from "./ltx-a2v";
@@ -31,6 +32,7 @@ export { definition as whisper } from "./whisper";
 // All model definitions for auto-loading
 import { definition as elevenlabsDefinition } from "./elevenlabs";
 import { definition as fluxDefinition } from "./flux";
+import { definition as heygenAvatarDefinition } from "./heygen";
 import { definition as klingDefinition } from "./kling";
 import { definition as llamaDefinition } from "./llama";
 import { definition as ltxA2vDefinition } from "./ltx-a2v";
@@ -77,4 +79,5 @@ export const allModels = [
   seedance2FastPreviewDefinition,
   sonautoDefinition,
   llamaDefinition,
+  heygenAvatarDefinition,
 ];

package/src/providers/heygen.ts

@@ -0,0 +1,480 @@
+/**
+ * HeyGen provider for AI avatar video generation
+ * Supports text-to-video with talking avatars, photo-to-video lipsync,
+ * and pre-built avatar catalog.
+ *
+ * HeyGen API docs: https://docs.heygen.com/reference
+ */
+
+import type { JobStatusUpdate, ProviderConfig } from "../core/schema/types";
+import { BaseProvider } from "./base";
+
+const HEYGEN_API_BASE = "https://api.heygen.com";
+const HEYGEN_UPLOAD_BASE = "https://upload.heygen.com";
+
+// ---------------------------------------------------------------------------
+// Response types
+// ---------------------------------------------------------------------------
+
+interface HeyGenVideoResponse {
+  video_id: string;
+  status?: string;
+}
+
+interface HeyGenVideoStatusResponse {
+  code: number;
+  data: {
+    id: string;
+    status: string;
+    video_url?: string;
+    video_url_caption?: string;
+    thumbnail_url?: string;
+    gif_url?: string;
+    caption_url?: string;
+    duration?: number;
+    error?: string | null;
+    callback_id?: string;
+    created_at?: number;
+  };
+  message: string;
+}
+
+interface HeyGenVoice {
+  voice_id: string;
+  name: string;
+  language: string;
+  gender: string;
+  preview_audio?: string;
+  support_pause?: boolean;
+  emotion_support?: boolean;
+  support_interactive_avatar?: boolean;
+  support_locale?: boolean;
+}
+
+interface HeyGenAvatar {
+  avatar_id: string;
+  avatar_name: string;
+  gender?: string;
+  preview_image_url?: string;
+  preview_video_url?: string;
+  tags?: string[];
+}
+
+interface HeyGenTalkingPhoto {
+  talking_photo_id: string;
+  talking_photo_name: string;
+  preview_image_url?: string;
+}
+
+interface HeyGenAssetUploadResponse {
+  code: number;
+  data: {
+    id: string;
+    name: string;
+    file_type: string;
+    url: string;
+    image_key?: string;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+export class HeyGenProvider extends BaseProvider {
+  readonly name = "heygen";
+  private apiKey: string;
+
+  constructor(config?: ProviderConfig) {
+    super({
+      timeout: 600000, // 10 minutes default (avatar videos can take 30-120s)
+      ...config,
+    });
+    this.apiKey = config?.apiKey || process.env.HEYGEN_API_KEY || "";
+  }
+
+  // ---- Provider interface ----
+
+  async submit(
+    _model: string,
+    inputs: Record<string, unknown>,
+    _config?: ProviderConfig,
+  ): Promise<string> {
+    const script = inputs.script as string | undefined;
+    const voiceId = inputs.voice_id as string | undefined;
+    const avatarId = inputs.avatar_id as string | undefined;
+    const talkingPhotoId = inputs.talking_photo_id as string | undefined;
+    const audioUrl = inputs.audio_url as string | undefined;
+    const audioAssetId = inputs.audio_asset_id as string | undefined;
+    const aspectRatio = inputs.aspect_ratio as string | undefined;
+    const callbackUrl = inputs.callback_url as string | undefined;
+    const title = inputs.title as string | undefined;
+    const background = inputs.background as
+      | Record<string, unknown>
+      | string
+      | undefined;
+
+    // Always use Studio V2 (POST /v2/video/generate)
+    // Works for avatars, talking photos, and uploaded images
+
+    // Build character
+    const character: Record<string, unknown> = {};
+    if (avatarId) {
+      character.type = "avatar";
+      character.avatar_id = avatarId;
+      character.avatar_style = (inputs.avatar_style as string) ?? "normal";
+    } else if (talkingPhotoId) {
+      character.type = "talking_photo";
+      character.talking_photo_id = talkingPhotoId;
+      if (inputs.talking_style) character.talking_style = inputs.talking_style;
+      if (inputs.matting) character.matting = inputs.matting;
+    }
+
+    // Build voice
+    const voice: Record<string, unknown> = {};
+    if (script && voiceId) {
+      voice.type = "text";
+      voice.input_text = script;
+      voice.voice_id = voiceId;
+      if (inputs.speed) voice.speed = inputs.speed;
+      if (inputs.emotion) voice.emotion = inputs.emotion;
+    } else if (audioUrl) {
+      voice.type = "audio";
+      voice.audio_url = audioUrl;
+    } else if (audioAssetId) {
+      voice.type = "audio";
+      voice.audio_asset_id = audioAssetId;
+    }
+
+    // Build background
+    let bg: Record<string, unknown> | undefined;
+    if (typeof background === "string") {
+      bg = background.startsWith("#")
+        ? { type: "color", value: background }
+        : { type: "image", url: background, fit: "cover" };
+    } else if (background) {
+      bg = background;
+    }
+
+    // Build scene
+    const scene: Record<string, unknown> = { character, voice };
+    if (bg) scene.background = bg;
+
+    // Dimension from aspect ratio
+    const dim =
+      aspectRatio === "9:16"
+        ? { width: 720, height: 1280 }
+        : { width: 1280, height: 720 };
+
+    const payload: Record<string, unknown> = {
+      video_inputs: [scene],
+      dimension: dim,
+    };
+    if (callbackUrl) payload.callback_url = callbackUrl;
+    if (title) payload.title = title;
+
+    console.log("[heygen] submitting via Studio V2...");
+
+    const response = await fetch(`${HEYGEN_API_BASE}/v2/video/generate`, {
+      method: "POST",
+      headers: {
+        "X-Api-Key": this.apiKey,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `heygen submit failed (${response.status}): ${errorText}`,
+      );
+    }
+
+    const data = (await response.json()) as {
+      data?: HeyGenVideoResponse;
+      video_id?: string;
+      error?: unknown;
+    };
+    const videoId = data.data?.video_id ?? data.video_id;
+
+    if (!videoId) {
+      throw new Error("no video_id in heygen response");
+    }
+
+    console.log(`[heygen] video submitted: ${videoId}`);
+    return videoId;
+  }
+
+  async getStatus(jobId: string): Promise<JobStatusUpdate> {
+    const res = await fetch(
+      `${HEYGEN_API_BASE}/v1/video_status.get?video_id=${jobId}`,
+      {
+        method: "GET",
+        headers: {
+          "X-Api-Key": this.apiKey,
+          Accept: "application/json",
+        },
+      },
+    );
+
+    if (!res.ok) {
+      throw new Error(`heygen status check failed (${res.status})`);
+    }
+
+    const body = (await res.json()) as HeyGenVideoStatusResponse;
+    const status = body.data?.status?.toLowerCase();
+
+    const statusMap: Record<string, JobStatusUpdate["status"]> = {
+      pending: "queued",
+      waiting: "queued",
+      processing: "processing",
+      completed: "completed",
+      failed: "failed",
+    };
+
+    return {
+      status: statusMap[status] ?? "processing",
+      output: body.data?.video_url
+        ? { url: body.data.video_url, duration: body.data.duration }
+        : undefined,
+      error: body.data?.error ?? undefined,
+    };
+  }
+
+  async getResult(jobId: string): Promise<unknown> {
+    const res = await fetch(
+      `${HEYGEN_API_BASE}/v1/video_status.get?video_id=${jobId}`,
+      {
+        method: "GET",
+        headers: {
+          "X-Api-Key": this.apiKey,
+          Accept: "application/json",
+        },
+      },
+    );
+
+    if (!res.ok) {
+      throw new Error(`heygen result fetch failed (${res.status})`);
+    }
+
+    const body = (await res.json()) as HeyGenVideoStatusResponse;
+    return body.data;
+  }
+
+  // ---- Convenience methods ----
+
+  /**
+   * Generate an avatar video from script text using Avatar IV.
+   * This is the simplest path: script + voice + avatar/image = video.
+   */
+  async createAvatarVideo(args: {
+    script: string;
+    voiceId: string;
+    avatarId?: string;
+    imageUrl?: string;
+    motionPrompt?: string;
+    expressiveness?: "low" | "medium" | "high";
+    aspectRatio?: "16:9" | "9:16";
+    resolution?: "720p" | "1080p";
+  }) {
+    console.log("[heygen] starting avatar video generation...");
+
+    const videoId = await this.submit("avatar-iv", {
+      script: args.script,
+      voice_id: args.voiceId,
+      ...(args.avatarId ? { avatar_id: args.avatarId } : {}),
+      ...(args.imageUrl ? { image_url: args.imageUrl } : {}),
+      ...(args.motionPrompt ? { motion_prompt: args.motionPrompt } : {}),
+      ...(args.expressiveness ? { expressiveness: args.expressiveness } : {}),
+      ...(args.aspectRatio ? { aspect_ratio: args.aspectRatio } : {}),
+      ...(args.resolution ? { resolution: args.resolution } : {}),
+    });
+
+    const result = (await this.waitForCompletion(videoId, {
+      maxWait: this.config.timeout ?? 600000,
+      pollInterval: 5000,
+    })) as { url?: string; duration?: number };
+
+    if (!result?.url) {
+      throw new Error("heygen video completed but no video URL");
+    }
+
+    console.log("[heygen] avatar video completed!");
+    return { video: { url: result.url, duration: result.duration } };
+  }
+
+  /**
+   * List available HeyGen voices.
+   */
+  async listVoices(): Promise<HeyGenVoice[]> {
+    console.log("[heygen] fetching voices...");
+
+    const res = await fetch(`${HEYGEN_API_BASE}/v2/voices`, {
+      headers: {
+        "X-Api-Key": this.apiKey,
+        Accept: "application/json",
+      },
+    });
+
+    if (!res.ok) {
+      const errorText = await res.text();
+      throw new Error(
+        `heygen list voices failed (${res.status}): ${errorText}`,
+      );
+    }
+
+    const data = (await res.json()) as {
+      data?: { voices?: HeyGenVoice[] };
+      error?: unknown;
+    };
+    const voices = data.data?.voices ?? [];
+    console.log(`[heygen] found ${voices.length} voices`);
+    return voices;
+  }
+
+  /**
+   * List available HeyGen avatars and talking photos.
+   */
+  async listAvatars(): Promise<{
+    avatars: HeyGenAvatar[];
+    talkingPhotos: HeyGenTalkingPhoto[];
+  }> {
+    console.log("[heygen] fetching avatars...");
+
+    const res = await fetch(`${HEYGEN_API_BASE}/v2/avatars`, {
+      headers: {
+        "X-Api-Key": this.apiKey,
+        Accept: "application/json",
+      },
+    });
+
+    if (!res.ok) {
+      const errorText = await res.text();
+      throw new Error(
+        `heygen list avatars failed (${res.status}): ${errorText}`,
+      );
+    }
+
+    const data = (await res.json()) as {
+      data?: {
+        avatars?: HeyGenAvatar[];
+        talking_photos?: HeyGenTalkingPhoto[];
+      };
+      error?: unknown;
+    };
+
+    const avatars = data.data?.avatars ?? [];
+    const talkingPhotos = data.data?.talking_photos ?? [];
+    console.log(
+      `[heygen] found ${avatars.length} avatars, ${talkingPhotos.length} talking photos`,
+    );
+    return { avatars, talkingPhotos };
+  }
+
+  /**
+   * Upload an image as a talking photo to HeyGen.
+   * Returns a talking_photo_id that can be used in Studio V2 video generation.
+   */
+  async uploadTalkingPhoto(
+    file: Uint8Array | ArrayBuffer,
+    contentType = "image/jpeg",
+  ): Promise<string> {
+    console.log("[heygen] uploading talking photo...");
+
+    const body = file instanceof Uint8Array ? file : new Uint8Array(file);
+
+    const res = await fetch(`${HEYGEN_UPLOAD_BASE}/v1/talking_photo`, {
+      method: "POST",
+      headers: {
+        "X-Api-Key": this.apiKey,
+        "Content-Type": contentType,
+      },
+      body,
+    });
+
+    if (!res.ok) {
+      const errorText = await res.text();
+      throw new Error(
+        `heygen talking photo upload failed (${res.status}): ${errorText}`,
+      );
+    }
+
+    const data = (await res.json()) as {
+      data?: { talking_photo_id?: string };
+    };
+    const talkingPhotoId = data.data?.talking_photo_id;
+
+    if (!talkingPhotoId) {
+      throw new Error("no talking_photo_id in heygen upload response");
+    }
+
+    console.log(`[heygen] uploaded talking photo: ${talkingPhotoId}`);
+    return talkingPhotoId;
+  }
+
+  /**
+   * Upload an asset (image/audio/video) to HeyGen.
+   * Note: uses upload.heygen.com, not api.heygen.com.
+   */
+  async uploadAsset(
+    file: Uint8Array | ArrayBuffer,
+    contentType: string,
+  ): Promise<{ assetId: string; url: string }> {
+    console.log(`[heygen] uploading asset (${contentType})...`);
+
+    const body = file instanceof Uint8Array ? file : new Uint8Array(file);
+
+    const res = await fetch(`${HEYGEN_UPLOAD_BASE}/v1/asset`, {
+      method: "POST",
+      headers: {
+        "X-Api-Key": this.apiKey,
+        "Content-Type": contentType,
+      },
+      body,
+    });
+
+    if (!res.ok) {
+      const errorText = await res.text();
+      throw new Error(
+        `heygen asset upload failed (${res.status}): ${errorText}`,
+      );
+    }
+
+    const data = (await res.json()) as HeyGenAssetUploadResponse;
+    const assetId = data.data?.id;
+    const url = data.data?.url;
+
+    if (!assetId) {
+      throw new Error("no asset id in heygen upload response");
+    }
+
+    console.log(`[heygen] uploaded asset: ${assetId}`);
+    return { assetId, url: url ?? "" };
+  }
+
+  /**
+   * Get remaining API quota.
+   */
+  async getRemainingQuota(): Promise<number> {
+    const res = await fetch(`${HEYGEN_API_BASE}/v2/user/remaining_quota`, {
+      headers: {
+        "X-Api-Key": this.apiKey,
+        Accept: "application/json",
+      },
+    });
+
+    if (!res.ok) {
+      throw new Error(`heygen quota check failed (${res.status})`);
+    }
+
+    const data = (await res.json()) as {
+      data?: { remaining_quota?: number };
+    };
+    return data.data?.remaining_quota ?? 0;
+  }
+}
+
+// Export singleton instance
+export const heygenProvider = new HeyGenProvider();

package/src/providers/index.ts

@@ -86,6 +86,8 @@ export {
   listModels,
   transcribeAudio,
 } from "./groq";
+// HeyGen provider (AI avatar video generation)
+export { HeyGenProvider, heygenProvider } from "./heygen";
 // Higgsfield provider (Soul image generation)
 export {
   BatchSize,
@@ -129,6 +131,7 @@ import { falProvider } from "./fal";
 import { ffmpegProvider } from "./ffmpeg";
 import { fireworksProvider } from "./fireworks";
 import { groqProvider } from "./groq";
+import { heygenProvider } from "./heygen";
 import { higgsfieldProvider } from "./higgsfield";
 import { piapiProvider } from "./piapi";
 import { replicateProvider } from "./replicate";
@@ -142,6 +145,7 @@ providers.register(elevenlabsProvider);
 providers.register(groqProvider);
 providers.register(fireworksProvider);
 providers.register(higgsfieldProvider);
+providers.register(heygenProvider);
 providers.register(piapiProvider);
 providers.register(ffmpegProvider);
 providers.register(storageProvider);