API docs

Generate personalized videos from AI Studio.

Use the BHuman API to render personalized videos from AI Studio campaigns, video instances, and Speakeasy imports. Send recipient rows, optional assets, and a callback URL; receive share URLs, MP4 downloads, thumbnails, GIF previews, status, and error details.

Start quickstart GitHub README Swagger UI

Do not use old mode language

Older BHuman articles and videos may use legacy setup terminology. For new work, use AI Studio templates, campaigns, variable mapping, Speakeasy imports, API generation, callbacks, and generated assets.

Live reference

Swagger is the endpoint-level source of truth.

This page explains the practical integration model. For exact request and response schemas, use the live Swagger UI or OpenAPI JSON.

Open Swagger OpenAPI JSON

Integration model

The API sits after template setup and before delivery.

Prepare the source

Create or upload a base video in AI Studio, or generate a presenter in Speakeasy and import it into AI Studio.

Mark variables

Define the text, links, images, or background assets that should change for each recipient row.

Trigger generation

Use a campaign, video instance, Zapier/Pabbly payload, Leadr payload, or the API endpoint wired to your workflow.

Collect assets

Use callbacks or polling to collect share URLs, MP4 downloads, thumbnails, GIFs, status, and failure details.

Quickstart

Campaign generation request

1. Create or choose a campaign. Copy the campaign ID from AI Studio or the campaign URL.
2. Generate API keys. Open Settings, then API keys. Use the key ID and secret for Basic Authentication.
3. Send ordered rows. The variables array defines column order. Every row in names must follow that same order.
4. Handle completion. Provide a callback_url for async delivery, or poll the generated video endpoints.

Campaign generation

cURL

curl -X POST "https://studio.bhuman.ai/api/ai_studio/pipeline/campaign" \
  -H "Authorization: Basic $BHUMAN_BASIC_AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "YOUR_CAMPAIGN_ID",
    "variables": ["first_name", "company", "cta_url"],
    "names": [
      ["Alex", "ExampleCo", "https://example.com/start"],
      ["Jordan", "Sample Labs", "https://example.com/book"]
    ],
    "callback_url": "https://yourapp.com/bhuman/callback"
  }'

Authentication

Use Basic Authentication with an API key.

Generate an API key in BHuman from Settings, then API keys. Combine the key ID and secret with a colon, Base64 encode the result, and send it in the Authorization header.

Authorization header

Header

api_key_id:api_key_secret -> base64

Authorization: Basic <encoded_value>

Request contract

Core generation fields

Field

Type

Required

Notes

campaign_id

String

Campaign

AI Studio campaign ID for campaign and pipeline generation.

video_instance_id

String

Instance

AI Studio video instance ID for direct try_sample generation.

variables

String[]

Yes

Variable names in the same order as each recipient row.

names

String[][]

Yes

Recipient rows. Each row maps to variables by position.

callback_url

String

BHuman posts completion details for generated videos.

assets

String[][]

Row-specific URLs for images, sites, videos, or background media.

backgrounds

Background[]

Timed background segments for links, sites, LinkedIn, or chroma scenes.

enable_lipsync

Boolean

Enable lip sync when supported by the template and generation mode.

enable_subtitles

Boolean

Request subtitles when supported by the template.

Recipient row rule

Treat variables as the header row and names as data rows. The API maps values by position, not by object key.

variables[0] = first_name

names[0][0] = Alex

variables[1] = company

names[0][1] = ExampleCo

Pabbly-style payload

JSON

{
  "campaign_id": "YOUR_CAMPAIGN_ID",
  "variables": {
    "first_name": "Alex",
    "company": "ExampleCo",
    "cta_url": "https://example.com/start"
  },
  "callback_url": "https://yourapp.com/bhuman/callback"
}

Accepted response

Generation requests return accepted IDs.

A generation request accepts work for asynchronous rendering. Store the returned IDs, then reconcile them with callbacks or polling results.

Accepted response

JSON

{
  "code": 200,
  "result": [
    "c10ee155-6202-4cec-9a40-dde536e2ab4e"
  ]
}

Completion

Completion payloads return render assets.

BHuman can send one POST callback per generated video. Store the generation ID, then use the media fields your workflow needs.

Generation ID.

status

Processing, succeeded, failed, or related render state.

share_url

Hosted video page or share destination when available.

url

Downloadable MP4 URL.

thumbnail

Generated thumbnail image URL.

gif

Generated GIF preview URL.

message

Failure or processing detail when available.

execution_name

Pipeline execution identifier when available.

row_index

Recipient row index when available.

Completion example

JSON

{
  "id": "c10ee155-6202-4cec-9a40-dde536e2ab4e",
  "status": "succeeded",
  "share_url": "https://videos.bhuman.ai/video/...",
  "url": "https://assets.bhuman.ai/generated-video.mp4",
  "thumbnail": "https://assets.bhuman.ai/thumb.jpg",
  "gif": "https://assets.bhuman.ai/preview.gif"
}

Dynamic backgrounds

Pass row-specific websites, images, or videos.

