Generate personalized videos from your own workflow.

The guide on this page explains the integration model. Swagger is the live endpoint reference for schemas, optional fields, and response models.

BHuman API keys use Basic Authentication. Generate the client ID and client secret in BHuman Settings, then send the base64-encoded credentials in the Authorization header.

export BHUMAN_API_KEY_ID="your_api_key_id"
export BHUMAN_API_KEY_SECRET="your_api_key_secret"

export BHUMAN_BASIC_AUTH=$(printf "%s:%s" "$BHUMAN_API_KEY_ID" "$BHUMAN_API_KEY_SECRET" | base64)

1. 01

   Create an AI Studio template

   Record, upload, or import a video and mark the variables that should be personalized.
2. 02

   Create or identify the campaign

   Use the campaign ID when generation should follow campaign settings such as mapped variables and background configuration.
3. 03

   Send recipient rows

   Send variables and names in matching order. Each row in names creates one generated video.
4. 04

   Collect generated assets

   Use callbacks or polling endpoints to collect status, share URL, MP4 URL, thumbnail, and GIF preview.

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"
  }'

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

campaign_id

AI Studio campaign ID for campaign-based generation.

video_instance_id

AI Studio template ID for direct sample generation.

variables

Variable names in the same order as the values in each recipient row.

names

Recipient value rows. Each nested array maps by position to variables.

callback_url

HTTPS URL that receives completion details after asynchronous rendering.

assets

Row-by-row background asset URL matrix. Each assets row maps to the matching names row, and each URL column maps to the matching backgrounds entry.

backgrounds

Dynamic background definitions for images, websites, or LinkedIn sources used during campaign generation.

enable_lipsync

Boolean option for templates and generation modes that support lip sync.

Dynamic background replacement works through the campaign API, not only through the AI Studio interface. Send assets and backgrounds with POST /api/ai_studio/pipeline/campaign when each recipient needs a different image or page behind the speaker.

• The number of assets rows should match the number of names rows.
• Each assets row can contain one or more URLs, ordered to match the backgrounds array.
• Use kind values such as link, site, or linkedin depending on the background source configured for the campaign.
• For property or listing videos, send the per-recipient listing image URL in assets and keep the campaign template locked to the intended background layer.

{
  "campaign_id": "YOUR_CAMPAIGN_ID",
  "variables": ["first_name", "property_address"],
  "names": [
    ["Alex", "123 Main St"],
    ["Jordan", "9 Oak Ave"]
  ],
  "assets": [
    ["https://cdn.example.com/alex-listing.jpg"],
    ["https://cdn.example.com/jordan-listing.jpg"]
  ],
  "backgrounds": [
    {
      "name": "listing_photo",
      "kind": "link",
      "start": 0,
      "end": -1,
      "config": {
        "mode": "none",
        "scale": 0.42,
        "position": "bottom-right",
        "brightness": 1
      }
    }
  ],
  "callback_url": "https://yourapp.com/bhuman/callback"
}

id

Generated video ID.

status

Render state such as preparing, queued, processing, succeeded, failed, or completed.

share_url

Hosted video page or share destination returned by polling endpoints when available.

url

Downloadable MP4 URL.

thumbnail

Generated thumbnail image URL.

gif

Generated GIF preview URL.

message

Failure or processing detail when available. Show customers a support-safe code instead of raw render messages.

execution_name

Pipeline execution identifier when available.

row_index

The source row associated with the generated video.

Pipeline generation

POST /api/ai_studio/pipeline/campaign, /pipeline/zapier, /pipeline/pabbly, and /pipeline/leadr.

Direct template generation

POST /api/ai_studio/try_sample when a workflow targets a video_instance_id directly.

Templates and campaigns

GET video instances, one video instance, campaigns, and one campaign.

Generated results

GET generated videos by campaign ID, video instance ID, or generation ID.

Speakeasy imports

GET importable Speakeasy projects and POST a project import into AI Studio.

Saved webhooks

GET and POST reusable webhook destinations in AI Studio settings.

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

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"
  }'

Use callbacks when your workflow needs to react as soon as rendering finishes. Store the generated video ID returned by the initial request so callback payloads can be matched to your records.

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

{
  "id": "c10ee155-6202-4cec-9a40-dde536e2ab4e",
  "campaign_id": "YOUR_CAMPAIGN_ID",
  "status": "failed",
  "video_url": "",
  "url": "",
  "thumbnail": "",
  "gif": "",
  "campaign_result_id": null
}

• Use HTTPS callback URLs.
• Allow duplicate delivery handling in your receiver.
• Store the generated video ID, campaign ID, and final media URLs before triggering downstream automation.
• Poll generated video endpoints when callbacks are not configured or when a backfill is needed.

400

Valid JSON that is not usable for the campaign, such as a variable count that does not match recipient values.

401

Missing, invalid, or unauthorized Basic Authentication credentials.

422

Request body or query shape could not be parsed, such as a malformed UUID or missing required field.

Accepted then failed

The generation was queued successfully, but asynchronous rendering later failed. Handle this through callback or polling status.

• Generation is asynchronous. A successful request means the rows were accepted for rendering, not that the videos are ready inline.
• Test with two or three rows before submitting a large render batch.
• Campaign generation currently accepts up to 2,000 recipient rows per request.
• Before sending 50 or more concurrent generations, test the exact campaign, variable set, and asset sizes that will be used in production.
• There is no separate public sandbox, fixed public per-minute rate limit, or guaranteed render-latency SLA published for the API.
• Use API keys from BHuman Settings for evaluation and coordinate production volume expectations with BHuman support or your account team.

• If a generated video needs an AI disclosure, place the disclosure line in the AI Studio template as fixed copy rather than as a recipient variable.
• The API cannot remove fixed template copy during generation. Control template and campaign editing permissions so production disclosure text is not accidentally changed.
• Send only the recipient fields required for the video, such as first name, address, listing image URL, and CTA URL.
• Keep API keys and recipient data server-side. Do not place secrets or private recipient data in browser-side JavaScript.
• For retention, DPA, and account-specific privacy requirements, coordinate with BHuman support or your account team before launch.

• Test with two or three rows before submitting a large render batch.
• Keep variable names stable once a campaign, Zapier, Pabbly, or API workflow is live.
• Send asset rows in the same order as recipient rows.
• Treat generated media as asynchronous outputs, not immediate inline responses.
• Use Swagger for the latest endpoint-level request and response schema.