zelai-cloud-sdk

Official TypeScript/JavaScript SDK for ZelStudio.com Cloud AI Generation API

Generate images, videos, and text using state-of-the-art AI models through a simple and intuitive API.

🤖 New AI agents can now discover and use this SDK automatically via skill.md. See AI Agent Integration.

Features

• Text-to-Image - Generate stunning images from text prompts
• Image-to-Image - Edit and transform existing images
• Dual-Image Editing - Face restoration, character consistency, and image merging with two source images
• AI Image Upscale - Upscale images 2-4x using AI
• Image-to-Video - Create videos from static images
• LLM Text Generation - Generate text with context, memory, and JSON support
• LLM Streaming - Real-time token-by-token streaming with SSE and WebSocket
• Image Vision - Analyze images with LLM for structured data extraction
• STT Speech-to-Text - Audio transcription with streaming and multi-language support
• TTS Text-to-Speech - Voice synthesis with voice models, cloning, realtime mode, and streaming
• 14 Style Presets - Realistic, anime, manga, watercolor, cinematic, and more
• 7 Format Presets - Portrait, landscape, profile, story, post, smartphone, banner
• Built-in Watermarking - Apply custom watermarks to generated content
• WebSocket Support - Real-time generation with progress updates
• CDN Operations - Format conversion, resizing, frame extraction
• Full TypeScript Support - Comprehensive type definitions

🤖 For AI Agents and Tools:

• OpenAI-Compatible API - Drop-in /v1/chat/completions endpoint
• AI Agent Integration - Enable any AI agent (Claude, GPT, etc.) to discover and use the SDK via skill.md

Installation

npm install zelai-cloud-sdk

Quick Start

import { createClient, STYLES, FORMATS } from 'zelai-cloud-sdk';

// Initialize client
const client = createClient('zelai_pk_your_api_key_here');

// Generate an image
const image = await client.generateImage({
  prompt: 'a futuristic city at sunset with flying cars',
  style: STYLES.cine.id,
  format: FORMATS.landscape.id
});
console.log('Image ID:', image.imageId);

// Generate text
const text = await client.generateText({
  prompt: 'Explain quantum computing in simple terms',
  system: 'You are a helpful science teacher'
});
console.log(text.response);

// Stream text in real-time
const controller = client.generateTextStream({
  prompt: 'Write a short story about AI',
  onChunk: (chunk) => process.stdout.write(chunk),
  onComplete: (result) => console.log(`\nTokens: ${result.totalTokens}`)
});
await controller.done;

// Dual-image editing (merge, blend, mix two images)
const result = await client.editImage('image-1-id', {
  imageId2: 'image-2-id',
  prompt: 'make an image with both subjects'
});
console.log('Merged Image ID:', result.imageId);

// Text-to-Speech
const speech = await client.generateSpeech({
  text: 'Hello, how can I help you today?',
  voice: TTS_VOICES.PAUL
});
console.log(`Duration: ${speech.duration}s`);

// Text-to-Speech with realtime mode (low-latency)
const realtimeSpeech = await client.generateSpeech({
  text: 'Fast response with realtime mode.',
  voice: TTS_VOICES.ALICE,
  realtime: true
});

// Speech-to-Text
const transcript = await client.transcribeAudio({
  audio: audioBase64,
  language: 'en'
});
console.log(transcript.text);

Documentation

Full documentation is available in the Wiki.

| Guide | Description | |-------|-------------| | Getting Started | Installation, API key, initialization | | Image Generation | Text-to-image, editing, upscaling, styles & formats | | Video Generation | Image-to-video creation | | LLM & Streaming | Text generation, streaming, OpenAI-compatible API | | STT Speech-to-Text | Audio transcription, streaming, multi-language | | TTS Text-to-Speech | Voice synthesis, cloning, realtime mode, streaming | | CDN Operations | Downloads, watermarks, format conversion | | WebSocket API | Real-time generation with progress updates | | API Reference | Complete endpoint documentation | | Examples | Full code examples | | Troubleshooting | Common issues, debug mode, best practices | | AI Agent Integration | Enable AI agents to use the SDK |

OpenAI Compatibility

Use with OpenAI client libraries:

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'zelai_pk_your_api_key_here',
  baseURL: 'https://api.zelstudio.com/v1'
});

const completion = await client.chat.completions.create({
  model: 'default',
  messages: [{ role: 'user', content: 'Hello!' }],
  stream: true
});

for await (const chunk of completion) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

Available Styles

| Style | Description | |-------|-------------| | raw | Unprocessed, natural look | | realistic | Photo-realistic | | cine | Cinematic, film-like | | portrait | Optimized for portraits | | anime | Japanese anime style | | manga | Japanese manga style | | watercolor | Watercolor painting | | paint | Oil/acrylic painting | | comicbook | Western comic style |

See Image Generation for all 14 styles.

Testing

The SDK includes comprehensive test suites covering REST, WebSocket, and OpenAI-compatible endpoints.

# Run all tests
npm test

# Run specific test suites
npm run test:rest      # REST API tests (25 tests)
npm run test:ws        # WebSocket tests (38 tests)
npm run test:openai    # OpenAI-compatible tests (15 tests)
npm run test:stt       # STT speech-to-text tests
npm run test:tts       # TTS text-to-speech tests

See tests/README.md for detailed test documentation.

Changelog

See CHANGELOG.md for version history and release notes.

License

MIT License - see LICENSE for details.

Support

• Documentation: Wiki
• Issues: GitHub Issues
• Email: [email protected]