ai-key-rotator

Rotate API keys across multiple AI providers with automatic rate limit handling, cooldowns, and failover.

Install

npm install ai-key-rotator

Quick Start

import { AIKeyRotator } from "ai-key-rotator";

const rotator = new AIKeyRotator({
  providers: {
    openai: {
      credentials: [
        { key: "sk-key1", label: "personal" },
        { key: "sk-key2", label: "work" },
      ],
      cooldown: { type: "fixed", durationMs: 60_000 }, // 1 min cooldown
    },
    google: {
      credentials: [
        { key: "AIza-1", meta: { model: "gemini-flash" } },
        { key: "AIza-2", meta: { model: "gemini-pro" } },
      ],
      // default: resets at midnight UTC
    },
  },
});

// Get an available key
const cred = rotator.getKey("openai");
if (cred) {
  console.log(cred.key); // "sk-key1"
}

// On rate limit error, mark it and auto-rotate
rotator.markExhausted("openai", "sk-key1");

// Next call gets the next available key
const next = rotator.getKey("openai"); // "sk-key2"

API

new AIKeyRotator(config)

| Option | Type | Description | |--------|------|-------------| | providers | Record<string, ProviderConfig> | Map of provider name → credentials + cooldown | | persistence | PersistenceAdapter | Optional save/load adapter for state persistence | | resetIntervalMs | number | Background reset check interval (default: 600000). Set 0 to disable. |

ProviderConfig

{
  credentials: Array<{ key: string; label?: string; meta?: Record<string, unknown> }>;
  cooldown?: { type: "fixed"; durationMs: number } | { type: "midnight-utc" };
}

Methods

| Method | Returns | Description | |--------|---------|-------------| | getKey(provider) | Credential \| null | Get next available credential | | markExhausted(provider, key?) | boolean | Mark a key as exhausted, auto-rotates to next | | rotateNext(provider) | boolean | Manually rotate to next available key | | hasAvailable(provider) | boolean | Check if any keys are available | | getStatus(provider?) | RotatorStatus \| ProviderStatus | Get status overview | | getProviders() | string[] | List all provider names | | addCredential(provider, cred) | void | Add a credential at runtime | | removeCredential(provider, key) | void | Remove a credential | | addProvider(name, config) | void | Add a new provider at runtime | | resetAll(provider?) | void | Manually reset all exhausted credentials | | save() | Promise<void> | Persist state | | load() | Promise<boolean> | Restore state from persistence | | destroy() | void | Stop background timers |

Events

rotator.on("exhausted", (provider, credential) => { /* key was exhausted */ });
rotator.on("rotated", (provider, credential) => { /* switched to new key */ });
rotator.on("allExhausted", (provider) => { /* no keys left */ });
rotator.on("reset", (provider, count) => { /* keys were reset */ });

Persistence

import fs from "fs";

const rotator = new AIKeyRotator({
  providers: { /* ... */ },
  persistence: {
    save: (state) => fs.writeFileSync("state.json", state),
    load: () => {
      try { return fs.readFileSync("state.json", "utf-8"); }
      catch { return null; }
    },
  },
});

// Restore previous state on startup
await rotator.load();

License

MIT