llm4s-core
API
Generated with
llm4s-core/org.llm4s/org.llm4s.imagegeneration/org.llm4s.imagegeneration.provider/HuggingFaceClient

HuggingFaceClient

org.llm4s.imagegeneration.provider.HuggingFaceClient
class HuggingFaceClient(config: HuggingFaceConfig, httpClient: HttpClient) extends ImageGenerationClient

HuggingFace Inference API client for image generation.

This client provides access to HuggingFace's hosted diffusion models through their Inference API. It supports popular models like Stable Diffusion and other text-to-image models available on the HuggingFace Hub.

Value parameters

config

Configuration containing API key and model settings

Attributes

Example 
val config = HuggingFaceConfig(
 apiKey = "your-hf-token",
 model = "stabilityai/stable-diffusion-2-1"
)
val client = new HuggingFaceClient(config)
client.generateImage("a beautiful sunset over mountains") match {
 case Right(image) => println(s"Generated image: $${image.size}")
 case Left(error) => println(s"Error: $${error.message}")
}
Graph
Supertypes
class Object
trait Matchable
class Any

Members list

Value members

Concrete methods

def buildPayload(prompt: String, options: ImageGenerationOptions): Either[ImageGenerationError, String]

Builds the JSON payload required for the HuggingFace Inference API based on the provided prompt and image generation options.

Builds the JSON payload required for the HuggingFace Inference API based on the provided prompt and image generation options.

Value parameters

options

The image generation options such as size, seed, guidance scale, etc.

prompt

The text description for the image generation.

Attributes

Returns

Either an ImageGenerationError if payload creation fails, or the JSON string representing the payload.

def convertToBase64(imageBytes: Array[Byte]): Either[ImageGenerationError, String]

Base64-encodes raw image bytes received directly from the HTTP layer.

Base64-encodes raw image bytes received directly from the HTTP layer.

Takes the exact wire bytes so no charset round-trip occurs. The previous approach (response.body.getBytes(ISO_8859_1)) was lossy: BodyHandlers.ofString decoded bytes as UTF-8, replacing invalid sequences with U+FFFD, which ISO_8859_1 then mapped to ? (0x3F), corrupting binary image data.

Value parameters

imageBytes

Raw bytes from the HTTP response body.

Attributes

Returns

Either an ImageGenerationError in case of a failure or the resulting Base64-encoded string on success.

def createJsonPayload(huggingClientPayload: HuggingClientPayload): String

Serializes a HuggingClientPayload object into a JSON string.

Serializes a HuggingClientPayload object into a JSON string.

Value parameters

huggingClientPayload

The payload object containing input text and generation parameters to be serialized into JSON format.

Attributes

Returns

The JSON string representation of the provided HuggingClientPayload object.

override def editImage(imagePath: Path, prompt: String, maskPath: Option[Path], options: ImageEditOptions): Either[ImageGenerationError, Seq[GeneratedImage]]

Edit an existing image based on a prompt and optional mask.

Edit an existing image based on a prompt and optional mask.

Not currently supported for HuggingFace provider.

Attributes

Definition Classes
override def editImageAsync(imagePath: Path, prompt: String, maskPath: Option[Path], options: ImageEditOptions)(implicit ec: ExecutionContext): Future[Either[ImageGenerationError, Seq[GeneratedImage]]]

Edit an existing image asynchronously

Edit an existing image asynchronously

Attributes

Definition Classes
def generateAllImages(prompt: String, count: Int, options: ImageGenerationOptions, base64Data: String): Either[ImageGenerationError, IndexedSeq[GeneratedImage]]

Generates multiple images based on the given text prompt using predefined options and base64-encoded image data.

Generates multiple images based on the given text prompt using predefined options and base64-encoded image data.

This method creates a sequence of GeneratedImage objects by iteratively adding offsets to the provided seed (if present in the options). It handles errors by returning an ImageGenerationError wrapped in an Either.

Value parameters

base64Data

The base64-encoded image data that will be used to populate each generated image.

count

The number of images to generate. Ensures the specified number of iterations in the generation process.

options

Optional parameters for image generation, including size, format, seed, guidance scale, etc.

prompt

The text description of the images to be generated.

Attributes

Returns

Either an ImageGenerationError in case of a generation issue, or an IndexedSeq of GeneratedImage objects containing all successfully created images.

override def generateImage(prompt: String, options: ImageGenerationOptions): Either[ImageGenerationError, GeneratedImage]

Generate a single image from a text prompt using HuggingFace Inference API.

Generate a single image from a text prompt using HuggingFace Inference API.

Value parameters

options

Optional generation parameters like size, guidance scale, etc.

prompt

The text description of the image to generate

Attributes

Returns

Either an error or the generated image

Definition Classes
override def generateImageAsync(prompt: String, options: ImageGenerationOptions)(implicit ec: ExecutionContext): Future[Either[ImageGenerationError, GeneratedImage]]

Generate an image asynchronously

Generate an image asynchronously

Attributes

Definition Classes
override def generateImages(prompt: String, count: Int, options: ImageGenerationOptions): Either[ImageGenerationError, Seq[GeneratedImage]]

Generate multiple images from a text prompt using HuggingFace Inference API.

Generate multiple images from a text prompt using HuggingFace Inference API.

Note: HuggingFace Inference API typically returns one image per request, so multiple images are generated by making the same request multiple times with different seeds.

Value parameters

count

Number of images to generate (1-4)

options

Optional generation parameters like size, guidance scale, etc.

prompt

The text description of the images to generate

Attributes

Returns

Either an error or a sequence of generated images

Definition Classes
override def generateImagesAsync(prompt: String, count: Int, options: ImageGenerationOptions)(implicit ec: ExecutionContext): Future[Either[ImageGenerationError, Seq[GeneratedImage]]]

Generate multiple images asynchronously

Generate multiple images asynchronously

Attributes

Definition Classes
override def health(): Either[ImageGenerationError, ServiceStatus]

Check the health status of the HuggingFace Inference API.

Check the health status of the HuggingFace Inference API.

Attributes

Returns

Either an error or the current service status

Definition Classes
def makeHttpRequest(payload: String): Either[ImageGenerationError, Array[Byte]]

Makes an HTTP POST request to the HuggingFace Inference API and returns the raw response bytes.

Makes an HTTP POST request to the HuggingFace Inference API and returns the raw response bytes.

Uses postRaw so the binary image payload is never decoded through a charset, preventing the corruption that occurred when BodyHandlers.ofString decoded bytes as UTF-8 and they were then re-encoded with ISO_8859_1.

Value parameters

payload

The JSON payload to send with the HTTP request.

Attributes

Returns

Either an ImageGenerationError if the request fails, or the raw image bytes on success.

def validateCount(count: Int): Either[ImageGenerationError, Int]

Validates the provided count to ensure it is within the allowable range for image generation (1 to 4 inclusive, for HuggingFace).

Validates the provided count to ensure it is within the allowable range for image generation (1 to 4 inclusive, for HuggingFace).

Value parameters

count

The number of images requested for generation. Must be between 1 and 4.

Attributes

Returns

Either an ImageGenerationError if the count is out of range, or the valid count as an Int if the validation succeeds.

def validatePrompt(prompt: String): Either[ImageGenerationError, String]

Validates the provided prompt to ensure it is not empty or blank.

Validates the provided prompt to ensure it is not empty or blank.

Value parameters

prompt

The input string representing the prompt to validate.

Attributes

Returns

Either an ImageGenerationError if the validation fails, or the original valid prompt as a String.

Generated with