emaki 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 60391feae004e1d2657423237a25638c2b13f9083fdb654aaee9dc7346951aaa
+  data.tar.gz: f60f3d361c2ce90a94a3f166d8052d5d1fbd890d4e07ef8317623a3e2adc9873
+SHA512:
+  metadata.gz: 6759f21e11ef03fd0a390ad8c96811389b9bbaec6af5b7b42adbc9e6e318c45cb071272d4fcbec82967179786a5fc54f13b740c8fad13d21aa11fa2363a0836c
+  data.tar.gz: db2ee405e755c9acc1fa8a51f44bc23f74d26f8592f228f66b8fb5874692c1f66c70a84bd4cb11d1d53414179ca963a0091f3e6acf668db0c2415f4beef481f0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 emaki (https://emaki.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,90 @@
+# emaki
+
+Official SDK for emaki (emaki.ai), the Japanese-language AI video generator for Seedance 2.5 and Seedance 2.0. Generate video and images from your own code with one API key: [Seedance 2.5](https://emaki.ai/seedance-2-5), [Seedance 2.0](https://emaki.ai/seedance-2), [image to video](https://emaki.ai/image-to-video), plus Nano Banana 2, Seedream and GPT Image for stills. To sharpen a finished clip, use the [AI video upscaler](https://emaki.ai/video-upscaler) on the site.
+
+日本語での使い方は [シーダンス](https://emaki.ai/) へ。
+
+```ruby
+require "emaki"
+
+clip = Emaki.generate_video("a paper lantern drifting over a night river, slow dolly")
+img  = Emaki.generate_image("a ramen shop at dusk, isometric")
+```
+
+Each call submits the run, waits for it and returns the URL of the finished file.
+
+## Install
+
+```bash
+gem install emaki
+```
+
+No dependencies beyond the standard library (`net/http`, `json`).
+
+## API key
+
+Sign in on [emaki.ai](https://emaki.ai/?utm_source=rubygems&utm_medium=package), create a key at [emaki.ai/settings/apikeys](https://emaki.ai/settings/apikeys), then export it:
+
+```bash
+export EMAKI_API_KEY=sk-...
+```
+
+A key runs on your account exactly like the site does: same models, same review, and every run costs credits on your emaki account, the same price as on the website.
+
+## Video
+
+The default video model is `seedance_2_5` (Seedance 2.5).
+
+```ruby
+clip = Emaki.generate_video("a fox trotting through fresh snow at dawn, tracking shot",
+  model: "seedance_2_5", duration: 8, resolution: "720p", aspect_ratio: "9:16")
+
+# image to video: the image becomes the first frame
+clip = Emaki.generate_video("the camera slowly orbits the statue",
+  model: "seedance_2", image: "https://example.com/statue.jpg")
+```
+
+| model | parameters |
+|---|---|
+| `seedance_2_5` | `duration` 4-30 · `resolution` 480p / 720p / 1080p · `aspect_ratio` 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive · `generate_audio` · `image` (first frame) · `last_frame_image` |
+| `seedance_2` | `duration` 4-15 · `resolution` 480p / 720p / 1080p · `aspect_ratio` · `generate_audio` · `image` |
+| `seedance_2_fast`, `seedance_2_mini` | `duration` 4-15 · `resolution` 480p / 720p · `aspect_ratio` · `generate_audio` · `image` |
+| `minimax_h3` | `duration` 5-15 · `aspect_ratio` · `image` |
+| `veo_3_1` | `resolution` 720p / 1080p / 4k · `aspectRatio` 16:9 / 9:16 · `image` |
+
+Parameters you leave out take the same defaults as the site.
+
+## Images
+
+The default image model is `nano_banana_2_lite`, the cheapest one.
+
+```ruby
+url = Emaki.generate_image("isometric diorama of a tea house",
+  model: "nano_banana_2", aspect_ratio: "16:9", resolution: "2K")
+```
+
+Image models: `nano_banana_2_lite`, `nano_banana_2` (`resolution` 1K / 2K / 4K), `seedream_5_lite` (`quality` basic / high / ultra), `gpt_image_2` (`resolution` 1K / 2K / 4K); all take `aspect_ratio`.
+
+## Lower level
+
+```ruby
+client = Emaki::Client.new            # reads EMAKI_API_KEY
+id   = client.submit("a koi pond in the rain", model: "seedance_2_mini")
+st   = client.status(id)              # st["status"]: "generating" | "completed" | "failed"
+left = client.credits                 # remaining credits on the account
+```
+
+## Errors worth catching
+
+- `Emaki::AuthError`: no key, or the key is wrong or deleted
+- `Emaki::QuotaError`: the account is out of credits
+- `Emaki::PlanError`: that model unlocks after a credit purchase
+- `Emaki::BusyError`: a generation on this account is already in progress
+- `Emaki::RejectedError`: the content filter refused the prompt or image; reword it rather than retrying
+- `Emaki::ValidationError`: a parameter the API did not accept (the message says which)
+- `Emaki::FailedError`: the run ended as failed; `#failure_code` says why
+- `Emaki::TimeoutError`: the deadline passed (15 minutes by default); the run may still finish in your library
+
+Every finished run also lands in your library on emaki.ai.
+
+MIT licensed. Made by [emaki](https://emaki.ai/?utm_source=rubygems&utm_medium=package), the Japanese-language home for Seedance.

data/lib/emaki/version.rb

@@ -0,0 +1,3 @@
+module Emaki
+  VERSION = "0.1.0"
+end

data/lib/emaki.rb

@@ -0,0 +1,184 @@
+# Official SDK for emaki (https://emaki.ai), the Japanese-language AI video
+# generator for Seedance 2.5 and Seedance 2.0.
+#
+#   require "emaki"
+#   clip = Emaki.generate_video("a paper lantern drifting over a night river")
+#   img  = Emaki.generate_image("a ramen shop at dusk, isometric")
+#
+# Set EMAKI_API_KEY (create a key at https://emaki.ai/settings/apikeys).
+require "json"
+require "net/http"
+require "uri"
+require_relative "emaki/version"
+
+module Emaki
+  BASE_URL = "https://emaki.ai".freeze
+  KEYS_URL = "https://emaki.ai/settings/apikeys".freeze
+  MODEL_VIDEO = "seedance_2_5".freeze
+  MODEL_IMAGE = "nano_banana_2_lite".freeze
+
+  # Base of every error this gem raises. #status is the HTTP status when there was one.
+  class Error < StandardError
+    attr_reader :status
+    def initialize(msg = nil, status: nil)
+      super(msg)
+      @status = status
+    end
+  end
+  # No API key, or the key is invalid or deleted (HTTP 401).
+  class AuthError < Error; end
+  # The account is out of credits (HTTP 402).
+  class QuotaError < Error; end
+  # The model unlocks after a credit purchase (HTTP 403).
+  class PlanError < Error; end
+  # A generation on this account is already in progress (HTTP 409).
+  class BusyError < Error; end
+  # The content filter refused the prompt or image; reword it rather than retrying.
+  class RejectedError < Error; end
+  # A parameter the API did not accept (HTTP 400).
+  class ValidationError < Error; end
+  # The run ended as failed. #failure_code says why.
+  class FailedError < Error
+    attr_reader :failure_code
+    def initialize(code)
+      @failure_code = code
+      super("emaki: generation failed (#{code})")
+    end
+  end
+  # The deadline passed; the run may still finish in your emaki library.
+  class TimeoutError < Error; end
+
+  # Map an HTTP status and error body to the error that says what to do next.
+  def self.classify(status, body)
+    body = {} unless body.is_a?(Hash)
+    msg = (body["error"] || body["message"] || "request failed").to_s
+    tag = body["code"].is_a?(String) ? body["code"] : ""
+    klass =
+      case
+      when status == 401 then AuthError
+      when status == 402 then QuotaError
+      when status == 403 then PlanError
+      when status == 409 then BusyError
+      when %w[content_cooldown content_blocked].include?(tag) then RejectedError
+      when status == 400 then ValidationError
+      # The credits endpoint answers HTTP 200 with code -1.
+      when status == 200 && (msg.downcase.include?("api key") || msg.downcase.include?("unauthorized")) then AuthError
+      else Error
+      end
+    klass.new(klass == Error ? "HTTP #{status}: #{msg}" : msg, status: status)
+  end
+
+  # A client bound to one API key. transport: is a callable (url, body, key) -> [status, hash], for tests.
+  class Client
+    attr_accessor :poll_every, :timeout
+
+    def initialize(api_key = nil, base_url: BASE_URL, poll_every: 5, timeout: 900, transport: nil)
+      @key = (api_key || ENV["EMAKI_API_KEY"]).to_s.strip
+      @base = base_url.chomp("/")
+      @poll_every = poll_every
+      @timeout = timeout
+      @transport = transport || method(:http)
+    end
+
+    # Start a run and return its id without waiting.
+    def submit(prompt, model: MODEL_VIDEO, **params)
+      raise ValidationError, "prompt is required" if prompt.to_s.strip.empty?
+
+      status, body = call("/api/video/ai", { "prompt" => prompt, "model" => model, "parameters" => stringify(params) })
+      id = body.is_a?(Hash) && body["success"] == true && body["data"].is_a?(Hash) && body["data"]["id"]
+      return id if status == 200 && id
+
+      raise Emaki.classify(status, body)
+    end
+
+    # Look up a run; returns the API's data hash ("id", "status", "videoUrl", "failureCode", ...).
+    def status(id)
+      status, body = call("/api/video/status", { "videoId" => id })
+      return body["data"] if status == 200 && body.is_a?(Hash) && body["success"] == true && body["data"].is_a?(Hash)
+
+      raise Emaki.classify(status, body)
+    end
+
+    # Credits left on the account. Free to call.
+    def credits
+      status, body = call("/api/user/get-user-credits", {})
+      if status == 200 && body.is_a?(Hash) && body["code"] == 0 && body["data"].is_a?(Hash)
+        return body["data"]["remainingCredits"].to_i
+      end
+
+      raise Emaki.classify(status, body)
+    end
+
+    # Submit, wait, and return the URL of the finished file.
+    def generate(prompt, model:, **params)
+      wait(submit(prompt, model: model, **params))
+    end
+
+    # Wait for a submitted run and return its URL.
+    def wait(id)
+      deadline = Time.now + @timeout
+      while Time.now < deadline
+        sleep @poll_every
+        begin
+          d = status(id)
+        rescue AuthError
+          raise
+        rescue StandardError
+          next # a dropped poll is not a failed run
+        end
+        case d["status"]
+        when "completed", "succeeded"
+          return d["videoUrl"] if d["videoUrl"]
+        when "failed"
+          raise FailedError, (d["failureCode"] || "unknown")
+        end
+      end
+      raise TimeoutError, "emaki: deadline passed after #{@timeout}s; the run may still finish in your library"
+    end
+
+    private
+
+    def call(path, body)
+      raise AuthError, "set EMAKI_API_KEY or pass api_key; create a key at #{KEYS_URL}" if @key.empty?
+
+      @transport.call("#{@base}#{path}", body, @key)
+    end
+
+    def stringify(h)
+      h.each_with_object({}) { |(k, v), o| o[k.to_s] = v }
+    end
+
+    def http(url, body, key)
+      uri = URI(url)
+      req = Net::HTTP::Post.new(uri)
+      req["Content-Type"] = "application/json"
+      req["Authorization"] = "Bearer #{key}"
+      req["User-Agent"] = "emaki-ruby/#{VERSION}"
+      req.body = JSON.generate(body)
+      res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 60) { |h| h.request(req) }
+      parsed = begin
+        JSON.parse(res.body.to_s.empty? ? "{}" : res.body)
+      rescue JSON::ParserError
+        {}
+      end
+      [res.code.to_i, parsed]
+    rescue SocketError, SystemCallError, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError => e
+      raise Error, "emaki: #{e.message}"
+    end
+  end
+
+  # Generate a clip (Seedance 2.5 by default) and return its URL.
+  def self.generate_video(prompt, model: MODEL_VIDEO, api_key: nil, **params)
+    Client.new(api_key).generate(prompt, model: model, **params)
+  end
+
+  # Generate an image (the cheapest model by default) and return its URL.
+  def self.generate_image(prompt, model: MODEL_IMAGE, api_key: nil, **params)
+    Client.new(api_key, poll_every: 3).generate(prompt, model: model, **params)
+  end
+
+  # Credits left on the account.
+  def self.credits(api_key: nil)
+    Client.new(api_key).credits
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: emaki
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- emaki
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-10-16 00:00:00.000000000 Z
+dependencies: []
+description: 'Official SDK for emaki (emaki.ai), the Japanese-language AI video generator
+  for Seedance 2.5 and Seedance 2.0. A zero-dependency Ruby client: text-to-video
+  and image-to-video with Seedance 2.5, Seedance 2.0, MiniMax H3 and Veo 3.1, and
+  images with Nano Banana 2, Seedream 5 and GPT Image 2, on one API key.'
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/emaki.rb
+- lib/emaki/version.rb
+homepage: https://emaki.ai/?utm_source=rubygems&utm_medium=package
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://emaki.ai/?utm_source=rubygems&utm_medium=package
+  source_code_uri: https://github.com/hanshs474/emaki-rb
+  documentation_uri: https://emaki.ai/seedance-2-5
+  bug_tracker_uri: https://github.com/hanshs474/emaki-rb/issues
+  rubygems_mfa_required: 'false'
+post_install_message: 
+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.0.3.1
+signing_key: 
+specification_version: 4
+summary: Official SDK for emaki (emaki.ai), the Japanese-language AI video generator
+  for Seedance 2.5 and Seedance 2.0
+test_files: []