Generate Your First Video

Prerequisites

Before starting, make sure you have:

✅ A Bluma account (sign up)
✅ An API key (get one here)
✅ Basic knowledge of making HTTP requests

Use a test API key for this tutorial - it’s free and generates watermarked videos perfect for learning!

Step 1: Choose a Template

First, let’s see what templates are available:

curl https://api.getbluma.com/api/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.getbluma.com/api/v1/templates', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data.templates);

import requests

response = requests.get(
    'https://api.getbluma.com/api/v1/templates',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
templates = response.json()['templates']
print(templates)

You’ll see a list of templates. For this tutorial, we’ll use consumerclub-discord-zoomed.

Step 2: Create the Video

Let’s generate a fun personality quiz video:

curl -X POST https://api.getbluma.com/api/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "consumerclub-discord-zoomed",
    "context": {
      "prompt": "Create a fun personality quiz about your favorite foods"
    }
  }'

const response = await fetch('https://api.getbluma.com/api/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    template_id: 'consumerclub-discord-zoomed',
    context: {
      prompt: 'Create a fun personality quiz about your favorite foods'
    }
  })
});

const result = await response.json();
console.log('Video ID:', result.id);

import requests

response = requests.post(
    'https://api.getbluma.com/api/v1/videos',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'template_id': 'consumerclub-discord-zoomed',
        'context': {
            'prompt': 'Create a fun personality quiz about your favorite foods'
        }
    }
)

result = response.json()
print('Video ID:', result['id'])

Response:

{
  "id": "batch_abc123xyz",
  "status": "queued",
  "template_id": "consumerclub-discord-zoomed",
  "created_at": "2025-11-03T10:30:00Z",
  "estimated_completion": "2025-11-03T10:32:00Z",
  "status_url": "/v1/videos/batch_abc123xyz",
  "credits_charged": 2
}

Save the id - you’ll need it to check the status and download your video!

Step 3: Check the Status

Video generation is asynchronous (takes 2-5 minutes). Poll the status endpoint:

curl https://api.getbluma.com/api/v1/videos/batch_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"

