Method: Stability::Client#generate_sd3

Defined in:
lib/stability/client.rb

#generate_sd3(prompt, options: {}, json: false) ⇒ Object

Performs a text-to-image or image-to-image generation request to the Stability API using Stable Diffusion 3.

Parameters:

  • prompt (String) —

    Descriptive prompt for the desired output image. Elements, colors, and subjects should be well-defined for optimal results. Use the format (word:weight) to control the weight of specific words, e.g., “The sky was a crisp (blue:0.3) and (green:0.8)” indicates a sky more green than blue.

  • options (Hash) (defaults to: {}) —

    Additional options for the request:

    • aspect_ratio [String] Specifies the aspect ratio of the generated image. Options: “16:9”, “1:1” (default), “21:9”, “2:3”, “3:2”, “4:5”, “5:4”, “9:16”, “9:21”

    • mode [String] Controls whether this is a text-to-image or image-to-image generation. Options: “text-to-image” (default), “image-to-image”

    • image [File] Required if mode is “image-to-image”. The input image file.

    • strength [Float] Required if mode is “image-to-image”. Controls the strength of the transformation.

    • negative_prompt [String] Describes elements to be excluded from the image. Max 10000 characters.

    • model [String] Specifies the model to use for generation. Options: “sd3” (default), “sd3-turbo”

    • seed [Integer] Controls the randomness of generation, where 0 uses a random seed. Range: 0 (default) to 4294967294

    • output_format [String] Specifies the format of the generated image. Options: “jpeg”, “png” (default)

  • json (Boolean) (defaults to: false) —

    Specifies whether to return the response as a JSON object containing a base64 encoded image or as image bytes directly. Default is false (image bytes directly).



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/stability/client.rb', line 87

def generate_sd3(prompt, options: {}, json: false)
  headers = { "Accept" => json ? "application/json" : "image/*" }
  parameters = { prompt: }.merge(options)

  # Ensure required parameters for image-to-image mode
  if parameters[:mode] == "image-to-image"
    raise ArgumentError, "image is required for image-to-image mode" unless parameters[:image]
    raise ArgumentError, "strength is required for image-to-image mode" unless parameters[:strength]
  end

  multipart_post(path: "/stable-image/generate/sd3", headers:, parameters:).tap do |response|
    raise ServerError, "Empty response from Stability. Might be worth retrying once or twice." if response.blank?
    raise ServerError, response.dig("error", "message") if response.dig("error", "message").present?
  end.with_indifferent_access
end