tryiton 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dc7c9b0e58bea7120e432b59b8db60364d95f66f2962fdc54e04a64602d8d757
+  data.tar.gz: e1f08ab852de54a201dc962e9799d35853b7b7a8c1da8c6947e3d1d135a85814
+SHA512:
+  metadata.gz: b577a2d18b96023088aa636b0a287ec4a96581c264017fbc0aefb981af926b8bc49d1437964738e52e43da421628b7725028b7ac94dc54ca490c981769e4b445
+  data.tar.gz: 327f7c89b5a2b35f6dad23b60faaaaf6ee21e4ff7d39a42ea87ad29651eadd11c95679c000cc5c655893f386ecfd92104c05c38122009329a9969705dbb4d859

data/README.md

@@ -0,0 +1,99 @@
+# TryItOn Ruby SDK — AI Virtual Try-On API
+
+Official Ruby client for the [TryItOn](https://tryiton.now) virtual try-on API. Add photoreal AI virtual try-on for clothing, accessories, hairstyles, and tattoos to your Ruby or Rails application with a few lines of code.
+
+- Virtual clothing try-on and accessory try-on (eyewear, footwear, headwear, jewelry)
+- Hairstyle and tattoo try-on
+- Standard library only (no dependencies), with a built-in job polling helper
+
+Full API reference: [docs.tryiton.now](https://docs.tryiton.now) · Get an API key: [tryiton.now/app/developer](https://tryiton.now/app/developer)
+
+## Installation
+
+```bash
+gem install tryiton
+```
+
+Or add it to your Gemfile:
+
+```ruby
+gem "tryiton"
+```
+
+Requires Ruby 2.6 or later.
+
+## Quickstart: run a virtual try-on
+
+Submit a garment and a model photo, then wait for the generated result image.
+
+```ruby
+require "tryiton"
+
+client = Tryiton::Client.new(api_key: ENV["TRYITON_API_KEY"])
+
+# Submit a clothing try-on
+job_id = client.try_on_clothes(
+  model_image: "https://example.com/model.jpg",
+  garment_image: "https://example.com/tshirt.jpg",
+  category: "clothing",
+  subcategory: "tops"
+)
+
+# Poll until the job completes and return the output image URL(s)
+urls = client.wait_for_result(job_id)
+puts urls.first # CDN URL, available for 72 hours
+```
+
+Image inputs accept a public URL or a base64 data URL (`data:image/png;base64,...`).
+
+## Core parameters
+
+`try_on_clothes` covers clothing and accessory try-on. The most important parameters:
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `model_image` | String | Yes | URL or base64 data URL of the person. |
+| `garment_image` | String | Yes | URL or base64 data URL of the garment or accessory. |
+| `category` | String | No | Item type: `auto`, `clothing`, `eyewear`, `footwear`, `headwear`, `jewelry`, `accessories`, or `others`. `auto` detects it for you. |
+| `subcategory` | String | No | Required for `clothing` (`tops`, `bottoms`, `dresses`), `jewelry`, and `accessories`. |
+
+Additional options (`mode` and `moderation_level` for clothing; `num_samples` 1–4 and `output_format` `png`/`jpeg` for every try-on, including hairstyle and tattoo) are documented in the [API reference](https://docs.tryiton.now).
+
+## Other endpoints
+
+```ruby
+# Hairstyle try-on (see Tryiton::HAIRCUTS for all supported values)
+client.try_on_hairstyle(face_image: face_url, haircut: "BuzzCut", hair_color: "ash blonde")
+
+# Tattoo try-on
+client.try_on_tattoo(body_image: body_url, design_image: design_url, placement: "on the right forearm, small")
+
+# Poll a job manually, or check your credit balance
+status  = client.get_status(job_id)  # { "status" => ..., "output" => [...], "error" => ... }
+credits = client.get_credits          # { "on_demand" => ..., "subscription" => ..., "purchased" => ..., "reserved" => ... }
+```
+
+## Error handling
+
+All failures raise `Tryiton::Error`, which carries the HTTP status code and the API error name.
+
+```ruby
+begin
+  client.try_on_clothes(...)
+rescue Tryiton::Error => e
+  puts "#{e.status} #{e.error_name} #{e.message}" # e.g. 429 OutOfCredits
+end
+```
+
+## Notes
+
+- Output image URLs expire 72 hours after completion. Download any results you want to keep.
+- Failed jobs are never charged.
+
+## Documentation
+
+Full documentation, parameter reference, and guides: [docs.tryiton.now](https://docs.tryiton.now)
+
+## License
+
+MIT

data/lib/tryiton/client.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Tryiton
+  # Raised for API-level errors and runtime (job) failures.
+  #
+  #   status      - HTTP status code, or nil for a runtime job failure.
+  #   error_name  - the API error name, e.g. "OutOfCredits" / "ProcessingError".
+  class Error < StandardError
+    attr_reader :status, :error_name
+
+    def initialize(message, status: nil, error_name: nil)
+      super(message)
+      @status = status
+      @error_name = error_name
+    end
+  end
+
+  # Supported `haircut` values for hairstyle try-on.
+  HAIRCUTS = %w[
+    Afro BobCut BowlCut BoxBraids BuzzCut Chignon CombOver CornrowBraids CurlyBob
+    CurlyShag DoubleBun Dreadlocks FauxHawk FishtailBraid LongCurly LongHairTiedUp
+    LongHimeCut LongStraight LongTwintails LongWavy LongWavyCurtainBangs ManBun
+    MessyTousled PixieCut Pompadour Ponytail ShortCurlyPixie ShortTwintails
+    ShoulderLengthHair Spiky TexturedFringe TwinBraids Updo WavyShag
+  ].freeze
+
+  # Client for the TryItOn virtual try-on API.
+  #
+  #   client = Tryiton::Client.new(api_key: ENV["TRYITON_API_KEY"])
+  #   job_id = client.try_on_clothes(
+  #     model_image: "https://example.com/model.jpg",
+  #     garment_image: "https://example.com/tshirt.jpg",
+  #     category: "clothing", subcategory: "tops"
+  #   )
+  #   urls = client.wait_for_result(job_id)
+  #
+  # See https://docs.tryiton.now
+  class Client
+    DEFAULT_BASE_URL = "https://tryiton.now/api/v1"
+
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: 60)
+      raise Error.new("An api_key is required.", error_name: "ConfigError") if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @base_url = base_url.sub(%r{/+\z}, "")
+      @timeout = timeout
+    end
+
+    # Put a garment or accessory on a person. Returns the job id.
+    # Keys: model_image (required), garment_image (required), category,
+    # subcategory, mode, num_samples (1-4), output_format ("png"/"jpeg"),
+    # moderation_level ("conservative"/"permissive"/"none").
+    def try_on_clothes(**params)
+      request(:post, "/tryon/clothes", params)["jobId"]
+    end
+
+    # Restyle a person's hair. Returns the job id.
+    # Keys: face_image (required), haircut (required), hair_color,
+    # num_samples (1-4), output_format ("png"/"jpeg").
+    def try_on_hairstyle(**params)
+      request(:post, "/tryon/hairstyle", params)["jobId"]
+    end
+
+    # Ink a design onto skin. Returns the job id.
+    # Keys: body_image (required), design_image (required), placement,
+    # num_samples (1-4), output_format ("png"/"jpeg").
+    def try_on_tattoo(**params)
+      request(:post, "/tryon/tattoo", params)["jobId"]
+    end
+
+    # Fetch the current status of a job.
+    # Returns { "status" => ..., "output" => [...], "error" => ... }.
+    def get_status(job_id)
+      data = request(:get, "/status/#{URI.encode_www_form_component(job_id)}")
+      { "status" => data["status"] || "processing", "output" => data["output"] || [], "error" => data["error"] }
+    end
+
+    # Fetch your current credit balance.
+    def get_credits
+      request(:get, "/credits")["credits"]
+    end
+
+    # Poll a job until it completes, then return the output image URLs.
+    # Raises Tryiton::Error if the job fails or the timeout is reached.
+    def wait_for_result(job_id, poll_interval: 2.0, timeout: 120.0)
+      deadline = monotonic + timeout
+      loop do
+        status = get_status(job_id)
+        return status["output"] if status["status"] == "completed"
+
+        if status["status"] == "failed"
+          err = status["error"] || {}
+          raise Error.new(err["message"] || "Try-on failed.", error_name: err["name"] || "ProcessingError")
+        end
+
+        raise Error.new("Timed out waiting for job #{job_id}.", error_name: "Timeout") if monotonic > deadline
+
+        sleep(poll_interval)
+      end
+    end
+
+    private
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def request(method, path, body = nil)
+      uri = URI.parse("#{@base_url}#{path}")
+      req =
+        case method
+        when :post then Net::HTTP::Post.new(uri)
+        else Net::HTTP::Get.new(uri)
+        end
+      req["Authorization"] = "Bearer #{@api_key}"
+
+      unless body.nil?
+        compact = body.reject { |_, v| v.nil? }
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(compact)
+      end
+
+      begin
+        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https", read_timeout: @timeout) do |http|
+          http.request(req)
+        end
+      rescue StandardError => e
+        raise Error.new("Network error: #{e.message}", error_name: "NetworkError")
+      end
+
+      data =
+        begin
+          res.body && !res.body.empty? ? JSON.parse(res.body) : {}
+        rescue JSON::ParserError
+          {}
+        end
+
+      code = res.code.to_i
+      unless (200..299).cover?(code)
+        raise Error.new(data["message"] || "HTTP #{code}", status: code, error_name: data["error"])
+      end
+
+      data
+    end
+  end
+end

data/lib/tryiton/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Tryiton
+  VERSION = "1.0.0"
+end

data/lib/tryiton.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "tryiton/version"
+require_relative "tryiton/client"
+
+# Official Ruby SDK for the TryItOn virtual try-on API.
+# See https://docs.tryiton.now
+module Tryiton
+end

metadata

@@ -0,0 +1,47 @@
+--- !ruby/object:Gem::Specification
+name: tryiton
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- TryItOn
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Add photoreal clothing, accessory, hairstyle, and tattoo virtual try-on
+  to your app.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/tryiton.rb
+- lib/tryiton/client.rb
+- lib/tryiton/version.rb
+homepage: https://docs.tryiton.now
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://tryiton.now
+  documentation_uri: https://docs.tryiton.now
+  source_code_uri: https://github.com/tryiton-now/tryiton-ruby
+  bug_tracker_uri: https://github.com/tryiton-now/tryiton-ruby/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Ruby SDK for the TryItOn virtual try-on API.
+test_files: []