SDK Overview

npm install @stephen_turtles/bluma-sdk
# or
yarn add @stephen_turtles/bluma-sdk
# or
pnpm add @stephen_turtles/bluma-sdk

pip install bluma

# or with async support
pip install bluma[async]

import { Bluma } from '@stephen_turtles/bluma-sdk';

const bluma = new Bluma({
  apiKey: process.env.BLUMA_API_KEY
});

// Generate a video
const video = await bluma.videos.create({
  templateId: 'rick-morty-explainer',
  context: {
    prompt: 'Create a funny dialogue about programmers'
  }
});

console.log('Video ID:', video.id);

// Wait for completion
const completed = await bluma.videos.waitFor(video.id);
console.log('Download URL:', completed.url);

from bluma import Bluma

bluma = Bluma(api_key=os.getenv('BLUMA_API_KEY'))

# Generate a video
video = bluma.videos.create(
    template_id='rick-morty-explainer',
    context={
        'prompt': 'Create a funny dialogue about programmers'
    }
)

print(f'Video ID: {video.id}')

# Wait for completion
completed = bluma.videos.wait_for(video.id)
print(f'Download URL: {completed.url}')

import { Bluma } from '@stephen_turtles/bluma-sdk';
import express from 'express';

const app = express();

app.post('/webhooks/bluma',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-bluma-signature'] as string;
    const payload = req.body.toString();

    try {
      const event = Bluma.webhooks.verify(
        payload,
        signature,
        process.env.BLUMA_WEBHOOK_SECRET
      );

      console.log('Verified event:', event.type);
      res.sendStatus(200);
    } catch (error) {
      console.error('Invalid signature');
      res.status(401).send('Unauthorized');
    }
  }
);

from bluma import Bluma
from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks/bluma', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Bluma-Signature')
    payload = request.get_data()

    try:
        event = Bluma.webhooks.verify(
            payload,
            signature,
            os.getenv('BLUMA_WEBHOOK_SECRET')
        )

        print(f'Verified event: {event.type}')
        return '', 200
    except Exception as error:
        print('Invalid signature')
        return 'Unauthorized', 401

// Async iteration
for await (const video of bluma.videos.list({ limit: 50 })) {
  console.log(video.id, video.status);
}

# Simple iteration
for video in bluma.videos.list(limit=50):
    print(video.id, video.status)

// Full TypeScript support
import { Video, Template, VideoStatus } from '@stephen_turtles/bluma-sdk';

const video: Video = await bluma.videos.get('batch_abc123');

// Type checking
if (video.status === 'completed') { // VideoStatus enum
  console.log(video.url); // Type: string | undefined
}

// Autocomplete for template IDs
const template: Template = await bluma.templates.get('rick-morty-explainer');

# Python type hints
from bluma import Bluma, Video, Template, VideoStatus

video: Video = bluma.videos.get('batch_abc123')

# Type checking with IDE support
if video.status == VideoStatus.COMPLETED:
    print(video.url)  # Optional[str]

template: Template = bluma.templates.get('rick-morty-explainer')

import { BlumaError, RateLimitError, InsufficientCreditsError } from '@stephen_turtles/bluma-sdk';

try {
  const video = await bluma.videos.create({...});
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof InsufficientCreditsError) {
    console.log('Out of credits!');
    // Notify user to purchase more
  } else if (error instanceof BlumaError) {
    console.error('API error:', error.message, error.status);
  } else {
    console.error('Network error:', error);
  }
}

from bluma import (
    BlumaError,
    RateLimitError,
    InsufficientCreditsError
)

try:
    video = bluma.videos.create(...)
except RateLimitError as error:
    print(f'Rate limited. Retry after {error.retry_after} seconds')
except InsufficientCreditsError:
    print('Out of credits!')
except BlumaError as error:
    print(f'API error: {error.message} (status: {error.status})')
except Exception as error:
    print(f'Network error: {error}')