StabilitySDK - Ruby client for stability.ai APIs, such as Stable Diffusion

A ruby client for stability.ai APIs, e.g., Stable Diffusion. Referring to https://github.com/Stability-AI/stability-sdk.

Installation

Add this line to your application's Gemfile:

gem 'stability_sdk'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install stability_sdk

Usage

First, you need to create a DreamStudio's account and get an API Key of it.

Access DreamStudio and create an account if you have not had it
Go to the membership page
You can get the API Key in an API Key tab

Command line usage

STABILITY_SDK_API_KEY=YOUR_API_KEY stability-client 'A night in winter, oil-on-canvas landscape painting, by Vincent van Gogh'

This command saves an image like this:

img2img example:

STABILITY_SDK_API_KEY=YOUR_API_KEY stability-client --init_image=/path/to/image.png --mask_image=/path/to/mask.png 'your prompt'

Usage: stability-client [options] YOUR_PROMPT_TEXT

Options:
        --api_key=VAL                api key of DreamStudio account. You can also specify by a STABILITY_SDK_API_KEY environment variable
    -H, --height=VAL                 height of image in pixel. default 512
    -W, --width=VAL                  width of image in pixel. default 512
    -C, --cfg_scale=VAL              CFG scale factor. default 7.0
    -A, --sampler=VAL                ddim, plms, k_euler, k_euler_ancestral, k_heun, k_dpm_2, k_dpm_2_ancestral, k_lms, k_dpmpp_2s_ancestral, k_dpmpp_2m, k_dpmpp_sde. default auto-select
    -s, --steps=VAL                  number of steps. default auto-select
    -S, --seed=VAL                   random seed to use in integer
    -p, --prefix=VAL                 output prefixes for artifacts. default `generation`
        --no-store                   do not write out artifacts
    -n, --num_samples=VAL            number of samples to generate. default 1
    -e, --engine=VAL                 engine to use for inference. default `stable-diffusion-xl-1024-v1-0`
    -i, --init_image=VAL             path to init image
    -m, --mask_image=VAL             path to mask image
        --start_schedule=VAL         start schedule for init image (must be greater than 0, 1 is full strength text prompt, no trace of image). default 1.0
        --end_schedule=VAL           end schedule for init image. default 0.01
        --guidance_preset=VAL        Guidance preset to use. See generation.GuidancePreset for supported values. default `GUIDANCE_PRESET_NONE`
        --guidance_cuts=VAL          Number of cuts to use for guidance. default 0
        --guidance_strength=VAL      Strength of the guidance. We recommend values in range [0.0,1.0]. A good default is 0.25. default nil
        --guidance_prompt=VAL        Prompt to use for guidance, defaults to `YOUR_PROMPT_TEXT` argument (above) if not specified.
        --guidance_models=VAL        Models to use for guidance. default nil
    -t, --artifact_types=VAL         filter artifacts by type (ARTIFACT_IMAGE, ARTIFACT_TEXT, ARTIFACT_CLASSIFICATIONS, etc)
        --prompt_weight=VAL          Weight of the prompt. Currently multi-prompting is not supported yet. default 1"
    -v, --verbose

CLIP guidance

By specifying --guidance_preset and other --guidance_* options, you can use CLIP guidance, which is enabled by default on DreamStudio's web interface. See also this notebook for more details.

# example
# [note] --steps=35 is recommended. which is also the default value of the web interface
STABILITY_SDK_API_KEY=xxx stability-client --guidance_preset=GUIDANCE_PRESET_FAST_BLUE --guidance_strength=0.25 --steps=35 --sampler=k_dpm_2_ancestral "A dream of a distant galaxy, by Caspar David Friedrich, matte painting trending on artstation HQ"

SDK usage

This sample code saves a generated image as result.png.

require "stability_sdk"

client = StabilitySDK::Client.new(api_key: "YOUR_API_KEY", timeout: 600)

prompt = "your prompot here"
options = {}

# for the case of img2img:
# options[:init_image] = "/path/to/image.png"
# options[:mask_image] = "/path/to/mask.png"

client.generate(prompt, options) do |answer|
  answer.artifacts.each do |artifact|
    if artifact.type == :ARTIFACT_IMAGE
      File.open("result.png", "wb") do |f|
        f.write(artifact.binary)
      end
    end
  end
end

Dashboard API

Dashboard API is a way to interact with DreamStudio Web UIs, such as getting user info, payment info, etc.

Currently, the API key is only allowed as read-only. And this client supports only GetMe and GetOrganization actions. See also Stability-AI/stability-sdk#23

# get user info
STABILITY_SDK_DASHBOARD_API_KEY=YOUR_API_KEY stability-dashboard-client get_me

# get organization info
STABILITY_SDK_DASHBOARD_API_KEY=YOUR_API_KEY stability-dashboard-client get_organization

# i.e, get remaining balance
STABILITY_SDK_DASHBOARD_API_KEY=YOUR_API_KEY stability-dashboard-client get_organization | jq .paymentInfo.balance

require "stability_sdk"

client = StabilitySDK::DashboardClient.new(api_key: "your api key")
res = client.get_organization
p res.payment_info.balance  # prints a remaining balance

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

update submodule to try a new feature on Stability-AI/api-interfaces

update submodule

git submodule update --init  # if you haven't fetched the content of the submodule yet
cd api-interfaces

# checkout some branch/commit you need
git fetch
git checkout origin/some_branch # or `git reset --hard origin/some_branch`

cd ..
git add

# if you need to follow the updates of submodules inside the Stability-AI/api-interfaces, you have to update submodules recursively
git submodule update --init --recursive

build

bundle exec rake protoc

git diff
# now you may be able to confirm that the diff is created in lib/generation_pb.rb

modify the lib/stability_sdk/client.rb to try some new features

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/cou929/stability-sdk-ruby.

stability_sdk

Development

Runtime

StabilitySDK - Ruby client for stability.ai APIs, such as Stable Diffusion

Installation

Usage

Command line usage

CLIP guidance

SDK usage

Dashboard API

Development

update submodule to try a new feature on Stability-AI/api-interfaces

Contributing