Bulk Generation

Overview

Bulk generation is a loop over your data: one create request per recipient, each with its own values and your own id in metadata, and a webhook (or polling) to collect the results. Every create starts real generation work and, on a managed team, charges credits. Each team can send 30 POST requests per minute (120 for reads) and have 3 downloads of its URLs running at once; over that the API answers 429 with a Retry-After header. Send requests at a steady pace with a small number in flight, wait Retry-After seconds on a 429, and test on a few records first.

Prerequisites

A format and its ids

The format endpoint you will call for every row (for example POST /v1/project/create/talking-avatar), and the avatar, voice or media ids it needs from the list endpoints. See Creating videos.

Enough credits or your own keys

On a managed team, check the balance covers the batch. On a byok team, make sure the provider keys the format needs are set. See Credits and your own keys.

A webhook endpoint

An HTTPS endpoint that records each finished video. See Webhooks.

Basic bulk generation

Step 1: Prepare your data

const recipients = [
  { id: "cus_001", first_name: "John", company: "Acme Corp" },
  { id: "cus_002", first_name: "Sarah", company: "TechStart" },
  { id: "cus_003", first_name: "Mike", company: "Global Inc" },
];

Fill empty values with defaults before you start, so no script has a gap in it.

Step 2: A simple generator

const API_KEY = process.env.HOOKED_API_KEY;
const BASE_URL = "https://api.hooked.so/v1";
const AVATAR_ID = "cm4x9k2p10001ab12cd34ef56"; // from GET /v1/avatar/list
const WEBHOOK = `https://yoursite.com/hooks/hooked?token=${process.env.HOOKED_WEBHOOK_TOKEN}`;

async function createForRecipient(recipient) {
  const res = await fetch(`${BASE_URL}/project/create/talking-avatar`, {
    method: "POST",
    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      avatarId: AVATAR_ID,
      name: `Welcome - ${recipient.first_name}`,
      script: `Hi ${recipient.first_name}! Welcome to ${recipient.company}. Here is how to get started in two minutes.`,
      webhook: WEBHOOK,
      metadata: { recipientId: recipient.id },
    }),
  });
  const json = await res.json().catch(() => ({}));
  return { recipient, status: res.status, ok: res.ok, json };
}

const results = [];
for (const recipient of recipients) {
  const result = await createForRecipient(recipient);
  results.push(result);
  if (result.ok) {
    console.log(`Created ${result.json.data.projectId} for ${recipient.id}`);
  } else {
    console.error(`Failed for ${recipient.id}: ${result.status} ${result.json.message}`);
    if (result.status === 402 || result.status === 401) break; // the rest would fail too
  }
}

Store each projectId with the recipient as soon as you get it. The same loop works with any other format: change the endpoint and the body, for example script-to-video with a voiceId and mediaType.

Advanced: concurrency and failures

Run a few requests at once, stop on account-level errors, and never re-send a create whose outcome you do not know.

const CONCURRENCY = 3;

async function runBatch(recipients, createFn) {
  const queue = [...recipients];
  const created = [];
  const rejected = []; // 4xx: fix the data, safe to send again later
  const unknown = []; // network error or 5xx: check before re-sending
  let stop = false;

  async function worker() {
    while (queue.length > 0 && !stop) {
      const recipient = queue.shift();
      try {
        const result = await createFn(recipient);
        if (result.ok) {
          created.push({ recipientId: recipient.id, projectId: result.json.data.projectId });
        } else if (result.status === 429) {
          // Over the team's rate limit: nothing was created, so wait and send it again
          queue.unshift(recipient);
          await new Promise((r) => setTimeout(r, (result.json.retryAfterSeconds ?? 5) * 1000));
        } else if (result.status >= 500) {
          unknown.push({ recipient, reason: result.json.message });
        } else {
          rejected.push({ recipient, status: result.status, reason: result.json.message });
          if (result.status === 401 || result.status === 402) stop = true;
        }
      } catch (error) {
        unknown.push({ recipient, reason: error.message });
      }
    }
  }

  await Promise.all(Array.from({ length: CONCURRENCY }, worker));
  return { created, rejected, unknown, notSent: queue };
}

const report = await runBatch(recipients, createForRecipient);
console.log(report.created.length, "created");
console.log(report.rejected.length, "rejected", report.rejected);
console.log(report.unknown.length, "unknown: check these before re-sending", report.unknown);
console.log(report.notSent.length, "not sent");

Requests in unknown may have created a project anyway. Re-send them with the same Idempotency-Key they were first sent with and you get the first answer back instead of a second video. Without a key, re-sending can create and charge a second video: look for them first (by the recipientId in the webhook’s metadata, in your dashboard, or with GET /v1/project/list?source=api, which lists a project as soon as it is created) and only re-send the ones that really did not go through.

Processing CSV files

import { readFile } from "node:fs/promises";
import { parse } from "csv-parse/sync"; // npm install csv-parse

const rows = parse(await readFile("recipients.csv"), {
  columns: true,
  skip_empty_lines: true,
  trim: true,
});

const recipients = rows
  .map((row) => ({
    id: row.id,
    first_name: row.first_name || "there",
    company: row.company || "your team",
  }))
  .filter((row) => row.id);

const report = await runBatch(recipients, createForRecipient);

recipients.csv

