kitsue

A free, high-performance anime avatar, banner & Discord media ecosystem for bots and web apps.

Official Website • Cloudflare CDN • npm Package • Discord Support • Report Issue

What is Kitsue?

Kitsue is an asset ecosystem designed for Discord bots, profile customization commands (/avatar, /banner, /wallpaper), and community platforms. Instead of relying on rate-limited third-party APIs or self-hosting heavy graphics folders, Kitsue provides:

• Cloudflare Edge CDN: 7,000 hand-curated media assets across 7 collections, delivered globally with open CORS and permanent edge caching.
• Official npm Package (kitsue): A zero-dependency client with native TypeScript types and instant 0ms synchronous in-memory resolution.

📦 Getting Started (npm)

1. Installation

npm install kitsue
# or
pnpm add kitsue
# or
yarn add kitsue
# or
bun add kitsue

2. Basic Usage

const { getRandom, getUrl, getCategories, getAllUrls } = require("kitsue");

// Get a random anime PFP URL (synchronous, 0ms latency)
const avatar = getRandom("anime");
console.log(avatar);
// => "https://cdn-kitsue.pages.dev/anime/742.jpg"

// Get a specific wallpaper by number (0 to 999)
const wallpaper = getUrl("wallpapers", 42);
console.log(wallpaper);
// => "https://cdn-kitsue.pages.dev/wallpapers/42.jpg"

// Get all 1,000 URLs in a collection for prefetching
const banners = getAllUrls("banners");

// List all 7 collections
const collections = getCategories();
// => ["girls", "boys", "anime", "couples", "banners", "wallpapers", "server-icons"]

3. Discord.js v14 Bot Example

const { SlashCommandBuilder, EmbedBuilder } = require("discord.js");
const { getRandom } = require("kitsue");

module.exports = {
  data: new SlashCommandBuilder()
    .setName("avatar")
    .setDescription("Fetch a curated anime or aesthetic avatar!")
    .addStringOption(opt =>
      opt.setName("category")
        .setDescription("Avatar collection to fetch from")
        .setRequired(false)
        .addChoices(
          { name: "Anime", value: "anime" },
          { name: "Girls", value: "girls" },
          { name: "Boys", value: "boys" },
          { name: "Couples (Matching)", value: "couples" }
        )
    ),

  async execute(interaction) {
    const category = interaction.options.getString("category") || "anime";
    const avatarUrl = getRandom(category);

    const embed = new EmbedBuilder()
      .setColor(0xff6b4a)
      .setTitle(`Random ${category.toUpperCase()} Avatar`)
      .setImage(avatarUrl)
      .setFooter({ text: "Powered by Kitsue" })
      .setTimestamp();

    await interaction.reply({ embeds: [embed] });
  }
};

🌐 Direct CDN Usage

If you prefer consuming raw URLs without installing any library:

# URL Pattern
https://cdn-kitsue.pages.dev/{category}/{number}.jpg

# Examples
https://cdn-kitsue.pages.dev/anime/1.jpg
https://cdn-kitsue.pages.dev/wallpapers/42.jpg
https://cdn-kitsue.pages.dev/banners/10.jpg
https://cdn-kitsue.pages.dev/server-icons/0.jpg

# Manifest / Index (all categories and metadata)
https://cdn-kitsue.pages.dev/index.json

Available Mirrors

| Provider | Base URL | Advantage | | :--- | :--- | :--- | | Cloudflare Pages (Primary) | https://cdn-kitsue.pages.dev | Fast Anycast edge, HTTP/3, 1-year cache | | GitHub Raw (Direct) | https://raw.githubusercontent.com/PandaDevOfficial/Kitsue-CDN/main | Synchronized with git repository | | jsDelivr (Edge Cache) | https://cdn.jsdelivr.net/gh/PandaDevOfficial/Kitsue-CDN@main | Redundant multi-CDN failover | | Statically | https://cdn.statically.io/gh/PandaDevOfficial/Kitsue-CDN/main | Fast static cache proxy |

📂 Available Collections (7,000 Assets)

| Category | Assets | Aspect Ratio | Range | Description | | :--- | :---: | :---: | :---: | :--- | | girls | 1,000 | 1:1 | 0–999 | Female profile pictures and aesthetic avatars | | boys | 1,000 | 1:1 | 0–999 | Male profile pictures and minimalist avatars | | anime | 1,000 | 1:1 | 0–999 | Anime avatars, icons, and character art | | couples | 1,000 | 1:1 | 0–999 | Matching profile pictures for duos and friends | | banners | 1,000 | 3:1+ | 0–999 | Discord profile banners and Twitter/X headers | | wallpapers | 1,000 | 16:9 | 0–999 | Desktop HD wallpapers and backgrounds | | server-icons | 1,000 | 1:1 | 0–999 | Discord server icons and community logos |

💬 Support & Community

Need help integrating Kitsue into your project, want to suggest new collections, or found an issue?

• Join our Discord Support Server.
• Open an issue in our GitHub Issues tracker for bug reports, broken image replacements, or library feedback.

📄 License

MIT © PandaDevOfficial.