TypeScript SDK

Installation

Install the SDK using npm or yarn:

npm

npm install @warps-studio/sdk

yarn

yarn add @warps-studio/sdk

pnpm

pnpm add @warps-studio/sdk

---

Quick Start

Get started with a simple text-to-image generation:

import { WarpsClient } from '@warps-studio/sdk';

// Initialize the client
const warps = new WarpsClient({
  apiKey: process.env.WARPS_API_KEY
});

// Generate an image
async function generateImage() {
  try {
    const result = await warps.generate({
      prompt: 'A modern office workspace with natural lighting',
      model: 'warp-v3-turbo',
      variations: 4
    });

    console.log('Generation ID:', result.id);
    console.log('Status:', result.status);

    // Wait for completion
    const completed = await warps.waitForCompletion(result.id);

    console.log('Images:', completed.images);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

generateImage();

---

Configuration

Configure the client with options for authentication, retries, and timeouts:

import { WarpsClient } from '@warps-studio/sdk';

const warps = new WarpsClient({
  apiKey: 'your_api_key_here',

  // Optional: Custom base URL
  baseURL: 'https://api.warps.studio/v1',

  // Optional: Timeout in milliseconds (default: 60000)
  timeout: 120000,

  // Optional: Maximum retry attempts (default: 3)
  maxRetries: 5,

  // Optional: Enable debug logging
  debug: true
});

---

Core Methods

generate()

Generate images from text prompts or reference images.

const result = await warps.generate({
  // Required
  prompt: 'A serene mountain landscape at sunset',

  // Optional parameters
  model: 'warp-v3-turbo',        // Model ID
  variations: 4,                  // Number of variations (1-16)
  width: 1024,                    // Width in pixels (512-2048)
  height: 1024,                   // Height in pixels (512-2048)
  brandKitId: 'bk_abc123',       // Brand kit to apply
  referenceImage: imageBuffer,    // Buffer or base64 string
  styleStrength: 0.75,           // Brand style adherence (0.0-1.0)
  seed: 42                        // Random seed for reproducibility
});

getGeneration()

Retrieve the status and results of a generation.

const generation = await warps.getGeneration('gen_7k3m9n2p4q5r6s8t');

console.log(generation.status);  // 'processing' | 'completed' | 'failed'
console.log(generation.images);  // Array of image URLs (when completed)

waitForCompletion()

Poll until a generation is complete (with exponential backoff).

const completed = await warps.waitForCompletion('gen_7k3m9n2p4q5r6s8t', {
  pollingInterval: 2000,  // Check every 2 seconds (default: 1000)
  timeout: 300000         // Timeout after 5 minutes (default: 120000)
});

// Download images
for (const image of completed.images) {
  console.log('Image URL:', image.url);
}

createBrandKit()

Create a brand kit for consistent generations.

const brandKit = await warps.brandKits.create({
  name: 'Acme Corp Brand',
  logo: logoBuffer,  // Buffer or base64 string
  colors: ['#FF5733', '#3498DB', '#2ECC71'],
  styleReferences: [ref1Buffer, ref2Buffer],
  description: 'Modern, clean design with bold colors'
});

console.log('Brand Kit ID:', brandKit.id);

listBrandKits()

List all brand kits in your account.

const brandKits = await warps.brandKits.list();

for (const kit of brandKits) {
  console.log(`${kit.name}: ${kit.id}`);
}

listModels()

Get available models and their capabilities.

const models = await warps.models.list();

for (const model of models) {
  console.log(`${model.name} (${model.id})`);
  console.log(`  Avg time: ${model.avgGenerationTime}s`);
  console.log(`  Max resolution: ${model.maxResolution}px`);
}

---

WarpsPipeline Class

Advanced usage with the WarpsPipeline class for complex workflows:

import { WarpsPipeline } from '@warps-studio/sdk';

const pipeline = new WarpsPipeline(warps);

// Chain multiple operations
const result = await pipeline
  .setPrompt('A futuristic city skyline')
  .setModel('warp-v3')
  .setDimensions(1920, 1080)
  .applyBrandKit('bk_abc123')
  .setVariations(8)
  .onProgress((status) => {
    console.log(`Progress: ${status}`);
  })
  .execute();

console.log('Generated images:', result.images);

---

Event Handlers

Listen to generation events for real-time updates:

const generation = await warps.generate({
  prompt: 'A modern workspace',
  model: 'warp-v3-turbo'
});

// Set up event handlers
warps.on('generation.progress', (data) => {
  console.log(`Generation ${data.id}: ${data.progress}%`);
});

warps.on('generation.completed', (data) => {
  console.log(`Generation ${data.id} completed!`);
  console.log('Images:', data.images);
});

warps.on('generation.failed', (data) => {
  console.error(`Generation ${data.id} failed:`, data.error);
});

// Wait for completion
await warps.waitForCompletion(generation.id);

---

Error Handling

The SDK provides detailed error types for robust error handling:

import {
  WarpsClient,
  WarpsAPIError,
  WarpsAuthenticationError,
  WarpsRateLimitError,
  WarpsTimeoutError
} from '@warps-studio/sdk';

const warps = new WarpsClient({ apiKey: 'your_api_key' });

try {
  const result = await warps.generate({
    prompt: 'A beautiful landscape'
  });
} catch (error) {
  if (error instanceof WarpsAuthenticationError) {
    console.error('Authentication failed. Check your API key.');
  } else if (error instanceof WarpsRateLimitError) {
    console.error('Rate limit exceeded. Retry after:', error.retryAfter);
  } else if (error instanceof WarpsTimeoutError) {
    console.error('Request timed out. Try increasing the timeout.');
  } else if (error instanceof WarpsAPIError) {
    console.error('API error:', error.statusCode, error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

---

TypeScript Support

The SDK is written in TypeScript and includes comprehensive type definitions:

import {
  WarpsClient,
  GenerateOptions,
  Generation,
  GenerationStatus,
  BrandKit
} from '@warps-studio/sdk';

const warps = new WarpsClient({ apiKey: 'your_api_key' });

// Full type safety
const options: GenerateOptions = {
  prompt: 'A modern office',
  model: 'warp-v3-turbo',
  variations: 4,
  width: 1024,
  height: 1024
};

const generation: Generation = await warps.generate(options);

// Type-safe status checks
if (generation.status === 'completed') {
  generation.images.forEach((image) => {
    console.log(image.url, image.width, image.height);
  });
}

---

Advanced Examples

Batch Generation with Progress Tracking

import { WarpsClient } from '@warps-studio/sdk';

const warps = new WarpsClient({ apiKey: process.env.WARPS_API_KEY });

async function batchGenerate(prompts: string[]) {
  const generations = await Promise.all(
    prompts.map(prompt =>
      warps.generate({
        prompt,
        model: 'warp-v3-turbo',
        variations: 2
      })
    )
  );

  console.log(`Started ${generations.length} generations`);

  // Wait for all to complete
  const results = await Promise.all(
    generations.map(gen => warps.waitForCompletion(gen.id))
  );

  return results.flatMap(result => result.images);
}

const prompts = [
  'A modern kitchen design',
  'A cozy living room',
  'A minimalist bedroom'
];

const allImages = await batchGenerate(prompts);
console.log(`Generated ${allImages.length} images total`);

Image-to-Image with Brand Kit

import { WarpsClient } from '@warps-studio/sdk';
import fs from 'fs';

const warps = new WarpsClient({ apiKey: process.env.WARPS_API_KEY });

async function transformWithBrand() {
  // Read reference image
  const referenceImage = fs.readFileSync('./input.jpg');

  // Generate with brand kit
  const result = await warps.generate({
    prompt: 'Transform this into our brand style, modern and clean',
    referenceImage: referenceImage,
    brandKitId: 'bk_abc123',
    styleStrength: 0.8,
    variations: 4
  });

  const completed = await warps.waitForCompletion(result.id);

  // Download results
  for (let i = 0; i < completed.images.length; i++) {
    const response = await fetch(completed.images[i].url);
    const buffer = await response.arrayBuffer();
    fs.writeFileSync(`./output_${i}.png`, Buffer.from(buffer));
  }

  console.log('Saved', completed.images.length, 'images');
}

transformWithBrand();

---

Resources

• GitHub Repository: github.com/warps-studio/sdk-ts
• NPM Package: npmjs.com/package/@warps-studio/sdk
• API Reference: View REST API docs
• Full Documentation: docs.warps.studio
• Example Projects: github.com/warps-studio/examples

---