Complete Workflow

Overview

This guide covers the whole lifecycle of an API video: choosing resources, creating the project, following it until the video is ready, and downloading it.

Step-by-step workflow

1. Authentication setup

.env

HOOKED_API_KEY=your_api_key_here
HOOKED_WEBHOOK_TOKEN=a_long_random_string

const API_KEY = process.env.HOOKED_API_KEY;
const BASE_URL = "https://api.hooked.so/v1";

async function hooked(path, { method = "GET", body } = {}) {
  const res = await fetch(`${BASE_URL}${path}`, {
    method,
    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json().catch(() => ({}));
  if (!res.ok) {
    const error = new Error(json.message ?? `HTTP ${res.status}`);
    error.status = res.status;
    error.body = json;
    throw error;
  }
  return json;
}

Get a key in Settings → Developer API.

2. Choose a format

Each format has its own endpoint, POST /v1/project/create/{format}: talking avatar, UGC Studio, script to video, prompt to video, slideshow, scenes and more. You send your script (or prompt) and the ids the format needs, so each video can be completely different. Creating videos lists every endpoint.

The workflow

Step 1: Fetch resources

const [avatars, voices, music] = await Promise.all([
  hooked("/avatar/list?type=all&limit=100"),
  hooked("/voice/list?language=English&limit=100"),
  hooked("/music/list"),
]);

The avatar and voice lists are paginated with limit (up to 100) and offset and return a total; the music list returns every track. They change rarely, so cache them.

Step 2: Select resources

const isFemale = (item) => item.gender?.toLowerCase() === "female";
const avatar = avatars.data.avatars.find((a) => isFemale(a) && !a.isPro);
const voice = voices.data.voices.find((v) => isFemale(v) && !v.unavailable);
const track = music.data.music[0];

Send the voice’s id as voiceId in create requests. A voice with unavailable: true is a cloned voice that only works in the key mode it was cloned in. Which ones a format needs:

Format	Needs
`talking-avatar`, `ugc-studio/*`	`avatarId` (the avatar speaks with its own voice; `ugc-studio/voiceover` also needs a `voiceId` for its narrator)
`script-to-video`, `prompt-to-video`	`voiceId`
`scenes`	`avatarId` for avatar scenes, `mediaId` for clips, `voiceId` for narrated clips

musicId is optional for most formats.

Step 3: Create the video

const created = await hooked("/project/create/script-to-video", {
  method: "POST",
  body: {
    script: "Three habits that make mornings easier. First, prepare everything the night before...",
    voiceId: voice.id,
    musicId: track?.id,
    mediaType: "ai-images",
    aspectRatio: "ratio_9_16",
    webhook: `https://yoursite.com/hooks/hooked?token=${process.env.HOOKED_WEBHOOK_TOKEN}`,
    metadata: { jobId: "job_123" },
  },
});

const projectId = created.data.projectId;
console.log("Project", projectId, created.data.status); // "processing"

Store projectId right away. To resend a create that timed out, send it with the same Idempotency-Key; without one, check first.

Step 4: Monitor progress

Polling with GET /v1/project/{projectId}:

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function waitForVideo(projectId, { intervalMs = 15000, timeoutMs = 30 * 60 * 1000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const { data: project } = await hooked(`/project/${projectId}`);
    const video = project.video;

    if (video?.status === "COMPLETED") return video;
    if (project.status === "failed" || video?.status === "FAILED") {
      throw new Error(video?.message ?? project.message ?? "Project failed");
    }

    console.log(`${project.status} ${project.progress}% ${project.message ?? ""}`);
    await sleep(intervalMs);
  }
  throw new Error(`Timed out waiting for ${projectId}`);
}

const video = await waitForVideo(projectId);
console.log("Ready:", video.url, `${video.durationInSeconds}s`);

Field	Values
`project.status`	`draft`, `processing`, `completed`, `failed`
`project.video`	`null` until rendering starts
`project.video.status`	`STARTED`, `COMPLETED`, `FAILED`
`project.video.url`	`""` until the file is ready

Use the project endpoint, not the video list: a project only appears in GET /v1/video/list once its render has started, and one that fails before that never appears there. Webhook: if you passed webhook, you get a POST with status: "COMPLETED" and data.url, or status: "FAILED". See Webhooks.

Step 5: Download

import { writeFile } from "node:fs/promises";

const file = await fetch(video.url);
if (!file.ok) throw new Error(`Download failed: ${file.status}`);
await writeFile(`${projectId}.mp4`, Buffer.from(await file.arrayBuffer()));

The link can be signed and expire. Keep your own copy; for a fresh link call GET /v1/project/{projectId} again.

Personalized videos

To make one video per customer, build the script from your data and tag the project with your own id:

const customer = { id: "cus_123", firstName: "Sarah", company: "Acme Corp" };

const created = await hooked("/project/create/talking-avatar", {
  method: "POST",
  body: {
    avatarId: avatar.id,
    name: `Welcome - ${customer.firstName}`,
    script: `Hi ${customer.firstName}! Welcome to ${customer.company}. Here is how to get started in two minutes.`,
    webhook: `https://yoursite.com/hooks/hooked?token=${process.env.HOOKED_WEBHOOK_TOKEN}`,
    metadata: { customerId: customer.id },
  },
});

const video = await waitForVideo(created.data.projectId);

The webhook payload and GET /v1/project/{projectId} both return the metadata, so you always know which customer a video belongs to. See Personalization for writing scripts per recipient. For many recipients, loop over your data with a small concurrency and your own ids in metadata. See Bulk Generation.

Re-rendering a project

If you edit a project in the dashboard editor after it was generated, render it again for free:

const { data } = await hooked("/render", {
  method: "POST",
  body: { projectId, webhook: "https://yoursite.com/hooks/hooked?token=..." },
});
console.log(data.videoId, data.status); // "STARTED"

Then poll GET /v1/video/{videoId}, or wait for the webhook. Re-rendering never costs credits. A project whose editor timeline is still empty answers 400.

Complete example

// node --env-file=.env make-video.mjs
import { writeFile } from "node:fs/promises";

const API_KEY = process.env.HOOKED_API_KEY;
const BASE_URL = "https://api.hooked.so/v1";
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function hooked(path, { method = "GET", body } = {}) {
  const res = await fetch(`${BASE_URL}${path}`, {
    method,
    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json().catch(() => ({}));
  if (!res.ok) {
    const error = new Error(json.message ?? `HTTP ${res.status}`);
    error.status = res.status;
    error.body = json;
    throw error;
  }
  return json;
}

async function getWithRetry(path, attempts = 4) {
  for (let i = 1; ; i++) {
    try {
      return await hooked(path);
    } catch (error) {
      const retryable = !error.status || error.status >= 500;
      if (!retryable || i === attempts) throw error;
      await sleep(1000 * 2 ** (i - 1));
    }
  }
}

async function waitForVideo(projectId) {
  for (;;) {
    const { data: project } = await getWithRetry(`/project/${projectId}`);
    const video = project.video;
    if (video?.status === "COMPLETED") return video;
    if (project.status === "failed" || video?.status === "FAILED") {
      throw new Error(video?.message ?? project.message ?? "Project failed");
    }
    await sleep(15000);
  }
}

async function main() {
  const { data } = await getWithRetry("/avatar/list?type=library&limit=20");
  const avatar = data.avatars[0];

  let created;
  try {
    created = await hooked("/project/create/talking-avatar", {
      method: "POST",
      body: {
        avatarId: avatar.id,
        script: "Hey! Quick tip: if you plan tomorrow tonight, your morning takes care of itself.",
        metadata: { jobId: "job_123" },
      },
    });
  } catch (error) {
    if (error.status === 402) {
      console.error("Billing:", error.body.code ?? error.body.errorCode, error.body.missingProviders ?? "");
    }
    // Do not retry a create automatically
    throw error;
  }

  const projectId = created.data.projectId;
  console.log("Project", projectId);

  const video = await waitForVideo(projectId);
  const file = await fetch(video.url);
  await writeFile(`${projectId}.mp4`, Buffer.from(await file.arrayBuffer()));
  console.log(`Saved ${projectId}.mp4 (${video.durationInSeconds}s)`);
}

main().catch((error) => {
  console.error(error.message);
  process.exit(1);
});

Best practices summary

Store the projectId

It is the only handle you need: GET /v1/project/{projectId} gives status, progress and the video.

Webhook plus polling fallback

Webhooks are tried 3 times and then dropped. Poll any project you have not heard about after a while.

Retry creates with a key

Retry GETs freely. Retry a create only with the same Idempotency-Key; without one, check before re-sending.

Keep your own copy

Download finished videos to your storage; links can expire.

Next steps

Bulk Generation

Generate at scale

Error Handling

React to every error

Getting Started

Core Concepts

AI Agents

Guides

Examples

Overview

Step-by-step workflow

1. Authentication setup

2. Choose a format

The workflow

Step 1: Fetch resources

Step 2: Select resources

Step 3: Create the video

Step 4: Monitor progress

Step 5: Download

Personalized videos

Re-rendering a project

Complete example

Best practices summary

Next steps

Bulk Generation

Error Handling

​Overview

​Step-by-step workflow

​1. Authentication setup

​2. Choose a format

​The workflow

​Step 1: Fetch resources

​Step 2: Select resources

​Step 3: Create the video

​Step 4: Monitor progress

​Step 5: Download

​Personalized videos

​Re-rendering a project

​Complete example

​Best practices summary

​Next steps

Bulk Generation

Error Handling

Overview

Step-by-step workflow

1. Authentication setup

2. Choose a format

The workflow

Step 1: Fetch resources

Step 2: Select resources

Step 3: Create the video

Step 4: Monitor progress

Step 5: Download

Personalized videos

Re-rendering a project

Complete example

Best practices summary

Next steps