Image Generation API

​

Overview

Heurist provides a REST API that allows developers to invoke Stable Diffusion / Flux model inference to programmatically generate images based on text prompts. This document outlines how to use the API to submit image generation jobs and retrieve the generated images.

​

Authentication

To use the API, you must include a valid authentication token in the request header.

Authorization: Bearer YOUR_AUTH_KEY

​

Request Format

Submit a JSON payload with the following structure:

{
  "job_id": "Random Job Identifier (Must Be Unique)",
  "model_input": {
    "SD": {
      "prompt": "Textual description to generate the image",
      "neg_prompt": "Negative prompt to avoid certain elements in the image",
      "num_iterations": "Number of iterations for the image generation process",
      "width": "Width of the generated image in pixels",
      "height": "Height of the generated image in pixels",
      "guidance_scale": "Guidance scale to control the adherence to the prompt",
      "seed": "Seed for the random number generator to ensure reproducibility"
    }
  },
  "model_id": "Identifier for the image generation model"
}

​

Parameters

• job_id (String, required): A unique identifier for the job ensuring that every job you submit is tracked individually..

• model_input (Object, required): Contains the parameters for the image generation.

  • SD (Object): Specific settings for the Stable Diffusion model.

    • prompt (String, required): The main description that guides the image generation.

    • neg_prompt (String, optional): Descriptions of what to avoid in the generated image.

    • num_iterations (Integer, optional): The number of iteration steps. We recommend 20~30. Cannot exceed 50.

    • width (Integer, optional): The width of the generated image in pixels. Default is 512.

    • height (Integer, optional): The height of the generated image in pixels. Default is 512.

    • guidance_scale (Float, optional): Influences the model’s adherence to the prompt.

    • seed (Integer, optional): Ensures reproducibility of the image generation. Default is -1 for pure randomness.

• model_id (String, required): The identifier of the image generation model to use. You can find all supported models in the Heurist model list. Meaning of model type parameter:sd15 = Stable Diffusion 1.5 checkpoint.sdxl10 = SDXL 1.0 checkpoint. composite15 = Stable Diffusion 1.5 LoRA. compositexl = SDXL LoRA

​

Response Structure

When the job is successfully processed, the API returns a URL pointing to the generated image.

For API reference, Please visit the Image Generation Endpoint section.

​

Cost Considerations

The cost of generating an image depends on the model type, resolution, and number of iteration steps:

• 1 Standard Unit of Credit = 1 image generated at 1024x1024 resolution using SDXL model with 20 iterations.

• The cost of a job is proportional to the image’s resolution and the number of iterations used. For example:

• If you generate an image at 1024x512 resolution using 30 iterations with SDXL model, the cost calculation is: 1024x512 / (1024x1024) * 30 / 20 = 0.75 credits

• SD 1.5 models are smaller and thus cost less than SDXL models.

​

API Integration Examples

Want to see the Image Generation API in action? Here are a few integration examples:

• Stable Diffusion WebUI is a simple demo project that integrates with Heurist’s image generation API, built with Gradio in Python. Here’s the relevant POST API request

• Heurist Node.js SDK integrates with the API. The SDK provides complete authentication and error handling features.