diff --git a/README.md b/README.md index 6e9b529..4300e94 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +# ModelsLab JavaScript SDK +

ModelsLab Logo

@@ -14,51 +16,374 @@ -Modelslab provides cutting-edge **Generative AI APIs** for building production-grade AI-native applications with ease. Whether you need **image generation**, **text generation**, **video synthesis**, or **voice cloning**, Modelslab gives you high-performance APIs to power your product. +The official JavaScript/TypeScript SDK for ModelsLab's powerful AI APIs. Generate images, create videos, clone voices, and more with just a few lines of code. + +## 🚀 Quick Start + +### Installation + +```bash +npm install modelslab +``` + +### Basic Setup + +```javascript +import { Client, Community } from "modelslab"; -📚 **Docs**: [https://docs.modelslab.com](https://docs.modelslab.com) +// Initialize the client with your API key +const client = new Client("your-api-key-here"); ---- +// Create API instances +const community = new Community(client.key); +``` -## ✨ What is Modelslab? +### Your First AI Image -Modelslab is an API platform that offers: +```javascript +const result = await community.textToImage({ + key: client.key, + prompt: "A beautiful sunset over mountains", + model_id: "flux", + width: 512, + height: 512, + samples: 1, +}); -* 🎨 Image generation (text-to-image, inpainting, upscaling) -* 💬 Chat APIs (uncensored chat, character-based dialogues) -* 🎥 Video generation (AI lip-sync, talking head, motion transfer) -* 🗣 Voice cloning and text-to-speech -* 🧠 Fast inference backend with GPU-optimized APIs +console.log("Generated image:", result.output[0]); +``` -You can plug these APIs into your apps, games, websites, or automation tools with just a few lines of code. +## 📖 Complete Usage Guide ---- +### 1. Getting Your API Key -## 🚀 Installation +1. Sign up at [ModelsLab](https://modelslab.com) +2. Get your API key from the dashboard +3. Set it as an environment variable (optional): ```bash -npm install modelslab +export API_KEY="your-api-key-here" +``` + +### 2. Initialize the Client + +```javascript +// Method 1: Direct API key +const client = new Client("your-api-key"); + +// Method 2: Environment variable +const client = new Client(); // Reads from process.env.API_KEY + +// Method 3: With custom settings +const client = new Client("your-api-key", 5, 10); // 5 retries, 10 second timeout +``` + +### 3. Available APIs + +#### Community API (Image Generation) + +```javascript +import { Community } from "modelslab"; + +const community = new Community(client.key); + +// Text to Image +const image = await community.textToImage({ + key: client.key, + prompt: "A futuristic city at night", + model_id: "stable-diffusion-v1-5", + width: 512, + height: 512, + samples: 1, + num_inference_steps: 20, + guidance_scale: 7.5, +}); + +// Image to Image +const imageToImage = await community.imageToImage({ + key: client.key, + prompt: "A painting in Van Gogh style", + init_image: "base64-encoded-image", + model_id: "stable-diffusion-v1-5", + strength: 0.8, +}); + +// Inpainting (Fill masked areas) +const inpainting = await community.inpainting({ + key: client.key, + prompt: "A red car", + init_image: "base64-encoded-image", + mask_image: "base64-encoded-mask", + model_id: "stable-diffusion-v1-5", +}); + +// ControlNet (Guided generation) +const controlnet = await community.controlnet({ + key: client.key, + prompt: "A realistic portrait", + controlnet_model: "canny", + controlnet_conditioning_scale: 1.0, + model_id: "stable-diffusion-v1-5", +}); +``` + +#### Other APIs + +```javascript +import { Audio, Video, DeepFake, ImageEditing } from "modelslab"; + +// Audio/Voice APIs +const audio = new Audio(client.key); + +// Video Generation APIs +const video = new Video(client.key); + +// DeepFake APIs +const deepfake = new DeepFake(client.key); + +// Image Editing APIs +const imageEditing = new ImageEditing(client.key); +``` + +### 4. Enterprise Features + +For enterprise users with dedicated infrastructure: + +```javascript +// Enable enterprise mode +const enterpriseCommunity = new Community(client.key, true); + +// This uses https://modelslab.com/api/v1/enterprise/images/ endpoints +const result = await enterpriseCommunity.textToImage({ + key: client.key, + prompt: "Enterprise AI image", + model_id: "stable-diffusion-v1-5", +}); +``` + +### 5. Handling Async Operations + +ModelsLab APIs are asynchronous. Here's how to handle them: + +```javascript +// Method 1: Async/Await +async function generateImage() { + try { + const result = await community.textToImage({ + key: client.key, + prompt: "A beautiful landscape", + model_id: "stable-diffusion-v1-5", + }); + + if (result.status === "success") { + console.log("Image URL:", result.output[0]); + } else { + console.log("Still processing, request ID:", result.id); + + // Fetch the result later + const finalResult = await community.fetch(result.id); + console.log("Final result:", finalResult); + } + } catch (error) { + console.error("Error:", error.message); + } +} + +// Method 2: Promises +community + .textToImage({ + key: client.key, + prompt: "A sunset", + model_id: "stable-diffusion-v1-5", + }) + .then((result) => console.log(result)) + .catch((error) => console.error(error)); ``` ---- +### 6. TypeScript Support + +The SDK is written in TypeScript and includes full type definitions: + +```typescript +import { Client, Community, Text2Image } from "modelslab"; + +const client: Client = new Client("api-key"); +const community: Community = new Community(client.key); + +const request: Text2Image = { + key: client.key, + prompt: "A typed request", + model_id: "stable-diffusion-v1-5", + width: 512, + height: 512, +}; + +const result = await community.textToImage(request); +``` + +## �️ Advanced Usage + +### Custom Configuration + +```javascript +// Custom retry and timeout settings +const client = new Client("api-key", 3, 30); // 3 retries, 30 second timeout + +// Access client properties +console.log(client.baseUrl); // "https://modelslab.com/api/" +console.log(client.fetchRetry); // 3 +console.log(client.fetchTimeout); // 30 +``` + +### Error Handling + +```javascript +try { + const result = await community.textToImage({ + key: client.key, + prompt: "Test image", + model_id: "stable-diffusion-v1-5", + }); +} catch (error) { + if (error.message.includes("API key")) { + console.error("Invalid API key"); + } else if (error.message.includes("Network")) { + console.error("Network error, please try again"); + } else { + console.error("Unknown error:", error.message); + } +} +``` + +### Fetching Results + +```javascript +// Start generation +const initialResult = await community.textToImage({ + key: client.key, + prompt: "Long processing image", + model_id: "stable-diffusion-v1-5", +}); + +// If still processing, fetch later +if (initialResult.status !== "success") { + console.log("Processing... Request ID:", initialResult.id); + + // Wait and fetch + await new Promise((resolve) => setTimeout(resolve, 5000)); // Wait 5 seconds + const finalResult = await community.fetch(initialResult.id); + + if (finalResult.status === "success") { + console.log("Image ready:", finalResult.output[0]); + } +} +``` + +## 🎯 Common Use Cases + +### 1. AI Art Generator + +```javascript +async function generateArt(description, style) { + const result = await community.textToImage({ + key: client.key, + prompt: `${description} in ${style} style`, + model_id: "stable-diffusion-v1-5", + width: 512, + height: 512, + guidance_scale: 7.5, + num_inference_steps: 20, + }); + + return result.output[0]; +} + +// Usage +const artUrl = await generateArt("a dragon", "anime"); +``` + +### 2. Image Variation Generator + +```javascript +async function createVariations(baseImage, newPrompt) { + const result = await community.imageToImage({ + key: client.key, + prompt: newPrompt, + init_image: baseImage, // base64 encoded + strength: 0.7, + model_id: "stable-diffusion-v1-5", + }); + + return result.output; +} +``` + +### 3. Background Remover/Replacer + +```javascript +async function replaceBackground(image, mask, newBackground) { + const result = await community.inpainting({ + key: client.key, + prompt: newBackground, + init_image: image, + mask_image: mask, + model_id: "stable-diffusion-v1-5", + }); + + return result.output[0]; +} +``` + +## 🔧 Testing + +The package includes comprehensive tests: + +```bash +# Run all tests +npm test + +# Run tests with coverage +npm run test:coverage + +# Run interactive demo +npm run test:demo + +# Quick validation +npm run test:validate +``` + +## 📚 API Reference + +For detailed API documentation, visit: [https://docs.modelslab.com](https://docs.modelslab.com) -## 🛠 Usage +### Available Models -> Coming soon — SDK will provide simple TypeScript wrappers around Modelslab APIs for rapid integration. +Popular model IDs you can use: -For full API documentation and usage examples, visit the official docs: +- `stable-diffusion-v1-5` +- `stable-diffusion-xl-base-1.0` +- `deliberate-v2` +- `anything-v5` +- `realistic-vision-v1.3` -📚 [Modelslab Documentation](https://docs.modelslab.com) +## ❗ Error Codes ---- +Common errors and solutions: -## 💬 Feedback & Community +| Error | Cause | Solution | +| ---------------------- | ---------------------- | --------------------------------------- | +| "API key is required" | Missing API key | Set API key in client initialization | +| "Model not found" | Invalid model_id | Check available models in docs | +| "Insufficient credits" | Not enough API credits | Add credits to your account | +| "Rate limit exceeded" | Too many requests | Wait and retry with exponential backoff | -* GitHub: [https://github.com/Modelslab](https://github.com/Modelslab) -* Twitter: [@modelslab](https://x.com/ModelsLabAI) +## 🤝 Support & Community ---- +- **Documentation**: [https://docs.modelslab.com](https://docs.modelslab.com) +- **Discord**: [Join our community](https://discord.com/invite/modelslab-1033301189254729748) +- **Twitter**: [@ModelsLabAI](https://x.com/ModelsLabAI) +- **GitHub Issues**: [Report bugs](https://github.com/ModelsLab/modelslab-js/issues) ## 📄 License -MIT +MIT License - see [LICENSE](LICENSE) file for details. diff --git a/src/client.ts b/src/client.ts index b4ff18f..bb7ade2 100644 --- a/src/client.ts +++ b/src/client.ts @@ -1,29 +1,68 @@ // src/client.ts + +// Export API classes +export { BaseAPI } from "./apis/base"; +export { Community } from "./apis/community"; +export { DeepFake } from "./apis/deepfake"; +export { ThreeD } from "./apis/threed"; +export { Realtime } from "./apis/realtime"; +export { InteriorAPI } from "./apis/interior"; +export { Audio } from "./apis/audio"; +export { ImageEditing } from "./apis/image_editing"; +export { Video } from "./apis/video"; + +// Export schemas +export * from "./schemas/base"; +export * from "./schemas/community"; +export * from "./schemas/deepfake"; +export * from "./schemas/threed"; +export * from "./schemas/realtime"; +export * from "./schemas/interior"; +export * from "./schemas/audio"; +export * from "./schemas/video"; + +// Export image editing schemas with aliases to avoid conflicts +export { + Outpainting, + OutpaintingSchema, + BackgroundRemover, + BackgroundRemoverSchema, + SuperResolution, + SuperResolutionSchema, + Fashion, + FashionSchema, + ObjectRemoval, + ObjectRemovalSchema, + Facegen, + FacegenSchema, + Inpainting as ImageEditingInpainting, + InpaintingSchema as ImageEditingInpaintingSchema, + Headshot, + HeadshotSchema, + FluxHeadshot, + FluxHeadshotSchema, +} from "./schemas/image_editing"; + export class Client { - public readonly key: string; - public readonly baseUrl: string; - public readonly fetchRetry: number; - public readonly fetchTimeout: number; - - constructor( - key?: string, - fetchRetry: number = 10, - fetchTimeout: number = 2 - ) { - this.key = this._loadkey(key); - this.baseUrl = "https://modelslab.com/api/"; - this.fetchRetry = fetchRetry; - this.fetchTimeout = fetchTimeout; - } - - private _loadkey(key?: string): string { + public readonly key: string; + public readonly baseUrl: string; + public readonly fetchRetry: number; + public readonly fetchTimeout: number; + + constructor(key?: string, fetchRetry: number = 10, fetchTimeout: number = 2) { + this.key = this._loadkey(key); + this.baseUrl = "https://modelslab.com/api/"; + this.fetchRetry = fetchRetry; + this.fetchTimeout = fetchTimeout; + } + + private _loadkey(key?: string): string { + if (!key) { + key = process.env.API_KEY; if (!key) { - key = process.env.API_KEY; - if (!key) { - throw new Error("API key is required."); - } + throw new Error("API key is required."); } - return key; } + return key; } - \ No newline at end of file +}