Loudly JS SDK

Official JavaScript SDK for the Loudly AI Music API. Generate AI-powered songs, across 50+ genres, with pre-set prompts and parameters like energy, tempo, key and song structures via an easy intuitive interface. 100% Ethical AI and Copyright-Safe.

🚀 Quick Start

import LoudlyJSSDK from "loudly-js-sdk";

const sdk = new LoudlyJSSDK({
  apiKey: "your_api_key_here"
});

// Generate a song from a prompt
const song = await sdk.createSongFromPrompt({
  prompt: "A 90-second energetic house track with tropical vibes and flute"
});

console.log(song);

📋 Table of Contents

• Installation
• Authentication
• API Methods
• Examples
• Project Structure
• Contributing
• License

🔧 Installation

Install the SDK via npm:

npm install loudly-js-sdk

🔑 Authentication

Step 1: Get Your API Key

1. Create an account on the (https://www.loudly.com/music-api)
2. Navigate to your account dashboard
3. Generate an API key
4. Copy your API key for authentication

Step 2: Setup Authentication

Environment Variables (Recommended)

Create a .env file in your project root:

LOUDLY_API_KEY=your_api_key_here

Then initialize the SDK:

import dotenv from "dotenv";
import LoudlyJSSDK from "loudly-js-sdk";

dotenv.config();

const sdk = new LoudlyJSSDK({
  apiKey: process.env.LOUDLY_API_KEY
});

📚 API Methods

Account Management

getAccountLimits({ dateFrom, dateTo })

Retrieve account usage limits for a specified date range.

const limits = await sdk.getAccountLimits({
  dateFrom: "2025-01-01",
  dateTo: "2025-01-31"
});

Music Generation

createSong(payload)

Generate a song with detailed parameters.

const song = await sdk.createSong({
  genre: "House",
  duration: "90",
  energy: "high",
  bpm: "128",
  key_root: "C",
  key_quality: "major",
  instruments: "piano, drums"
});

createSongFromPrompt({ prompt, duration, test, structure_id })

Generate a song directly from a natural language prompt.

const song = await sdk.createSongFromPrompt({
  prompt: "A 90-second energetic house track with tropical vibes and flute",
  duration: "90"
});

Content Discovery

getGenres()

Fetch all available music genres.

const genres = await sdk.getGenres();

getStructures()

Retrieve available song structures.

const structures = await sdk.getStructures();

getSongTags()

Get all available song tags for categorization.

const tags = await sdk.getSongTags();

getSongs(params)

Search and filter songs with various parameters.

const songs = await sdk.getSongs({
  genre: "House",
  mood: "Energetic",
  limit: 10,
  page: 1
});

Prompts

getRandomPrompt()

Generate a random AI prompt for inspiration.

const prompt = await sdk.getRandomPrompt();

💡 Examples

Basic Song Generation

import LoudlyJSSDK from "loudly-js-sdk";

const sdk = new LoudlyJSSDK({
  apiKey: process.env.LOUDLY_API_KEY
});

async function generateSong() {
  try {
    // Create a song with specific parameters
    const song = await sdk.createSong({
      genre: "Electronic",
      duration: "120",
      energy: "medium",
      bpm: "120",
      key_root: "A",
      key_quality: "minor"
    });
    
    console.log("Song created:", song);
  } catch (error) {
    console.error("Error generating song:", error.message);
  }
}

generateSong();

Exploring Available Options

async function exploreOptions() {
  try {
    // Get all available genres
    const genres = await sdk.getGenres();
    console.log("Available genres:", genres);
    
    // Get song structures
    const structures = await sdk.getStructures();
    console.log("Available structures:", structures);
    
    // Get random prompt for inspiration
    const prompt = await sdk.getRandomPrompt();
    console.log("Random prompt:", prompt);
    
  } catch (error) {
    console.error("Error:", error.message);
  }
}

Search Existing Songs

async function searchSongs() {
  try {
    const songs = await sdk.getSongs({
      genre: "Ambient",
      mood: "Relaxing",
      limit: 5
    });
    
    console.log(`Found ${songs.length} ambient songs`);
    songs.forEach(song => {
      console.log(`- ${song.title} (${song.duration}s)`);
    });
    
  } catch (error) {
    console.error("Error searching songs:", error.message);
  }
}

📁 Project Structure

loudly-js-sdk/
├── src/
│   └── loudlyjssdk.js      # Core SDK implementation
├── test/
│   └── test.js             # Example usage and tests
├── .gitignore              # Git ignore rules
├── README.md               # This file
├── package.json            # Package configuration
└── LICENSE                 # MIT License

🔍 Error Handling

The SDK throws descriptive errors when something goes wrong. Always wrap API calls in try-catch blocks:

try {
  const song = await sdk.createSong(params);
  // Handle successful response
} catch (error) {
  console.error("API Error:", error.message);
  // Handle error appropriately
}

📝 Notes

• All methods return JSON responses directly from the Loudly API
• API responses may vary based on your account tier and limits
• Store your API key securely using environment variables
• Rate limiting may apply based on your account plan

🤝 Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Loudly Platform
• npm Package

❓ Support

If you encounter any issues or have questions, please:

1. Search existing GitHub issues
2. Create a new issue if needed

---

Made with ❤️ by the Loudly team