kitsue

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

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.