Dynamic backgrounds let a generated video show a website, image, video, LinkedIn page, product page, landing page, or other URL behind or around the presenter. Each row in assets lines up with the matching row in names.

Dynamic background payload

JSON

{
  "variables": ["first_name", "company"],
  "names": [
    ["Alex", "ExampleCo"],
    ["Jordan", "Sample Labs"]
  ],
  "assets": [
    ["https://example.com/product", "https://example.com/alex-demo.mp4"],
    ["https://example.com/pricing", "https://example.com/jordan-demo.mp4"]
  ],
  "backgrounds": [
    {
      "name": "product_page",
      "start": 0,
      "end": 3,
      "kind": "site",
      "config": {
        "mode": "circle",
        "position": "bottom-right",
        "scale": 0.4
      }
    },
    {
      "name": "demo_video",
      "start": 3,
      "end": -1,
      "kind": "link",
      "config": {
        "mode": "chroma",
        "color": "00FF00"
      }
    }
  ]
}

Speakeasy import

Import generated presenters into AI Studio.

Use Speakeasy to generate the presenter and voice. Import the project into AI Studio before adding recipient variables, campaign data, or API-triggered rendering.

Import Speakeasy project

cURL

curl -X POST "https://studio.bhuman.ai/api/ai_studio/speakeasy_projects/import" \
  -H "Authorization: Basic $BHUMAN_BASIC_AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "SPEAKEASY_PROJECT_ID",
    "workspace_id": "OPTIONAL_WORKSPACE_ID"
  }'

Endpoint reference

Core endpoint groups

For exact schemas, optional fields, and operations not summarized here, open Swagger UI.

OpenAPI JSON

Pipeline generation

Recommended endpoints for CRM, form, workflow, and automation-triggered renders.

POST

https://studio.bhuman.ai
/api/ai_studio/pipeline/campaign

Generate campaign videos from ordered variables and recipient rows.

POST

https://studio.bhuman.ai
/api/ai_studio/pipeline/zapier

Generate videos from the structured automation payload shape.

POST

https://studio.bhuman.ai
/api/ai_studio/pipeline/pabbly

Generate videos from a simple object-style payload for webhook builders.

POST

https://studio.bhuman.ai
/api/ai_studio/pipeline/leadr

Generate videos from Leadr pipeline data.

Templates and campaigns

Create, read, update, and list AI Studio video instances and campaigns.

GET

https://studio.bhuman.ai
/api/ai_studio/video_instances

List AI Studio video instances available to the authenticated user.

GET

https://studio.bhuman.ai
/api/ai_studio/video_instance?id={video_instance_id}

Fetch one AI Studio video instance.

POST

https://studio.bhuman.ai
/api/ai_studio/try_sample

Generate videos directly from a video instance ID.

GET

https://studio.bhuman.ai
/api/ai_studio/campaigns

List campaigns available to the authenticated user.

GET

https://studio.bhuman.ai
/api/ai_studio/campaign?id={campaign_id}

Fetch one AI Studio campaign.

Generated results

Poll generated video status and assets when callbacks are not enough.

GET

https://studio.bhuman.ai
/api/ai_studio/generated_video_by_video_instance_id?video_instance_id={video_instance_id}

List generated videos for a video instance.

GET

https://studio.bhuman.ai
/api/ai_studio/generated_video_by_campaign_id?campaign_id={campaign_id}

List generated videos for a campaign.

GET

https://studio.bhuman.ai
/api/ai_studio/generated_video_by_id?id={generation_id}

Fetch one generated video result by generation ID.

GET

https://studio.bhuman.ai
/api/ai_studio/get_generated_video

Fetch generated videos for the authenticated account context.

Speakeasy imports

Move generated presenter projects into AI Studio for personalization.

GET

https://studio.bhuman.ai
/api/ai_studio/speakeasy_projects

List Speakeasy projects available for import.

POST

https://studio.bhuman.ai
/api/ai_studio/speakeasy_projects/import

Import a Speakeasy project into AI Studio as a video instance.

Webhooks and previews

Configure saved webhooks, preview videos, and receive render pipeline callbacks.

GET

https://studio.bhuman.ai
/api/ai_studio/webhook

List saved campaign webhooks.

POST

https://studio.bhuman.ai
/api/ai_studio/webhook

Create a saved campaign webhook.

POST

https://studio.bhuman.ai
/api/ai_studio/videos_preview

Create a video preview request.

POST

https://studio.bhuman.ai
/api/ai_studio/pipeline/webhook

Internal render pipeline callback endpoint. Do not call this from CRM integrations.

Production checklist

Before you turn on an automated workflow

Use HTTPS callback URLs that can accept repeated delivery attempts.
Store generation IDs so callbacks and polling responses can be reconciled.
Keep variables stable after a campaign is wired into a production workflow.
Send row-specific assets in the same order as recipient rows.
Treat generated media URLs as outputs from an async render job, not as immediate inline responses.
Use the Swagger UI for the latest endpoint-level schema details before launching a custom integration.

Need implementation help?

Contact us with the workflow you are building and the team will help map it to the right campaign, template, callback, or landing page setup.