Introduction to image inference
Introduction
Image inference refers to image generation and manipulation operations. Generate images from text descriptions, transform existing images, and perform specialized editing operations, all powered by our Sonic Inference Engine®.
For the core API parameters common to all Runware tasks, please refer to our Getting Started Introduction. That guide covers the fundamental concepts that apply across all Runware APIs.
This page covers the common parameters and concepts shared across all image inference operations. Understanding these fundamentals will help you work effectively with any of our image-related APIs.
[
{
// Core parameters
"taskType": "imageInference",
"taskUUID": "a770f077-f413-47de-9dac-be0b26a35da6",
"includeCost": true,
// Image-related parameters
"outputType": "URL",
"outputFormat": "JPG",
"outputQuality": 95,
"numberResults": 2,
"checkNSFW": true,
// Task parameters
"model": "runware:101@1",
"positivePrompt": "a serene landscape with mountains and a lake",
"width": 1024,
"height": 1024
}
]
Image inference features
Our API offers several core image generation approaches:
Feature | Description | Key Parameters |
---|---|---|
Text-to-image | Generate images from textual descriptions. | positivePrompt |
Image-to-image | Transform existing images guided by text prompts. | seedImage + strength |
Inpainting | Selectively modify specific areas of an image using a mask. | seedImage + maskImage |
Outpainting | Extend images beyond their original boundaries. | seedImage + outpaint |
These core features can be enhanced with additional technologies:
Feature | Description | Key Parameters |
---|---|---|
Refiner | Improve or enhance previously generated images. | refiner |
VAE | Variational Autoencoders for improved image quality and details. | vae |
ControlNet | Add structural guidance using reference images. | controlNet |
LoRA | Apply specialized style or subject adaptation. | lora |
IP-Adapter | Incorporate visual reference for style and content from existing images. | ipAdapters |
Embeddings | Use custom concepts and styles across generations. | embeddings |
PuLID | Advanced face identity preservation across different contexts. | puLID |
ACE++ | Character-consistent image generation and editing workflows. | acePlusPlus |
PhotoMaker | Create consistent character identities and styles. | photoMaker |
All these functionalities use the imageInference
task type, differentiated by the specific parameters you include.
Common image inference parameters
While each image inference operation has its specific parameters, several parameters are common across all image inference tasks.
- outputType"base64Data" | "dataURI" | "URL" Default: URL
-
Specifies the output type in which the image is returned. Supported values are:
dataURI
,URL
, andbase64Data
.base64Data
: The image is returned as a base64-encoded string using theimageBase64Data
parameter in the response object.dataURI
: The image is returned as a data URI string using theimageDataURI
parameter in the response object.URL
: The image is returned as a URL string using theimageURL
parameter in the response object.
- outputFormat"JPG" | "PNG" | "WEBP" Default: JPG
-
Specifies the format of the output image. Supported formats are:
PNG
,JPG
andWEBP
.
- outputQualityinteger Min: 20 Max: 99 Default: 95
-
Sets the compression quality of the output image. Higher values preserve more quality but increase file size, lower values reduce file size but decrease quality.
- uploadEndpointstring
-
Specifies a URL where the generated content will be automatically uploaded using the HTTP PUT method. The raw binary data of the image or video file is sent directly as the request body (not as JSON), enabling webhook-like functionality for immediate processing once generation is complete.
Common use cases:
- Cloud storage: Upload directly to S3 buckets, Google Cloud Storage, or Azure Blob Storage.
- Webhook services: Send content to your API endpoints or serverless functions for processing.
- CDN integration: Upload to content delivery networks for immediate distribution.
URL customization:
You can include query parameters in the URL to help identify and process the uploaded content:
# Using our task UUIDs https://your-api.com/webhook/media?taskUUID=991e641a-d2a8-4aa3-9883-9d6fe230fff8 // Using your own IDs https://api.example.com/receive-content?id=img_abc123&projectId=proj_789 // Direct cloud storage upload https://your-bucket.s3.amazonaws.com/generated/content.mp4 // Multiple parameters for tracking https://api.example.com/process-media?userId=12345×tamp=1640995200
The content data will be sent as the request body, allowing your endpoint to receive and process the generated image or video immediately upon completion.
- checkNSFWboolean Default: false
-
This parameter is used to enable or disable the NSFW check. When enabled, the API will check if the image contains NSFW (not safe for work) content. This check is done using a pre-trained model that detects adult content in images.
When the check is enabled, the API will return
NSFWContent: true
in the response object if the image is flagged as potentially sensitive content. If the image is not flagged, the API will returnNSFWContent: false
.If this parameter is not used, the parameter
NSFWContent
will not be included in the response object.Adds 0.1 seconds to image inference time and incurs additional costs.
The NSFW filter occasionally returns false positives and very rarely false negatives.
- numberResultsinteger Min: 1 Max: 20 Default: 1
-
Specifies how many images to generate for the given parameters. Each image will have the same parameters but different seeds, resulting in variations of the same concept.
If seed is set, it will be incremented by
1
(+1) for each image generated.
Here's a simple text-to-image request illustrating the common parameters:
[
{
"taskType": "imageInference",
"taskUUID": "a770f077-f413-47de-9dac-be0b26a35da6",
"model": "runware:101@1",
"positivePrompt": "a serene landscape with mountains and a lake",
"width": 1024,
"height": 1024,
"outputType": "URL",
"outputFormat": "JPG",
"outputQuality": 95,
"numberResults": 2,
"checkNSFW": true,
"includeCost": true
}
]
Common response fields
All image inference operations return a consistent set of fields:
- imageUUIDstring UUID v4
-
A unique identifier for the output image. This UUID can be used to reference the image in subsequent operations or for tracking purposes.
The
imageUUID
is different from thetaskUUID
. WhiletaskUUID
identifies the request,imageUUID
identifies the specific image output.
- imageURLstring
-
If
outputType
is set toURL
, this parameter contains the URL of the image to be downloaded.
- imageBase64Datastring
-
If
outputType
is set tobase64Data
, this parameter contains the base64-encoded image data.
- imageDataURIstring
-
If
outputType
is set todataURI
, this parameter contains the data URI of the image.
- seedinteger
-
The seed value that was used to generate this image. This value can be used to reproduce the same image when using identical parameters in another request.
- NSFWContentboolean
-
If checkNSFW parameter is used,
NSFWContent
is included informing if the image has been flagged as potentially sensitive content.true
indicates the image has been flagged (is a sensitive image).false
indicates the image has not been flagged.
The filter occasionally returns false positives and very rarely false negatives.
Here’s the response to the previous request, illustrating the common parameters:
{
"data": [
{
"taskType": "imageInference",
"imageUUID": "97ae27b6-1d52-4815-a5d6-301428d668b1",
"taskUUID": "a770f077-f413-47de-9dac-be0b26a35da6",
"NSFWContent": false,
"cost": 0.0027,
"seed": 3614157524222286418,
"imageURL": "https://im.runware.ai/image/ws/2/ii/97ae27b6-1d52-4815-a5d6-301428d668b1.jpg"
},
{
"taskType": "imageInference",
"imageUUID": "a70ec6e4-8845-45b3-9993-bd02a6d7f88e",
"taskUUID": "a770f077-f413-47de-9dac-be0b26a35da6",
"NSFWContent": false,
"cost": 0.0027,
"seed": 3614157524222286419,
"imageURL": "https://im.runware.ai/image/ws/2/ii/a70ec6e4-8845-45b3-9993-bd02a6d7f88e.jpg"
}
]
}
Specialized guides
For detailed information about specific image inference operations, see these dedicated guides:
- Text-to-image guide: Creating images from text descriptions.
- Image-to-image guide: Transforming existing images.
- Inpainting guide: Selectively editing image regions.
- Outpainting guide: Extending image boundaries.