rails-openrouter

client = OpenRouter::Client.new(api_key: ENV["OPENROUTER_API_KEY"])

client.chat.completions.stream(
  model: "anthropic/claude-sonnet-4.5",
  messages: [{ role: "user", content: "Write a haiku about sockets" }]
).each_text { |text| print(text) }

# Gemfile
gem "rails-openrouter"

client = OpenRouter::Client.new(
  api_key: ENV["OPENROUTER_API_KEY"], # defaults to ENV["OPENROUTER_API_KEY"]
  site_url: "https://example.com",    # sent as HTTP-Referer, for leaderboards
  app_name: "My App",                 # sent as X-Title
  default_model: "openai/gpt-4o-mini",
  timeout: 600,                       # read timeout, seconds
  open_timeout: 10,
  max_retries: 2
)

OpenRouter.configure do |config|
  config.api_key = ENV["OPENROUTER_API_KEY"]
  config.app_name = "My App"
  config.default_model = "openai/gpt-4o-mini"
end

OpenRouter.chat.completions.create(messages: [{ role: "user", content: "Hi" }])

completion = client.chat.completions.create(
  model: "openai/gpt-4o-mini",
  messages: [
    { role: "system", content: "You are terse." },
    { role: "user", content: "Why is the sky blue?" }
  ],
  temperature: 0.2,
  max_tokens: 200
)

completion.choices.first.message.content
completion.usage.total_tokens
completion.to_h # plain Hash with symbol keys

client.chat.completions.create(
  model: "anthropic/claude-sonnet-4.5",
  models: ["openai/gpt-4o", "google/gemini-2.5-pro"],  # fallbacks
  provider: { order: ["Anthropic"], allow_fallbacks: false },
  reasoning: { effort: "high" },
  transforms: ["middle-out"],
  plugins: [{ id: "web" }],
  usage: { include: true },
  messages: messages
)

stream = client.chat.completions.stream(model: model, messages: messages)

stream.each_text { |text| print(text) }        # only the text deltas
stream.each { |chunk| p chunk.choices.first }  # raw chunks
stream.each_reasoning { |text| print(text) }   # reasoning tokens

stream.final_completion  # shaped exactly like a non-streaming response
stream.final_message     # .content, .tool_calls, .reasoning
stream.text              # the full text of choice 0
stream.usage             # prompt/completion/total tokens, and cost

completion = client.chat.completions.create(model: model, messages: messages, stream: true) do |chunk|
  print(chunk.choices.first.delta.content)
end

stream.each do |chunk|
  break if enough?(chunk)
end
stream.close

stream = client.chat.completions.stream(messages: messages, tools: tools)
stream.each_text { |text| print(text) }

stream.final_message.tool_calls&.each do |call|
  args = JSON.parse(call.function.arguments)
  # dispatch call.function.name with args, append a role: "tool" message, loop
end

client.chat.completions.stream(
  model: "google/gemini-3-flash-preview",
  messages: [
    OpenRouter::Message.user("What changed between these?", attach: [
      "before.png",                          # local file, inlined as a data URL
      Pathname("after.png"),
      "https://example.com/spec.pdf",        # URL: OpenRouter fetches it
      { id: "or_file_abc" }                  # a file already uploaded
    ])
  ]
).each_text { |text| print(text) }

# text, not a file read:
{ role: "user", content: "please check ./report.pdf" }

# a file read, because you asked for one:
OpenRouter::Message.user("please check this", attach: ["./report.pdf"])

OpenRouter::Content.text("What is this?")
OpenRouter::Content.image("chart.png")                 # or a URL, IO, Pathname
OpenRouter::Content.file("report.pdf")
OpenRouter::Content.file(id: "or_file_abc")            # previously uploaded
OpenRouter::Content.audio("note.m4a")                  # base64 only, per the API
OpenRouter::Content.video("https://example.com/clip.mp4")
OpenRouter::Content.attach("whatever.ext")             # shape picked by MIME type

client.chat.completions.create(
  model: model,
  messages: [OpenRouter::Message.user("Summarize", attach: ["report.pdf"])],
  pdf_engine: "native"        # model reads the file itself, billed as input tokens
  # "mistral-ocr"             # scanned pages and images, $2 per 1k pages
  # "cloudflare-ai"           # PDF to markdown, free
)

messages << completion.choices.first.message.to_h   # includes annotations
messages << OpenRouter::Message.user("And the risks section?")

file = client.files.upload("report.pdf")            # path, Pathname, IO or Attachment
file.id                                             # => "or_file_..."

client.files.list
client.files.retrieve(file.id)
client.files.download(file.id, to: "copy.pdf")      # server-created files only
client.files.delete(file.id)

OpenRouter::Message.user("What is the total?", attach: [{ id: file.id }])

client.models.list(input_modalities: %w[text image])   # vision models
client.models.list(input_modalities: "file")           # models that read documents
client.models.list(output_modalities: "image")         # models that draw

completion = client.chat.completions.create(
  model: "google/gemini-3-flash-image",
  messages: [{ role: "user", content: "A cat on a bicycle" }],
  modalities: %w[image text]
)

completion.choices.first.message.images.each_with_index do |image, index|
  OpenRouter::Content.decode(image).save("cat-#{index}.png")
end

attachment = OpenRouter::Attachment.new("clip.mp4")
attachment.mime_type  # => "video/mp4"
attachment.kind       # => :video
attachment.size       # => 2_481_233
attachment.data_url   # => "data:video/mp4;base64,..."
attachment.save("copy.mp4")

client.models.list                                  # every routable model
client.models.list(supported_parameters: "tools")   # filtered
client.models.endpoints("openai/gpt-4o")            # providers, pricing, limits
client.credits.retrieve                             # purchased vs. used
client.key.retrieve                                 # limits for the current key
client.generations.retrieve(completion.id)          # cost accounting for one call
client.files.list                                   # uploaded files

client.get("some/new/endpoint", query: { foo: "bar" })
client.post("some/new/endpoint", body: { foo: "bar" })
client.stream("some/new/endpoint", body: { foo: "bar", stream: true })