kie-ruby

A Ruby client library for interacting with the Kie.ai API. Supports both General models for image generation and Suno models for music generation.

Requirements

• Ruby 3.0 or higher

Installation

Add this line to your application's Gemfile:

gem "kie-ruby"

And then execute:

bundle install

Or install it yourself as:

gem install kie-ruby

Quick Start

Setting up your API Key

Get your API key from Kie.ai and configure it:

Option 1: Environment variable (Recommended)

export KIE_API_KEY=your_api_key_here

require "kie"

client = Kie::Client.new

Option 2: Direct configuration

require "kie"

client = Kie::Client.new(api_key: "your_api_key_here")

Usage Examples

Image Generation (General API)

Generate images using the nano-banana-pro model:

require "kie"

client = Kie::Client.new

# Create an image generation task
task = client.general.generate(
  model: "nano-banana-pro",
  input: { prompt: "A serene Japanese garden with cherry blossoms" },
  aspect_ratio: "16:9",
  resolution: "2K",
  output_format: "png"
)

# Wait for completion (polls automatically)
task.wait

# Get the generated image URLs
task.urls.each do |url|
  puts url
end

Music Generation (Suno API)

Generate music using the Suno V5 model:

Simple mode (describe the song):

require "kie"

client = Kie::Client.new

# Create a music generation task
task = client.suno.generate(
  model: "V5",
  input: {
    prompt: "An upbeat electronic dance track with energetic synths",
    callback_url: "https://your-server.com/webhook"  # Optional webhook URL
  }
)

# Wait for completion with progress monitoring
task.wait(timeout: 600, interval: 5)

# Get the generated audio and cover image URLs
puts "Audio files:"
task.audio_urls.each { |url| puts "  #{url}" }

puts "Cover images:"
task.image_urls.each { |url| puts "  #{url}" }

Custom mode (specify lyrics and style):

task = client.suno.generate(
  model: "V5",
  input: {
    custom_mode: true,
    prompt: "[Verse]\nWalking through the city lights\n[Chorus]\nWe are alive tonight",
    style: "Pop, Electronic, Upbeat",
    title: "City Lights",
    callback_url: "https://your-server.com/webhook"
  }
)

task.wait(timeout: 600)

task.audio_urls.each { |url| puts url }

Monitoring Task Progress

You can check task status manually instead of using wait:

task = client.general.generate(model: "nano-banana-pro", input: { prompt: "A sunset" })

loop do
  task.refresh!

  case task.status
  when :processing
    puts "Still processing..."
  when :success
    puts "Done! URLs: #{task.urls}"
    break
  when :failed
    puts "Failed: #{task.error_message}"
    break
  end

  sleep 3
end

Error Handling

The library provides structured exception classes for different error scenarios:

require "kie"

client = Kie::Client.new

begin
  task = client.general.generate(
    model: "nano-banana-pro",
    input: { prompt: "A beautiful landscape" }
  )
  task.wait

  puts task.urls
rescue Kie::AuthenticationError => e
  # Invalid or missing API key (HTTP 401)
  puts "Authentication failed: #{e.message}"

rescue Kie::InsufficientCreditsError => e
  # Not enough credits (HTTP 402)
  puts "Insufficient credits. Please top up your account."

rescue Kie::RateLimitError => e
  # Too many requests (HTTP 429)
  puts "Rate limited. Please wait and retry."
  sleep 10
  retry

rescue Kie::ContentPolicyError => e
  # Content violates policy (e.g., SENSITIVE_WORD_ERROR)
  puts "Content policy violation: #{e.message}"

rescue Kie::TimeoutError => e
  # Task did not complete within the timeout period
  puts "Task timed out"

rescue Kie::TaskFailedError => e
  # Task failed during processing
  puts "Task failed: #{e.message}"
  puts "Fail code: #{e.fail_code}"

rescue Kie::ApiError => e
  # Other API errors
  puts "API error (#{e.status_code}): #{e.message}"
end

Handling Task Failures Without Exceptions

If you prefer to handle failures without exceptions:

task = client.suno.generate(
  model: "V5",
  input: { prompt: "A jazz song", callback_url: "https://your-server.com/webhook" }
)
task.wait(raise_on_failure: false)

if task.failed?
  puts "Task failed: #{task.error_message}"
else
  puts "Success! #{task.urls}"
end

Supported Models

Suno Models (Music Generation)

Model	Description
V4	Suno V4
V4_5	Suno V4.5
V4_5PLUS	Suno V4.5+
V4_5ALL	Suno V4.5 ALL
V5	Suno V5 (Latest)

Suno model input parameters:

Parameter	Type	Description
prompt	String	Song description or lyrics (required)
callback_url	String	Webhook URL for notifications (optional)
custom_mode	Boolean	Enable custom mode for lyrics input
style	String	Music style (custom mode only)
title	String	Song title (custom mode only)
instrumental	Boolean	Generate instrumental only

General Models (Image Generation)

Model	Description
nano-banana-pro	High-quality image generation

General model parameters:

Parameter	Values	Default
aspect_ratio	1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, auto	1:1
resolution	1K, 2K, 4K	1K
output_format	png, jpg	png

Platform Limits

Item	Limit
Rate limit	20 requests per 10 seconds
Concurrent tasks	100
Polling rate	3 requests per second per task
File retention	14 days

Development

Setup

After checking out the repo, run the setup script to install dependencies:

bin/setup

Running Tests

bundle exec rspec

Linting

bundle exec rubocop

Interactive Console

bin/console

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/douhashi/kie-ruby.

License

This gem is available as open source under the terms of the MIT License.