AIHub2API for Ruby

aihub2api is a small, dependency-free Ruby client and command-line preflight checker for the AIHub OpenAI-compatible API. It can check the public health endpoint, list models with your own API key, and send Chat Completions or Responses requests. API keys are read from the environment and are never printed by the client.

AIHub is an independent third-party gateway. It is not affiliated with or endorsed by OpenAI. The service is intended only for users outside mainland China.

Install

gem install aihub2api

Preflight check

The health check does not need a key:

aihub2api check

To query the authenticated model list:

export AIHUB_API_KEY='your-key'
aihub2api models
aihub2api check --model gpt-5.6-sol

The AIHub operator reports availability of gpt-5.6-sol. Treat the output of the authenticated /v1/models endpoint as authoritative for your account at the time of use.

Ruby usage

require "aihub2api"

client = AIHub2API::Client.new(api_key: ENV.fetch("AIHUB_API_KEY"))

puts client.model_ids

result = client.chat_completions(
  model: "gpt-5.6-sol",
  messages: [{ role: "user", content: "Reply with exactly: connection ok" }],
)

puts result.dig("choices", 0, "message", "content")

You can test another OpenAI-compatible endpoint without changing code:

AIHUB_BASE_URL='https://your-gateway.example' aihub2api check

Billing terminology

On AIHub, 0.2x is an internal balance-conversion convention: CNY 0.20 covers USD 1.00 of official-list-price-equivalent usage, so CNY 2 covers USD 10 of that usage. It is not a foreign-exchange rate and not an OpenAI discount. Actual charges and model availability must be checked in the AIHub dashboard.

Security notes

  • Use environment variables or a secret manager for API keys.
  • Do not commit keys to a repository or pass them as command-line arguments.
  • The client requires HTTPS, except for explicit loopback testing.
  • Pin the gem version in production and review changes before upgrading.

The initial implementation was drafted with AI assistance and validated with the included automated tests. Bug reports should include Ruby version and a redacted response status, never an API key.