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.
API Endpoint
URL:
http://sequencer.heurist.xyz/submit_job
Method:
POST
Request Format
Submit a JSON payload with the following structure:
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.
Last updated