async function waitForVideo(videoId) {
  while (true) {
    const response = await fetch(
      `https://api.getbluma.com/api/v1/videos/${videoId}`,
      {
        headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
      }
    );

    const video = await response.json();
    console.log(`Status: ${video.status} (${video.progress || 0}%)`);

    if (video.status === 'completed') {
      return video;
    }

    if (video.status === 'failed') {
      throw new Error('Video generation failed');
    }

    // Wait 5 seconds before checking again
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

const video = await waitForVideo('batch_abc123xyz');
console.log('Video ready:', video.url);

import time

def wait_for_video(video_id):
    while True:
        response = requests.get(
            f'https://api.getbluma.com/api/v1/videos/{video_id}',
            headers={'Authorization': 'Bearer YOUR_API_KEY'}
        )

        video = response.json()
        print(f"Status: {video['status']} ({video.get('progress', 0)}%)")

        if video['status'] == 'completed':
            return video

        if video['status'] == 'failed':
            raise Exception('Video generation failed')

        time.sleep(5)

video = wait_for_video('batch_abc123xyz')
print('Video ready:', video['url'])

Status progression:

queued → processing → completed ✓

Don’t poll too frequently! Check every 5-10 seconds to avoid rate limits. Better yet, use webhooks for production.

Step 4: Download Your Video

Once status is completed, get the download URL:

curl https://api.getbluma.com/api/v1/videos/batch_abc123xyz/download \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  `https://api.getbluma.com/api/v1/videos/${videoId}/download`,
  {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);

const { download_url } = await response.json();

// Download the video
const videoResponse = await fetch(download_url);
const videoBlob = await videoResponse.blob();

// Save to file (Node.js)
const fs = require('fs');
const buffer = await videoBlob.arrayBuffer();
fs.writeFileSync('my-video.mp4', Buffer.from(buffer));

response = requests.get(
    f'https://api.getbluma.com/api/v1/videos/{video_id}/download',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

download_url = response.json()['download_url']

# Download the video
video_response = requests.get(download_url)
with open('my-video.mp4', 'wb') as f:
    f.write(video_response.content)

print('Video saved to my-video.mp4')

Response:

{
  "download_url": "https://cdn.getbluma.com/videos/batch_abc123xyz.mp4?signed=...",
  "expires_at": "2025-11-03T11:31:45Z"
}

Download URLs expire in 1 hour. Download your video before expiration!

Complete Example

Here’s the full workflow in one script:

const BLUMA_API_KEY = process.env.BLUMA_API_KEY;
const BASE_URL = 'https://api.getbluma.com/api/v1';

async function generateVideo() {
  // 1. Create video
  console.log('Creating video...');
  const createRes = await fetch(`${BASE_URL}/videos`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${BLUMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: 'consumerclub-discord-zoomed',
      context: {
        prompt: 'Create a fun personality quiz about food'
      }
    })
  });

  const { id } = await createRes.json();
  console.log('Video ID:', id);

  // 2. Wait for completion
  console.log('Waiting for video to complete...');
  let video;
  while (true) {
    const statusRes = await fetch(`${BASE_URL}/videos/${id}`, {
      headers: { 'Authorization': `Bearer ${BLUMA_API_KEY}` }
    });

    video = await statusRes.json();
    console.log(`Status: ${video.status} (${video.progress || 0}%)`);

    if (video.status === 'completed') break;
    if (video.status === 'failed') throw new Error('Generation failed');

    await new Promise(r => setTimeout(r, 5000));
  }

  // 3. Download video
  console.log('Downloading video...');
  const downloadRes = await fetch(`${BASE_URL}/videos/${id}/download`, {
    headers: { 'Authorization': `Bearer ${BLUMA_API_KEY}` }
  });

  const { download_url } = await downloadRes.json();
  console.log('Video URL:', download_url);

  return download_url;
}

generateVideo().catch(console.error);

import os
import time
import requests

BLUMA_API_KEY = os.getenv('BLUMA_API_KEY')
BASE_URL = 'https://api.getbluma.com/api/v1'
HEADERS = {
    'Authorization': f'Bearer {BLUMA_API_KEY}',
    'Content-Type': 'application/json'
}

def generate_video():
    # 1. Create video
    print('Creating video...')
    response = requests.post(
        f'{BASE_URL}/videos',
        headers=HEADERS,
        json={
            'template_id': 'consumerclub-discord-zoomed',
            'context': {
                'prompt': 'Create a fun personality quiz about food'
            }
        }
    )

    video_id = response.json()['id']
    print(f'Video ID: {video_id}')

    # 2. Wait for completion
    print('Waiting for video to complete...')
    while True:
        response = requests.get(
            f'{BASE_URL}/videos/{video_id}',
            headers=HEADERS
        )

        video = response.json()
        print(f"Status: {video['status']} ({video.get('progress', 0)}%)")

        if video['status'] == 'completed':
            break
        if video['status'] == 'failed':
            raise Exception('Generation failed')

        time.sleep(5)

    # 3. Download video
    print('Getting download URL...')
    response = requests.get(
        f'{BASE_URL}/videos/{video_id}/download',
        headers=HEADERS
    )

    download_url = response.json()['download_url']
    print(f'Video URL: {download_url}')

    return download_url

if __name__ == '__main__':
    generate_video()

Troubleshooting

401 Authentication Error

Problem: Invalid or missing API keySolution:

Verify your API key is correct
Check it’s in the Authorization header: Bearer YOUR_KEY
Ensure it starts with bluma_live_ or bluma_test_

402 Insufficient Credits

Problem: Not enough credits for video generationSolution:

Check balance: GET /v1/credits/balance
Use a test key (free, unlimited)
Purchase more credits or upgrade plan

Video stuck in 'processing'

Problem: Video taking longer than expectedSolution:

Complex templates can take 5-10 minutes
Check status hasn’t changed to ‘failed’
Set up webhooks instead of polling

Download URL expired

Problem: Waited too long to downloadSolution:

Request a new download URL (doesn’t cost credits)
Download immediately after getting URL
Store videos in your own storage if needed long-term

Next Steps

Set Up Webhooks

Stop polling - get notified when videos are ready

Explore Templates

Try different video styles and templates

Production Setup

Switch from test to production mode

Best Practices

Build robust production integrations

Congratulations! 🎉

You’ve successfully generated your first AI video with the Bluma API. The same pattern applies to all templates - just change the template_id and customize the context.

​Prerequisites

​Step 1: Choose a Template

​Step 2: Create the Video

​Step 3: Check the Status

​Step 4: Download Your Video

​Complete Example

​Troubleshooting

​Next Steps

Set Up Webhooks

Explore Templates

Production Setup

Best Practices

​Congratulations! 🎉

Prerequisites

Step 1: Choose a Template

Step 2: Create the Video

Step 3: Check the Status

Step 4: Download Your Video

Complete Example

Troubleshooting

Next Steps

Congratulations! 🎉