novelai-image-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,371 @@
+/**
+ * Supported NovelAI image generation models
+ */
+declare enum NovelAIModel {
+    /** V4.5 Full - Latest model with T5 encoding and multi-character support */
+    V45_Full = "nai-diffusion-4-5-full",
+    /** V4 Curated - More conservative aesthetic choices */
+    V4_Curated = "nai-diffusion-4-curated",
+    /** V4 Inpainting - For image editing and inpainting tasks */
+    Inpainting = "nai-diffusion-4-inpainting"
+}
+
+/**
+ * Supported sampling algorithms for image generation
+ */
+declare enum NovelAISampler {
+    /** Standard Euler sampler */
+    Euler = "k_euler",
+    /** Euler Ancestral - recommended for anime-style generations */
+    EulerAncestral = "k_euler_ancestral",
+    /** DPM++ 2M - stable and aesthetic */
+    DPM_2M = "k_dpmpp_2m",
+    /** DPM++ 2S Ancestral */
+    DPM_2S_Ancestral = "k_dpmpp_2s_ancestral",
+    /** DPM++ SDE */
+    DPM_SDE = "k_dpmpp_sde",
+    /** DDIM V3 */
+    DDIM = "ddim_v3"
+}
+/**
+ * Preset negative prompt configurations
+ */
+declare enum UCPreset {
+    /** Heavy - Low Quality + Bad Anatomy */
+    Heavy = 0,
+    /** Light - Low Quality only */
+    Light = 1,
+    /** None - Use custom negative prompt only */
+    None = 2
+}
+/**
+ * Noise schedule algorithms
+ */
+declare enum NoiseSchedule {
+    Native = "native",
+    Karras = "karras",
+    Exponential = "exponential",
+    Polyexponential = "polyexponential"
+}
+
+/**
+ * V4 condition input structure for prompts
+ * Used by both v4_prompt and v4_negative_prompt
+ */
+interface V4ConditionInput {
+    caption: {
+        base_caption: string;
+        char_captions: string[];
+    };
+    use_coords: boolean;
+    use_order: boolean;
+    legacy_uc?: boolean;
+}
+/**
+ * Parameters block for the generate-image API
+ * Note: Mixed casing is intentional - matches strict API schema
+ */
+interface NovelAIParameters {
+    width: number;
+    height: number;
+    scale: number;
+    sampler: NovelAISampler | string;
+    steps: number;
+    n_samples: number;
+    seed: number;
+    negative_prompt: string;
+    v4_prompt: V4ConditionInput;
+    v4_negative_prompt: V4ConditionInput;
+    qualityToggle: boolean;
+    ucPreset: UCPreset | number;
+    params_version: number;
+    noise_schedule: NoiseSchedule | string;
+    sm: boolean;
+    sm_dyn: boolean;
+    prefer_brownian: boolean;
+    deliberate_euler_ancestral_bug: boolean;
+    legacy: boolean;
+    legacy_v3_extend: boolean;
+}
+/**
+ * Root payload structure for /ai/generate-image endpoint
+ */
+interface GenerateImagePayload {
+    input: string;
+    model: NovelAIModel | string;
+    action: 'generate';
+    parameters: NovelAIParameters;
+}
+/**
+ * SDK configuration options
+ */
+interface ClientConfig {
+    /** NovelAI Persistent API Token (pst-...) */
+    token: string;
+    /** Base URL for the image API (default: https://image.novelai.net) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+/**
+ * Options for building an image generation request
+ */
+interface ImageGenerationOptions {
+    model?: NovelAIModel;
+    width?: number;
+    height?: number;
+    prompt?: string;
+    characterPrompts?: string[];
+    negativePrompt?: string;
+    seed?: number;
+    steps?: number;
+    scale?: number;
+    sampler?: NovelAISampler;
+    ucPreset?: UCPreset;
+    qualityToggle?: boolean;
+    smea?: boolean;
+    smeaDyn?: boolean;
+    noiseSchedule?: NoiseSchedule;
+}
+
+/**
+ * Metadata extracted from generated images
+ */
+interface ImageMetadata {
+    seed?: number;
+    prompt?: string;
+    model?: string;
+    sampler?: string;
+    steps?: number;
+    scale?: number;
+}
+/**
+ * Response from a successful image generation
+ */
+interface ImageResponse {
+    /** Generated image(s) as Buffer (Node.js) or Uint8Array (Browser) */
+    images: Uint8Array[];
+    /** Optional metadata parsed from response */
+    metadata?: ImageMetadata;
+}
+
+/**
+ * Fluent builder for constructing NovelAI image generation requests
+ * Provides method chaining and compile-time type safety
+ */
+declare class ImageRequestBuilder {
+    private client;
+    private model;
+    private width;
+    private height;
+    private prompt;
+    private characterPrompts;
+    private negativePrompt;
+    private seed;
+    private steps;
+    private scale;
+    private sampler;
+    private ucPreset;
+    private qualityToggle;
+    private smea;
+    private smeaDyn;
+    private noiseSchedule;
+    constructor(client: NovelAIClient);
+    /**
+     * Set the model to use for generation
+     */
+    setModel(model: NovelAIModel): this;
+    /**
+     * Set the output image dimensions
+     * @throws ValidationError if dimensions are not multiples of 64
+     */
+    setSize(width: number, height: number): this;
+    /**
+     * Set the main prompt (base scene description)
+     * For multi-character prompts, use the array overload
+     */
+    setPrompt(base: string, characters?: string[]): this;
+    /**
+     * Add character prompts for multi-character scenes
+     */
+    addCharacter(characterPrompt: string): this;
+    /**
+     * Set the negative prompt (what to avoid in generation)
+     */
+    setNegativePrompt(negative: string): this;
+    /**
+     * Set the random seed for reproducible generations
+     */
+    setSeed(seed: number): this;
+    /**
+     * Set the number of sampling steps
+     * @throws ValidationError if steps are out of range (1-50)
+     */
+    setSteps(steps: number): this;
+    /**
+     * Set the guidance scale (CFG)
+     * @throws ValidationError if scale is out of range (0-10)
+     */
+    setScale(scale: number): this;
+    /**
+     * Set the sampling algorithm
+     */
+    setSampler(sampler: NovelAISampler): this;
+    /**
+     * Set the UC preset (predefined negative prompt configuration)
+     */
+    setUCPreset(preset: UCPreset): this;
+    /**
+     * Toggle automatic quality tags insertion
+     */
+    setQualityToggle(enabled: boolean): this;
+    /**
+     * Enable SMEA (Sinusoidal Multipass Euler Ancestral)
+     * @param dynamic - If true, enables dynamic SMEA variant
+     */
+    enableSMEA(dynamic?: boolean): this;
+    /**
+     * Disable SMEA
+     */
+    disableSMEA(): this;
+    /**
+     * Set the noise schedule algorithm
+     */
+    setNoiseSchedule(schedule: NoiseSchedule): this;
+    /**
+     * Build the V4 condition input structure for prompts
+     */
+    private buildV4ConditionInput;
+    /**
+     * Build the formatted input string for the API
+     * Combines base prompt with character prompts using pipe delimiter
+     */
+    private buildInputString;
+    /**
+     * Build the complete API payload
+     */
+    buildPayload(): GenerateImagePayload;
+    /**
+     * Execute the image generation request
+     */
+    generate(): Promise<ImageResponse>;
+}
+
+/**
+ * Main entry point for the NovelAI Image SDK
+ *
+ * @example
+ * ```typescript
+ * const client = new NovelAIClient({ token: process.env.NAI_TOKEN });
+ *
+ * const result = await client.image()
+ *   .setPrompt('1girl, cyberpunk, neon lights')
+ *   .setSize(832, 1216)
+ *   .generate();
+ *
+ * fs.writeFileSync('output.png', result.images[0]);
+ * ```
+ */
+declare class NovelAIClient {
+    private readonly apiClient;
+    /**
+     * Create a new NovelAI client
+     * @param config - Client configuration including token and optional base URL
+     */
+    constructor(config: ClientConfig);
+    /**
+     * Start building an image generation request
+     * @returns A new ImageRequestBuilder instance
+     */
+    image(): ImageRequestBuilder;
+    /**
+     * Execute a generation request (called internally by the builder)
+     * @internal
+     */
+    _execute(payload: GenerateImagePayload): Promise<ImageResponse>;
+}
+
+/**
+ * Base error class for all NovelAI SDK errors
+ */
+declare class NovelAIError extends Error {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Authentication error (401/403)
+ * Thrown when the API token is invalid or expired
+ */
+declare class NovelAIAuthError extends NovelAIError {
+    constructor(message?: string);
+}
+/**
+ * Payment required error (402)
+ * Thrown when the user has insufficient Anlas credits
+ */
+declare class NovelAIPaymentError extends NovelAIError {
+    constructor(message?: string);
+}
+/**
+ * Validation error (400)
+ * Thrown when the API rejects the payload due to schema issues
+ */
+declare class NovelAIValidationError extends NovelAIError {
+    readonly details?: string;
+    constructor(message: string, details?: string);
+}
+/**
+ * Network error
+ * Thrown on timeouts, connection failures, or other network issues
+ */
+declare class NovelAINetworkError extends NovelAIError {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Rate limit error (429)
+ * Thrown when too many requests are made
+ */
+declare class NovelAIRateLimitError extends NovelAIError {
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number);
+}
+/**
+ * Server error (500+)
+ * Thrown when the NovelAI server encounters an internal error
+ */
+declare class NovelAIServerError extends NovelAIError {
+    readonly correlationId?: string;
+    constructor(message?: string, correlationId?: string);
+}
+
+/**
+ * Convert Uint8Array to Base64 string (useful for browser display)
+ */
+declare function toBase64(data: Uint8Array): string;
+/**
+ * Convert Uint8Array to data URL for direct use in img src
+ */
+declare function toDataURL(data: Uint8Array, mimeType?: string): string;
+
+/**
+ * Validates that image dimensions are multiples of 64
+ * @throws ValidationError if dimensions are invalid
+ */
+declare function validateResolution(width: number, height: number): void;
+/**
+ * Validates that step count is within acceptable range
+ * @throws ValidationError if steps are out of range
+ */
+declare function validateSteps(steps: number): void;
+/**
+ * Validates that scale (CFG) is within acceptable range
+ * @throws ValidationError if scale is out of range
+ */
+declare function validateScale(scale: number): void;
+/**
+ * Validates that seed is a valid unsigned 32-bit integer
+ */
+declare function validateSeed(seed: number): void;
+
+export { type ClientConfig, type GenerateImagePayload, type ImageGenerationOptions, type ImageMetadata, ImageRequestBuilder, type ImageResponse, NoiseSchedule, NovelAIAuthError, NovelAIClient, NovelAIError, NovelAIModel, NovelAINetworkError, type NovelAIParameters, NovelAIPaymentError, NovelAIRateLimitError, NovelAISampler, NovelAIServerError, NovelAIValidationError, UCPreset, type V4ConditionInput, toBase64, toDataURL, validateResolution, validateScale, validateSeed, validateSteps };