​
Official SDKs

Bluma provides official SDKs for popular programming languages, offering type-safe, idiomatic interfaces to the Bluma API.

TypeScript/Node.js

Type-safe SDK for Node.js and TypeScript

Python

Pythonic SDK with async support

​
Why Use an SDK?

Type Safety

Get autocomplete and type checking in your IDE

Error Handling

Built-in retry logic and error handling

Convenience

Simplified API with helper methods

Webhooks

Easy webhook signature verification

​
Quick Comparison

FeatureTypeScriptPython
Installationnpm install @stephen_turtles/bluma-sdkpip install bluma
Type Safety✅ Full TypeScript support✅ Type hints
Async/Await✅ Promise-based✅ async/await
Webhooks✅ Signature verification✅ Signature verification
Streaming⏳ Coming soon⏳ Coming soon
Retry Logic✅ Exponential backoff✅ Exponential backoff

​
Installation

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

​
Basic Usage

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);

​
Features

​
Automatic Retries

All SDKs include automatic retry logic with exponential backoff: 
const bluma = new Bluma({
  apiKey: process.env.BLUMA_API_KEY,
  maxRetries: 3,
  retryDelay: 1000 // milliseconds
});

// Automatically retries on 5xx errors and network failures
const video = await bluma.videos.create({...});

​
Webhook Verification

Easy webhook signature verification: 
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');
    }
  }
);

​
Pagination

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

​
Type Safety

// 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');

​
Error Handling

All SDKs provide structured error types: 
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);
  }
}

​
Need Help?

TypeScript SDK

Complete TypeScript/Node.js SDK documentation

Python SDK

Complete Python SDK documentation

API Reference

REST API reference (SDK-agnostic)

​
Changelog

​
v1.0.0

  • Initial release
  • Support for all core endpoints
  • Webhook verification
  • TypeScript and Python SDKs