​
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"
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"
    }
  }'
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"
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"
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);

​
Troubleshooting

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_
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
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
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.