@imperatrona/civitai

A lightweight, promise-based TypeScript client for the Civitai API.

Features

• Universal Compatibility: Works in any JavaScript environment that supports the global fetch API (Node.js v18+, Bun, Deno, and modern Browsers).
• Fully Typed: Includes comprehensive TypeScript interfaces for all API resources, models, and response metadata.
• Zero Dependencies: Designed to be minimal and reliable.
• Customizable: Supports custom fetch implementations and configurable authentication modes.

Installation

You can install the package via npm:

npm install @imperatrona/civitai

Quick Usage

import { CivitaiClient } from '@imperatrona/civitai';

// Initialize the client
const client = new CivitaiClient({
  token: 'YOUR_API_TOKEN' 
});

async function run() {
  try {
    // Fetch a list of models
    const response = await client.models({
      limit: 10,
      sort: 'Most Downloaded'
    });

    console.log(`Found ${response.items.length} models.`);
    
    // Get details for a specific model by ID
    const model = await client.model(12345);
    console.log(`Model name: ${model.name}`);
  } catch (err) {
    console.error('API Request failed:', err);
  }
}

run();

Downloading a Model

The modelDownloadUrl helper generates the direct download link. If you are using authMode: 'query' with an API token, the token is automatically appended to the URL.

const versionId = 12345;
const downloadUrl = client.modelDownloadUrl(versionId);

console.log(`Download link: ${downloadUrl}`);

// Example: Fetching the file via fetch
const response = await fetch(downloadUrl);
const blob = await response.blob();

Supported Methods

The CivitaiClient class provides the following methods to interact with the API:

| Method | Description | | --- | --- | | creators(query?) | Lists creators based on optional filters. | | images(query?) | Retrieves image listings with optional pagination/filtering. | | models(query?) | Lists models based on categories, tags, or search terms. | | model(id) | Fetches detailed information for a specific model ID. | | modelVersion(id) | Fetches details for a specific model version ID. | | modelVersionByHash(hash) | Retrieves a model version using its unique file hash. | | tags(query?) | Lists available tags and their usage counts. | | modelDownloadUrl(id) | Generates a direct download URL for a model version. |

Advanced Configuration

The CivitaiClient constructor accepts an optional configuration object:

| Option | Type | Description | | --- | --- | --- | | token | string | API Key for authenticated requests. | | authMode | 'header' | 'query' | Strategy for sending your token. Defaults to header. | | baseUrl | string | Override the default API base URL. | | fetchFn | typeof fetch | Inject a custom fetch implementation (e.g., to add proxies). |

Error Handling

The client throws a CivitaiApiError if the API returns a non-2xx status code. You can use this to handle specific HTTP errors:

import { CivitaiApiError } from '@imperatrona/civitai';

try {
  await client.model(999999);
} catch (err) {
  if (err instanceof CivitaiApiError) {
    console.error(`Status: ${err.status} - URL: ${err.url}`);
  }
}