Package net.paulem.aihorde4j.client

Class HordeClient

java.lang.Object
net.paulem.aihorde4j.client.HordeClient
All Implemented Interfaces:
AutoCloseable
public class HordeClient extends Object implements AutoCloseable
Main client for interacting with the AI Horde API. This client is thread-safe and supports both synchronous and asynchronous operations.

  • Field Details

    • DEFAULT_BASE_URL

      public static final String DEFAULT_BASE_URL
      Default base URL for the AI Horde API.
      See Also:

    • DEFAULT_API_KEY

      public static final String DEFAULT_API_KEY
      Default anonymous API key.
      See Also:

    • DEFAULT_POLL_INTERVAL_MS

      public static final long DEFAULT_POLL_INTERVAL_MS
      Default polling interval in milliseconds.
      See Also:

    • DEFAULT_GENERATION_TIMEOUT_SECONDS

      public static final long DEFAULT_GENERATION_TIMEOUT_SECONDS
      Default timeout for generation requests in seconds.
      See Also:

  • Method Details

    • builder

      public static HordeClient.Builder builder()
      Creates a new builder for HordeClient.
      Returns:
      A new builder instance

    • createDefault

      public static HordeClient createDefault()
      Creates a default client with anonymous access.
      Returns:
      A new HordeClient with default configuration

    • withApiKey

      public static HordeClient withApiKey(String apiKey)
      Creates a client with the specified API key.
      Parameters:
      apiKey - The API key to use
      Returns:
      A new HordeClient

    • getApi

      public HordeApi getApi()
      Gets the underlying Retrofit API interface for direct access.
      Returns:
      The HordeApi interface

    • submitImageGeneration

      public RequestAsync submitImageGeneration(GenerationInputStable request)
      Submits an image generation request.
      Parameters:
      request - The generation request
      Returns:
      The async request containing the job ID
      Throws:
      HordeException - if the request fails

    • checkImageGeneration

      public RequestStatusCheck checkImageGeneration(String requestId)
      Checks the status of an image generation request.
      Parameters:
      requestId - The request ID from submitImageGeneration
      Returns:
      The status check result
      Throws:
      HordeException - if the request fails

    • getImageGenerationStatus

      public RequestStatusStable getImageGenerationStatus(String requestId)
      Gets the full status and results of an image generation request.
      Parameters:
      requestId - The request ID
      Returns:
      The full status with generated images
      Throws:
      HordeException - if the request fails

    • cancelImageGeneration

      public RequestStatusStable cancelImageGeneration(String requestId)
      Cancels a pending image generation request.
      Parameters:
      requestId - The request ID
      Returns:
      The status after cancellation
      Throws:
      HordeException - if the request fails

    • generateImage

      public RequestStatusStable generateImage(String prompt)
      Generates an image synchronously, polling until completion.
      Parameters:
      prompt - The prompt for image generation
      Returns:
      The result containing generated images
      Throws:
      HordeException - if the generation fails

    • generateImage

      public RequestStatusStable generateImage(String prompt, ModelGenerationInputStable params, List<String> models, GenerationProgressCallback progressCallback)
      Generates an image synchronously with custom parameters.
      Parameters:
      prompt - The prompt for image generation
      params - Optional generation parameters
      models - Optional list of models to use
      progressCallback - Optional callback for progress updates
      Returns:
      The result containing generated images
      Throws:
      HordeException - if the generation fails

    • generateImage

      public RequestStatusStable generateImage(GenerationInputStable request, GenerationProgressCallback progressCallback)
      Generates an image synchronously with a full request object.
      Parameters:
      request - The full generation request
      progressCallback - Optional callback for progress updates
      Returns:
      The result containing generated images
      Throws:
      HordeException - if the generation fails

    • generateImageAsync

      public CompletableFuture<RequestStatusStable> generateImageAsync(String prompt)
      Generates an image asynchronously.
      Parameters:
      prompt - The prompt for image generation
      Returns:
      A CompletableFuture that completes with the result

    • generateImageAsync

      public CompletableFuture<RequestStatusStable> generateImageAsync(String prompt, ModelGenerationInputStable params, List<String> models, GenerationProgressCallback progressCallback)
      Generates an image asynchronously with custom parameters.
      Parameters:
      prompt - The prompt for image generation
      params - Optional generation parameters
      models - Optional list of models to use
      progressCallback - Optional callback for progress updates
      Returns:
      A CompletableFuture that completes with the result

    • submitTextGeneration

      public RequestAsync submitTextGeneration(GenerationInputKobold request)
      Submits a text generation request.
      Parameters:
      request - The generation request
      Returns:
      The async request containing the job ID
      Throws:
      HordeException - if the request fails

    • checkTextGeneration

      public RequestStatusCheck checkTextGeneration(String requestId)
      Checks the status of a text generation request.
      Parameters:
      requestId - The request ID
      Returns:
      The status check result
      Throws:
      HordeException - if the request fails

    • getTextGenerationStatus

      public RequestStatusKobold getTextGenerationStatus(String requestId)
      Gets the full status and results of a text generation request.
      Parameters:
      requestId - The request ID
      Returns:
      The full status with generated text
      Throws:
      HordeException - if the request fails

    • cancelTextGeneration

      public RequestStatusKobold cancelTextGeneration(String requestId)
      Cancels a pending text generation request.
      Parameters:
      requestId - The request ID
      Returns:
      The status after cancellation
      Throws:
      HordeException - if the request fails

    • generateText

      public RequestStatusKobold generateText(String prompt)
      Generates text synchronously, polling until completion.
      Parameters:
      prompt - The prompt for text generation
      Returns:
      The result containing generated text
      Throws:
      HordeException - if the generation fails

    • generateText

      public RequestStatusKobold generateText(String prompt, ModelGenerationInputKobold params, List<String> models, GenerationProgressCallback progressCallback)
      Generates text synchronously with custom parameters.
      Parameters:
      prompt - The prompt for text generation
      params - Optional generation parameters
      models - Optional list of models to use
      progressCallback - Optional callback for progress updates
      Returns:
      The result containing generated text
      Throws:
      HordeException - if the generation fails

    • generateText

      public RequestStatusKobold generateText(GenerationInputKobold request, GenerationProgressCallback progressCallback)
      Generates text synchronously with a full request object.
      Parameters:
      request - The full generation request
      progressCallback - Optional callback for progress updates
      Returns:
      The result containing generated text
      Throws:
      HordeException - if the generation fails

    • generateTextAsync

      public CompletableFuture<RequestStatusKobold> generateTextAsync(String prompt)
      Generates text asynchronously.
      Parameters:
      prompt - The prompt for text generation
      Returns:
      A CompletableFuture that completes with the result

    • generateTextAsync

      public CompletableFuture<RequestStatusKobold> generateTextAsync(String prompt, ModelGenerationInputKobold params, List<String> models, GenerationProgressCallback progressCallback)
      Generates text asynchronously with custom parameters.
      Parameters:
      prompt - The prompt for text generation
      params - Optional generation parameters
      models - Optional list of models to use
      progressCallback - Optional callback for progress updates
      Returns:
      A CompletableFuture that completes with the result

    • findUser

      public UserDetails findUser()
      Gets the details of the authenticated user.
      Returns:
      The user details
      Throws:
      HordeException - if the request fails

    • getActiveModels

      public List<ActiveModel> getActiveModels()
      Gets all active models.
      Returns:
      The list of active models
      Throws:
      HordeException - if the request fails

    • getActiveModels

      public List<ActiveModel> getActiveModels(String type)
      Gets active models filtered by type.
      Parameters:
      type - The model type ("image" or "text")
      Returns:
      The list of active models
      Throws:
      HordeException - if the request fails

    • getActiveModels

      public List<ActiveModel> getActiveModels(String type, Integer minCount)
      Gets active models filtered by type and minimum worker count.
      Parameters:
      type - The model type ("image" or "text")
      minCount - The minimum number of workers
      Returns:
      The list of active models
      Throws:
      HordeException - if the request fails

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable