Image Generation API

Overview

Heurist provides 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

API Endpoint

• URL: http://sequencer.heurist.xyz/submit_job

• Method: POST

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",
  "deadline": "Maximum time in seconds to wait for the job to complete (Not supported yet)",
  "priority": "Priority level of the job (Not supported yet)"
}

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.

Prompting Guide

For the best prompts, take a look at the JSON examples provided in our Stable Diffusion examples. These are fully reproducible and are used in Heurist Imagine.

Each model has its strengths in terms of image style. For better results, it might take a few tries to perfect your prompts. We recommend visiting Prompthero and Prompt Guide to learn more about improving your prompts.

Important: LoRA models require "trigger words" to activate the specific style or content. We suggest that the "autofill" field in models.json should always be present in the prompt, and it's highly recommended to include key words in the "recommend" field.

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.

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.

For more examples, check out our developer examples on GitHub.