id,first_name,company
cus_001,John,Acme Corp
cus_002,Sarah,TechStart
cus_003,Mike,Global Inc

Database integration

Keep a row per recipient with its state. This makes the batch resumable and avoids duplicates.

CREATE TABLE video_jobs (
  recipient_id TEXT PRIMARY KEY,
  status TEXT NOT NULL DEFAULT 'pending', -- pending | sending | created | completed | failed | unknown
  project_id TEXT,
  video_id TEXT,
  video_url TEXT,
  error TEXT,
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

// db is your database client (e.g. node-postgres)
async function processPending(db) {
  const { rows } = await db.query(
    "UPDATE video_jobs SET status = 'sending', updated_at = now() " +
      "WHERE recipient_id IN (SELECT recipient_id FROM video_jobs WHERE status = 'pending' LIMIT 50) " +
      "RETURNING recipient_id"
  );

  for (const { recipient_id } of rows) {
    const recipient = await loadRecipient(recipient_id); // your own lookup
    try {
      const result = await createForRecipient(recipient);
      if (result.ok) {
        await db.query(
          "UPDATE video_jobs SET status = 'created', project_id = $2, updated_at = now() WHERE recipient_id = $1",
          [recipient_id, result.json.data.projectId]
        );
      } else {
        await db.query(
          "UPDATE video_jobs SET status = $2, error = $3, updated_at = now() WHERE recipient_id = $1",
          [recipient_id, result.status >= 500 ? "unknown" : "failed", result.json.message ?? `HTTP ${result.status}`]
        );
      }
    } catch (error) {
      await db.query(
        "UPDATE video_jobs SET status = 'unknown', error = $2, updated_at = now() WHERE recipient_id = $1",
        [recipient_id, error.message]
      );
    }
  }
}

Because a row moves to sending before the request, a crash leaves it in sending rather than pending, so a restart does not send it twice. Review sending and unknown rows by hand.

Webhook management for bulk jobs

Every webhook carries your metadata, so one endpoint can serve the whole batch:

app.post("/hooks/hooked", express.json(), async (req, res) => {
  if (req.query.token !== process.env.HOOKED_WEBHOOK_TOKEN) return res.sendStatus(401);
  res.sendStatus(200);

  const { status, message, data } = req.body;
  const recipientId = data.metadata?.recipientId;

  if (status === "COMPLETED") {
    await db.query(
      "UPDATE video_jobs SET status = 'completed', video_id = $2, video_url = $3, updated_at = now() " +
        "WHERE project_id = $1",
      [data.projectId, data.videoId, data.url]
    );
  } else {
    await db.query(
      "UPDATE video_jobs SET status = 'failed', error = $2, updated_at = now() WHERE project_id = $1",
      [data.projectId, message]
    );
  }
  console.log(`${recipientId ?? data.projectId}: ${status}`);
});

Match on projectId (you stored it when you created the project). Render-failure payloads do not include metadata, so do not rely on it alone.

Catching up

Webhooks are tried 3 times in a row and then dropped. For rows still in created after a while, ask the API directly:

async function refreshProject(projectId) {
  const res = await fetch(`${BASE_URL}/project/${projectId}`, { headers: { "x-api-key": API_KEY } });
  const { data } = await res.json();
  if (data.video?.status === "COMPLETED") return { status: "completed", url: data.video.url, videoId: data.video.id };
  if (data.status === "failed" || data.video?.status === "FAILED") return { status: "failed", error: data.video?.message ?? data.message };
  return { status: "created" };
}

Performance tips

Keep a few requests in flight, not hundreds. Each create does real work (validation, pricing, project setup) before it answers, and a team can send 30 POST requests per minute.
Test with 3 to 5 rows and watch the videos before sending the full list.
Fetch shared data once. Avatar, voice and music lists do not change during a batch.
Spread very large batches over time so finished videos keep flowing in while new ones start.

Best practices

Store ids immediately

Save each projectId the moment the create call returns

Use metadata

Put your own recipient id in metadata on every request

Never blind-retry creates

Check before re-sending after a timeout or 5xx

Stop on 401/402

Account errors will fail every remaining request too

Next steps

Personalization

Make each video feel personal

Webhooks

Receive results reliably

Getting Started

Core Concepts

AI Agents

Guides

Examples

Overview

Prerequisites

Basic bulk generation

Step 1: Prepare your data

Step 2: A simple generator

Advanced: concurrency and failures

Processing CSV files

Database integration

Webhook management for bulk jobs

Catching up

Performance tips

Best practices

Store ids immediately

Use metadata

Never blind-retry creates

Stop on 401/402

Next steps

Personalization

Webhooks

​Overview

​Prerequisites

​Basic bulk generation

​Step 1: Prepare your data

​Step 2: A simple generator

​Advanced: concurrency and failures

​Processing CSV files

​Database integration

​Webhook management for bulk jobs

​Catching up

​Performance tips

​Best practices

Store ids immediately

Use metadata

Never blind-retry creates

Stop on 401/402

​Next steps

Personalization

Webhooks

Overview

Prerequisites

Basic bulk generation

Step 1: Prepare your data

Step 2: A simple generator

Advanced: concurrency and failures

Processing CSV files

Database integration

Webhook management for bulk jobs

Catching up

Performance tips

Best practices

Next steps