​
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"
  "deadline": 60,
  "priority": 1
}

​
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
  • priority (Integer, required): Sets priority in a queue for the job. Default is 1.
  • deadline (Integer, required): Sets the max duration of a job. Default is 60.

​
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: