How to Plan a Personalized Video Campaign With an API

Plan the campaign before you send API requests

To plan a personalized video campaign with an API, first define who will receive each video, what recipient details will personalize it, and what action you want viewers to take. Then prepare a ready video template and campaign, map your data fields, test one recipient, and only then plan a larger rollout.

With BHuman, the API generates personalized videos from an existing AI Studio template or campaign; it does not create a Speakeasy presenter video from a prompt. REST API access is in beta, and production REST credential provisioning is on hold until qualification is complete. Confirm your use case with support before production use.

1. Define the audience, message, and success criteria

Write down the audience and the purpose of the campaign before building your data flow. Decide what the video should say to each recipient and what you want them to do next. These are planning choices, not API settings.

Keep the personalized details limited to fields that genuinely need to vary by recipient. For example, imagine a sales team using a first name in a recorded greeting while keeping the rest of its message consistent. Treat that as a hypothetical example, not a promised campaign result.

• Audience: who should receive a video?
• Purpose: what should the video help the recipient understand or do?
• Personalized fields: which details change from one recipient to another?
• Delivery plan: how will your team use the finished video?

2. Prepare a ready template and campaign

Before using the API, prepare your source video, set up its variables in AI Studio, and create a campaign from that template. The API personalizes an existing campaign; it is not the step that creates the template.

For a first test, keep the template simple. BHuman’s quickstart uses a campaign with one variable named first_name and one recipient row. The campaign must be yours, and you must have permission to use its media.

3. Match recipient data to template variables

Plan one data field for each variable in the template. The API request uses an ordered variables array and a names matrix: each nested row supplies the values for one recipient, in the same order as the variables.

Send only the replacement text for a variable. If the template already says “Hi” before a first-name variable, send a name such as “Alex,” not the full greeting. Check that every row has a value for every mapped variable.

• Keep the field names and their order consistent with the template.
• Review recipient values for missing fields and unwanted surrounding text.
• Start with one recipient row before preparing a larger batch.

4. Choose how the API fits your workflow

The API is intended for cases where your product, CRM, backend, or form handler controls generation. If you only need a manual batch, CSV or Excel may be a better fit; BHuman also documents Zapier, Pabbly, and Leadr as other data-source options.

Choose the route that matches who should control generation. Avoid adding integrations or background assets to the first test unless your use case needs them.

• API: your product or backend controls generation and delivery.
• CSV or Excel: you want to test or generate a manual batch.
• Zapier: an event in a connected app should trigger generation.
• Pabbly: a workflow sends object-style variable data.
• Leadr: you are planning a LinkedIn-style outreach workflow.

5. Check beta access, credentials, and credits

BHuman’s REST API is in beta, and the documentation says production REST release verification is on hold. Confirm eligibility with support before production use. A ready campaign alone does not establish that your account can use the API.

For eligible access, the documented credential path is Settings → API Keys → Generate new key, which provides a Client ID and Client Secret. The REST API uses HTTP Basic Authentication. Keep both values in private environment variables or a secret manager; never put them in browser code, committed files, screenshots, or shared chat.

Review Plan & usage and the app’s campaign cost estimate before generation. API generation consumes video credits, and account entitlements and available credits apply. There is no documented free API sandbox or separate API latency SLA.

6. Test one recipient and plan for asynchronous results

BHuman’s documented first API test sends one recipient to an existing campaign. Specify the campaign ID, variables, names, and generation mode. The documented modes are keep_original, which retains the original recording outside personalized sections, and full_script, which regenerates the full spoken script.

A successful submission queues work; it does not mean the video is ready to watch. Save each returned generation ID, then check that individual result until its status is succeeded and a video URL is available. Review the returned result before using the media.

• Keep Original supports up to 100 personalized sections per video, each no longer than 10 seconds.
• Campaign generation accepts up to 2,000 recipient rows per request, but the API guide recommends beginning with one.
• If you use background assets, keep their rows aligned with the recipient rows.

7. Prevent duplicate work and unsafe retries

Plan your error handling before scaling beyond a test. The documented REST examples do not provide an idempotency key, so repeating a POST can create additional work and charges. Disable automatic POST retries.

If a submission times out or its response is lost, do not blindly submit it again. Check the campaign in the app and contact support if the outcome is uncertain. Once you have a generation ID, repeat status checks rather than resubmitting the generation request.

For larger batches, use modest concurrency and bounded polling with backoff. The documentation does not publish a fixed REST requests-per-minute guarantee.

Campaign planning checklist

Use this checklist to review the plan before making a paid API submission. It helps catch campaign and data issues, but does not replace account eligibility or credit checks.

• Define the audience, message, and intended next action.
• Prepare a source video, template variables, and an owned AI Studio campaign.
• Confirm the API is appropriate for your workflow and your use case is eligible for REST access.
• Match variable order to the values in each recipient row; remove fixed words from replacement values.
• Review available credits and the estimated campaign cost.
• Test one recipient, save the returned generation ID, and check for a completed result.
• Disable automatic POST retries and decide how your team will handle uncertain submissions.