Heurist TypeScript API Library

This library provides convenient access to the Heurist REST API from TypeScript or JavaScript.

The full API documentation can be found in docs.

Requirements

TypeScript >= 4.5 is supported.

The following runtimes are supported:

• Node.js 18 LTS or later (non-EOL) versions.
• Vercel Edge Runtime.

Installation

pnpm add heurist

Get an API Key

Submit this form: https://dev-api-form.heurist.ai/ with a valid email and description of your use case.

Usage

import Heurist from 'heurist'

const heurist = new Heurist({
  apiKey: process.env['HEURIST_API_KEY'], // This is the default and can be omitted
})

async function generateImage() {
  const response = await heurist.images.generate({
    model: 'BrainDance',
    prompt: '1girl',
    // below are optional
    neg_prompt: 'worst quality',
    num_iterations: 25,
    guidance_scale: 7.5,
    width: 1024,
    height: 768,
    seed: -1
  })

  // response
  // {
  //   "url": "https://heurist-images.s3.us-east-1.amazonaws.com/**********.png"
  //   ...
  // }
}

  async function workflow() {
    const upscalerTask = new UpscalerTask({
        consumer_id: 'example-id',
        image_url: 'https://example.com/sample.jpg',
        timeout_seconds: 300 // optional
    });

    const response = await heurist.workflow.executeWorkflowAndWaitForResult(upscalerTask);
  }

  // response
  // {
  //    "result": "xxxxxxx.png"
  //    ...
  // }

SmartGen for Image Generation (Experimental)

⚠️ Experimental Feature: SmartGen is currently in beta. APIs and behaviors may change.

Overview

SmartGen provides a high-level interface for generating images with enhanced prompt engineering and dimension controls. It supports both FLUX and Stable Diffusion models.

Basic Example

import Heurist from 'heurist'

const heurist = new Heurist({
  apiKey: process.env['HEURIST_API_KEY']
})

const response = await heurist.smartgen.generateImage({
  description: "A futuristic cyberpunk portrait of a young woman",
  image_model: "FLUX.1-dev",
  stylization_level: 3,
  detail_level: 4,
  color_level: 5,
  lighting_level: 2
})

Parameters and Controls

SmartGen accepts the following key parameters:

{
    // Basic settings
    description: string,    // Main image description
    width?: number
    height?: number

    // AI model settings
    image_model?: string,   // Default: FLUX.1-dev
    is_sd?: boolean          // Default: false. Set it to true if we want to use stable diffusion prompt format (comma-separated phrases)
    language_model?: string  // Default: nvidia/llama-3.1-nemotron-70b-instruct. For image prompt generation
    
    // Dimension controls (all optional, scale 1-5)
    stylization_level: number,  // Realism vs artistic style. 1: Photorealistic 5: Highly artistic
    detail_level: number,       // Amount of detail. 1: Minimalist 5: Extreme intricate
    color_level: number,        // Color intensity. 1: Monochromatic 5: Hyper-saturated
    lighting_level: number,     // Lighting drama. 1: Flat, even lighting 5: Extreme dramatic lighting
    
    // Optional parameters
    must_include?: string,       // Elements to always include without altering
    examples?: string[],         // Example prompts for reference
    quality?: 'normal' | 'high', // Controls iteration count
    num_iterations?: number      // Default is 20. If specified, this overrides quality setting
    guidance_scale?: number      // Default is 3 for Flux and 6 for Stable Diffusion
    negative_prompt?: string     // Negative prompt, only applies to Stable Diffusion
    param_only?: boolean         // Default: false. Set it to true if we want to return params without generating the image
}

Two-Step Generation

You can split the generation process into two steps:

// Step 1: Get image generation parameters
const params = await heurist.smartgen.generateImage({
  description: "A cyberpunk cityscape",
  image_model: "FLUX.1-dev",
  stylization_level: 4,
  must_include: "neon lights, flying cars",
  param_only: true  // Don't generate image yet
})

// Review and modify parameters if needed
console.log(params.parameters.prompt)

// Step 2: Call `images.generate` API to generate with the same or modified parameters
const imageResult = await heurist.images.generate({
  ...params.parameters
  // You may change some fields
})

Response Type in Parameter-only Mode (param_only set to true)

{
  parameters: {
    prompt: string,     // Enhanced prompt
    model: string,
    width: number,
    height: number,
    num_iterations: number,
    guidance_scale: number,
    neg_prompt?: string,
  }
}

One-Step Generation

You can create an image with a simple description in one step:

const result = await heurist.smartgen.generateImage({
  description: "A cyberpunk cityscape",
  image_model: "FLUX.1-dev",
  stylization_level: 4,
  must_include: "neon lights, flying cars"
})

// Result image URL
console.log(result.url)

// You can inspect the image generation parameters
console.log(result.parameters)

Demonstration

Here are two examples showcasing the progression from monochromatic to vibrant colors (color_level from 1 to 5):

Example 1: "A futuristic cyberpunk portrait of a young woman"

Example 2: "Hot air balloons in the sky"