PixelLab JavaScript SDK

This JavaScript/Node.js client simplifies interaction with the PixelLab developer API.

Create characters and items, animate them, and generate rotated views. Useful for game development and other pixel art projects.

For questions or discussions, join us on Discord.

Features

• Generate Image (Pixflux): Create characters, items, and environments from text descriptions
• Generate Image (Bitforge): Use reference images to match a specific art style
• Animation with Skeletons: Animate bi-pedal and quadrupedal characters and monsters with skeleton-based animations
• Animation with Text: Animate with text prompts
• Inpainting: Edit existing pixel art
• Rotation: Generate rotated views of characters and objects

With much more functionality coming soon.

Installation

npm install @pixellab-code/pixellab

Or install globally for CLI usage:

npm install -g @pixellab-code/pixellab

Usage

Basic Usage

import { PixelLabClient } from "@pixellab-code/pixellab";

const client = PixelLabClient.fromEnv();
// Or: const client = PixelLabClient.fromEnvFile(".env.development.secrets");
// Or: const client = new PixelLabClient("your-secret-key");

// Generate image
const response = await client.generateImagePixflux({
  description: "cute dragon",
  imageSize: { width: 64, height: 64 },
});

// Save image to file
await response.image.saveToFile("dragon.png");

// Or get as data URL for browser usage
console.log(response.image.dataUrl);

Environment Variables

Create a .env file or set environment variables:

PIXELLAB_SECRET=your-secret-key-here
PIXELLAB_BASE_URL=https://api.pixellab.ai/v1  # Optional

CLI Usage

# Generate an image
pixellab generate -d "cute dragon" -w 64 -h 64 -o dragon.png

# Check account balance
pixellab balance

# Start MCP server
pixellab mcp

API Methods

Generate Image (Pixflux)

const response = await client.generateImagePixflux({
  description: "cute dragon",
  imageSize: { width: 64, height: 64 },
  negativeDescription: "ugly, blurry",
  textGuidanceScale: 8.0,
  noBackground: true,
  outline: "single color black outline",
  shading: "basic shading",
  detail: "medium detail",
});

Generate Image (Bitforge)

import { Base64Image } from "@pixellab-code/pixellab";

const styleImage = await Base64Image.fromFile("style.png");

const response = await client.generateImageBitforge({
  description: "boy with wings",
  imageSize: { width: 64, height: 64 },
  styleImage,
  styleStrength: 50.0,
  noBackground: true,
});

Get Balance

const balance = await client.getBalance();
console.log(`Balance: ${balance.balance} ${balance.currency}`);

MCP Server

The library includes a Model Context Protocol (MCP) server for integration with AI assistants like Claude Desktop.

# Start MCP server
npx pixellab mcp

Add to your MCP client configuration:

{
  "mcpServers": {
    "pixellab": {
      "command": "npx",
      "args": ["pixellab", "mcp"]
    }
  }
}

Development

Prerequisites

• Node.js 16 or higher
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/pixellab-code/pixellab-js.git
cd pixellab-js

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

Project Structure

pixellab-js/
├── src/
│   ├── client.ts          # Main client class
│   ├── types.ts           # TypeScript types
│   ├── models/            # Data models
│   ├── api/               # API method implementations
│   ├── errors.ts          # Error classes
│   ├── settings.ts        # Configuration
│   └── index.ts           # Main exports
├── tests/                 # Test files
└── dist/                  # Compiled output

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run specific test
npm test -- generateImagePixflux

Make sure to set up your test environment variables in .env.development.secrets:

PIXELLAB_SECRET=your-test-secret-key

API Documentation

For complete API documentation, visit api.pixellab.ai/v1/docs.

Support

• Documentation: api.pixellab.ai/v1/docs
• Discord Community: Join us
• Issues: Please report any SDK issues on our GitHub repository

License

MIT License - see LICENSE file for details.