HeyGen Video 1

About

Generates video from text, an image, references · 480p to 2K · 5–15 s · native audio

Model id heygen-video-1, sent to POST https://api.sume.com/v1/video-router/generate.

1. Calling the API

Install the client

npm install @sume-com/client

Setup your API key

Set SUME_API_KEY as an environment variable in your server runtime. Make the key in Sume API → API keys.

export SUME_API_KEY="YOUR_API_KEY"

Submit a request

This sends the Playground's request, with the input it holds now. Change the input there and this updates. subscribe submits it, waits for the job and returns the result.

import { createSumeClient } from "@sume-com/client";

const sume = createSumeClient({ baseURL: "https://api.sume.com" });

const response = await sume.subscribe("/v1/video-router/generate", {
  input: {
    "model": "heygen-video-1",
    "prompt": "He smiles and explains a slow breathing exercise to the camera, with calm open-hand gestures.",
    "image_url": "https://media.sume.com/artifacts/artf_Rrnie28uyyn1-KcCJXsrFKJRzXJNQQWs/images.png",
    "duration": 5,
    "resolution": "480p",
    "aspect_ratio": "16:9"
  },
});

console.log(response.status, response.video?.url);

2. Authentication

API key

Send your Sume API key as a bearer token from server code only. Keys made under Sume API → API keys spend the workspace balance, the same one Studio spends, and call the model API only.

Authorization: Bearer $SUME_API_KEY

3. Queue

A submit answers at once with the job. Poll its status until it is completed, failed or canceled. Failed and canceled jobs are refunded.

Fetch request status

const response = await fetch(`https://api.sume.com/v1/jobs/${jobId}/status`, {
  headers: { authorization: `Bearer ${process.env.SUME_API_KEY}` },
});
const { data: job } = await response.json();

Get the result

A completed job returns its media. A queued or running job answers 409 job_not_completed with the current status; a failed one 409 job_failed with the reason, and a canceled one 409 job_canceled.

const response = await fetch(`https://api.sume.com/v1/jobs/${jobId}/result`, {
  headers: { authorization: `Bearer ${process.env.SUME_API_KEY}` },
});
const { data: result } = await response.json();

Cancel a request

A job can be canceled until generation starts.

const response = await fetch(`https://api.sume.com/v1/jobs/${jobId}/cancel`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.SUME_API_KEY}` },
});
const { data: job } = await response.json();

4. Files

Hosted files (URL)

Fields that end in _url or _urls take public HTTPS URLs. Some hosts block or rate-limit fetches from servers.

Uploading files

Upload a local file to Sume's storage, then send the URL it returns.

import { readFile } from "node:fs/promises";
import { createSumeClient } from "@sume-com/client";

const sume = createSumeClient({ baseURL: "https://api.sume.com" });

const url = await sume.uploadImage(await readFile("input.png"), "png");

5. Schema

Input

modelstringrequired

"heygen-video-1"

promptstringrequired

What happens in the video.

image_urlstring

First frame (HTTPS image).

reference_image_urlsstring[]

Reference images (HTTPS).

durationinteger

Seconds, 5–15.Default value: 5Range: 5–15

resolutionstring

Output resolution.Default value: "480p"Possible enum values: 480p, 768p, 2K

aspect_ratiostring

Frame shape.Default value: "16:9"Possible enum values: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9

{
  "model": "heygen-video-1",
  "prompt": "He smiles and explains a slow breathing exercise to the camera, with calm open-hand gestures.",
  "image_url": "https://media.sume.com/artifacts/artf_Rrnie28uyyn1-KcCJXsrFKJRzXJNQQWs/images.png",
  "duration": 5,
  "resolution": "480p",
  "aspect_ratio": "16:9"
}

Output

data.result.artifactsArtifact[]required

The generated media, in order.

data.jobJobrequired

The job record: id, status, model, input, created_at, started_at and completed_at.

Artifact

urlstringrequired

Public Sume CDN URL for the file. Do not parse the path.

typestringrequired

image, video, audio, model or file.

content_typestringrequired

The file's MIME type.

idstringrequired

Opaque artifact id, safe to log.

widthinteger

Pixels, when known.

heightinteger

Pixels, when known.

duration_msinteger

Length of a video or audio file, when known.

size_bytesinteger

File size, when known.

6. Price before you submit

The estimate is the charge: the same function prices both. This one prices the Playground's input.

const response = await fetch("https://api.sume.com/v1/open/estimate", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    "model": "heygen-video-1",
    "input": {
      "prompt": "He smiles and explains a slow breathing exercise to the camera, with calm open-hand gestures.",
      "image_url": "https://media.sume.com/artifacts/artf_Rrnie28uyyn1-KcCJXsrFKJRzXJNQQWs/images.png",
      "duration": 5,
      "resolution": "480p",
      "aspect_ratio": "16:9"
    }
  }),
});
const { data } = await response.json();
console.log(data.usd);

Full reference: /docs