Image Generation API

Overview

Heurist provides REST API that allows developers to invoke Stable Diffusion 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): A unique identifier for the job.

• model_input (Object): 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): The identifier of the image generation model to use. sd15 and sdxl10 models in Heurist model list are supported.

Response Structure

The API responds with the URL of the generated image.

Prompting Guide

Check out the JSON files in our Stable Diffusion examples. These example prompts and parameters are reproducible, and are used in Imagine by Heurist.

Each model is good at a specific image style. It takes some practice, trials and luck to reach a satisfactory result. Check https://prompthero.com/ and https://stable-diffusion-art.com/prompt-guide/ to improve your prompts.

Cost Considerations

The time it takes to generate an image depends on the model type, resolution and the number of iteration steps.

We define 1 standard unit of credit (equivalent to x HEU token - the exact ratio subjects to change due to price volatility) to be one 512*512 image generated by Stable Diffusion 1.5 model and 20 iterations.

The credit spent on an image generation job is proportional to the number of pixels and number of iterations.

For example, if an image is generated by SD 1.5 model with 40 iterations and resolution is 1024*1024, you will be charged (1024*1024) / (512*512) * (40 / 20) = 8 credits

SDXL cost of credits is 2x of that of SD 1.5 because the model size is larger.

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

• Imagine is a production-ready AI image generator site built with React and Next.js. Its getImage API route demonstrates the usage of Stable Diffusion API in real world.

More examples: https://github.com/heurist-network/dev-examples