CSV vs. API for Video Personalization: How to Choose

The short answer

Choose CSV for a batch list, a quick test, or a one-time campaign. Choose the API when your product or backend needs to control video generation and delivery. In either case, BHuman uses recipient data to fill variables in an existing AI Studio template or campaign; the API is currently in beta and has production-use restrictions.

At a glance

The main difference is how recipient data gets into a campaign and who controls generation. CSV is a file-based workflow; the API is an integration path for product- or backend-owned workflows. Both require a ready template, mapped variables, and valid values for each recipient.

• CSV: Best suited to batch generation, quick testing, and one-time lists. Upload the spreadsheet, preview rows, then map its headers to template variables.
• API: Best suited to a product, CRM, backend, or form handler that needs direct control of generation. Send recipient values in an API request.
• CSV workflow: BHuman’s campaign setup supports CSV or Excel; spreadsheet headers become mapping options.
• API workflow: Requests use ordered variable names and recipient rows, and generation runs asynchronously.

When CSV is the better fit

Use CSV when you already have a list to process and want to review the data before generating. BHuman’s data-source guidance recommends CSV or Excel for batch generation, quick tests, and one-time lists.

• Use one column per variable, keep header names stable, and include a value for every mapped variable in each row.
• Upload the file, preview the rows, and map each column to the corresponding template variable.
• Try a small test file before uploading a full list.
• If you use background mode, include the required background asset URLs in the data.

When the API is the better fit

Use the API when your product or backend needs to control generation and delivery, rather than relying on a manually uploaded file. API requests can generate from an owned campaign and return generation IDs that you can use to track results.

• Prepare an AI Studio template and campaign before making a request; the REST API does not create a Speakeasy presenter video from a prompt.
• Send the campaign ID, ordered variable names, and recipient rows with matching values. Start with one recipient.
• Save returned generation IDs and check the individual results: acceptance queues the work but does not mean the video is ready.
• Do not automatically retry a paid generation POST after a timeout or lost response. Check the campaign or contact support if the outcome is uncertain.

Check API access before planning a launch

BHuman’s REST integration is in beta, and production release verification is on hold pending qualification. Fresh-account access and several other areas are not yet fully qualified. Confirm your use case with support before production use and do not assume that having an API key guarantees access or unlimited generation.

API generation uses video credits. Review your plan and available balance, and use the app’s estimate for the campaign’s exact cost. The documented API does not have a free sandbox or a separate latency SLA.

A practical decision rule

Start with CSV if a person can prepare and upload the recipient list for each campaign. Consider the API if generation needs to be initiated and tracked from your own product or backend. That is a workflow choice, not a promise that one option is faster or produces better videos.

• Pick CSV for a list you can prepare, preview, and upload as a batch.
• Pick the API when you need direct programmatic control and can handle credentials, asynchronous results, and beta access requirements.
• If you are unsure, test the campaign with a small CSV first; move to an API integration only if your workflow needs backend-controlled generation.

Example: the same template, two workflows

For example, imagine a template with a first-name variable. With CSV, put each recipient’s replacement name in a column headed `first_name`, upload the file, preview its rows, and map that column to the variable. With the API, send `first_name` as the variable and each recipient’s name as the matching row value. In both cases, send the replacement value only—not fixed words already included in the template.