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.
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): 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
andsdxl10
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
Last updated