ドキュメント

無料で試す

登録不要で HAI のレイテンシと SDK 互換性を体験できます。下のボタンからトライアルキーを発行してください。

from openai import OpenAI

client = OpenAI(
    base_url="https://hai-api.hcloud.ltd/v1",
    api_key="hai_test_...",
)

resp = client.chat.completions.create(
    model="test",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

制約（透明性）

Claude Code / Codex はトライアル対象外です。コンテキスト要件が大きいため、本番モデル（kimi-k3 等）でご利用ください → コンソールへ。

curl / TypeScript

curl https://hai-api.hcloud.ltd/v1/chat/completions \
  -H "Authorization: Bearer hai_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "test",
    "messages": [{"role":"user","content":"こんにちは"}]
  }'

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://hai-api.hcloud.ltd/v1",
  apiKey: "hai_test_...",
});

const resp = await client.chat.completions.create({
  model: "test",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(resp.choices[0].message.content);

エンドポイント

https://hai-api.hcloud.ltd/v1

提供 API: /v1/chat/completions / /v1/responses / /v1/messages（Anthropic 互換） / /v1/models / /v1/embeddings（埋め込み） / /v1/videos（動画生成）

出力上限（max_tokens / max_completion_tokens / max_output_tokens）に 1 以上 3 未満を指定した場合は 3 として扱います （極端に小さい上限でも安定して応答を返すためです）。 自社 GPU で運用するモデル（qwen3.8-27b-uncensored / llm-jp-4-vl-9b）では、モデルの出力上限を超える値は出力上限として扱います。 指定を省略した場合に上限が付くことはありません。

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://hai-api.hcloud.ltd/v1",
    api_key="hai_...",
)

resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://hai-api.hcloud.ltd/v1",
  apiKey: "hai_...",
});

const resp = await client.chat.completions.create({
  model: "kimi-k2.6",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(resp.choices[0].message.content);

curl

curl https://hai-api.hcloud.ltd/v1/chat/completions \
  -H "Authorization: Bearer hai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [{"role":"user","content":"こんにちは"}]
  }'

Claude Code

Anthropic 互換の /v1/messages を提供しているため、環境変数の設定だけで Claude Code から HAI のモデルを利用できます。トライアル（model test）はコンテキスト上限が小さいため Claude Code での利用はおすすめしません。本番モデルと有料キーでご利用ください。

使うモデルに合わせて ~/.claude/settings.json を生成するなら クライアント設定ジェネレーター を使ってください。

export ANTHROPIC_BASE_URL=https://hai-api.hcloud.ltd
export ANTHROPIC_AUTH_TOKEN=hai_...
export ANTHROPIC_MODEL=kimi-k3
export ANTHROPIC_SMALL_FAST_MODEL=deepseek-v4-flash
claude

• ANTHROPIC_SMALL_FAST_MODEL は必須です。未設定の場合、Claude Code が haiku 系のモデル名でリクエストし 400（unknown model）エラーになります。 バックグラウンドタスク用のため、低価格の deepseek-v4-flash を推奨します（コストに応じて他のモデル ID に変更できます）。
• 認証は Authorization: Bearer（ANTHROPIC_AUTH_TOKEN）と x-api-key（ANTHROPIC_API_KEY）の両方に対応しています。
• /v1/messages/count_tokens は未提供です。コンテキスト残量の表示が不正確になりますが、動作には影響しません。

Codex CLI

OpenAI Responses API 互換の /v1/responses に対応しています。トライアルは対象外です（本番モデル + 有料キー）。~/.codex/config.toml に以下を追記してください。 モデルを切り替える場合の設定は クライアント設定ジェネレーター で生成できます。

model_provider = "hai"
model = "kimi-k3"

[model_providers.hai]
name = "HAI"
base_url = "https://hai-api.hcloud.ltd/v1"
env_key = "HAI_API_KEY"
wire_api = "responses"

export HAI_API_KEY=hai_...
codex

config.toml を書き換えずに試す場合は、-c オプションで同じ設定を渡せます。

codex exec --skip-git-repo-check \
  -c model_provider=hai \
  -c 'model_providers.hai.name=HAI' \
  -c 'model_providers.hai.base_url=https://hai-api.hcloud.ltd/v1' \
  -c 'model_providers.hai.env_key=HAI_API_KEY' \
  -c 'model_providers.hai.wire_api=responses' \
  -c model=kimi-k3 \
  "こんにちは"

• 起動時に /v1/models 関連の ERROR ログが表示されることがありますが、非致命的です。そのまま動作します。

思考（Reasoning）

提供モデルは思考（reasoning）に対応しており、思考の内容と使用トークン数が各 API のレスポンスに含まれます。OpenAI SDK・Claude Code・Codex CLI のいずれからも追加設定なしで利用できます。

• 思考量の指定（reasoning_effort / budget_tokens など）はそのままモデルへ渡されます。受け付ける値はモデルごとに違い、 対応しない値は 400 になります。モデルごとの一覧は モデル ID の表と クライアント設定 に載せています。
• "none" を受け付けないモデルは思考を止められません（思考が常時 ON のモデル）。reasoning_effort を送らない場合はモデル既定の思考量になります。
• 思考トークンは usage.completion_tokens_details.reasoning_tokens（Responses API では usage.output_tokens_details.reasoning_tokens）として報告され、出力トークンの一部として課金されます。
• 推論基盤のプレフィックスキャッシュから供給された入力トークンには、モデルごとに キャッシュ読取単価が適用されます（未設定のモデルは通常の入力単価）。 ヒットは保証されません。同一プロンプトでもヒットしないことがあり、 HAI 側でヒットを制御していません。
• 明細の cache_read_tokens は input_tokens の部分集合です。課金は (input_tokens − cache_read_tokens) × 入力単価 + cache_read_tokens × キャッシュ読取単価 + output_tokens × 出力単価です。単価未設定モデルでは cache_read_tokens が記録されても通常の入力単価で課金されます。
• /v1/chat/completions と /v1/responses の prompt_tokens / input_tokens はキャッシュ分を含み、/v1/messages の input_tokens は含みません（API 仕様の差）。

モデル ID

テキスト生成のモデル ID です。埋め込みのモデルは 埋め込み（/v1/embeddings）、動画生成のモデルは 動画生成（/v1/videos） に記載しています。

「出力上限」は 1 リクエストで生成できるトークン数の上限です。コンテキスト長 （入力 + 出力の合計）は料金に記載しています。reasoning_effort は実際にリクエストを通して受け付けを確認した値です。設定ファイルの形で欲しい場合は クライアント設定 から生成できます。

掲載してほしいモデルがあればモデルのリクエストから教えてください。ご意見箱扱いとなるため、こちらでは返信いたしません。

テキスト生成モデルの出力はテキストのみです。画像を受け付けるモデルには、 OpenAI 互換の content 配列で image_url（Responses API では input_image、Anthropic 互換では image ブロック）を渡せます。テキストのみのモデルに画像を送るとエラーを返します。

埋め込み（/v1/embeddings）

埋め込みは /v1/embeddings です。テキスト生成とは別サーフェスのため、これらのモデル ID は GET /v1/models には含まれません（GET /v1/embeddings/models で対応モデルと次元を確認できます）。トライアルキーは対象外です。

from openai import OpenAI

client = OpenAI(
    base_url="https://hai-api.hcloud.ltd/v1",
    api_key="hai_...",
)

resp = client.embeddings.create(
    model="qwen3-embedding-8b",
    input=["テキストをベクトルにする", "複数まとめて送れます"],
)
print(len(resp.data[0].embedding))  # 4096

curl https://hai-api.hcloud.ltd/v1/embeddings \
  -H "Authorization: Bearer hai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-embedding-8b",
    "input": "テキストをベクトルにする"
  }'

• input は文字列と文字列配列のどちらも受け付けます。配列で送ると data に入力と同じ順で返ります。
• 返るベクトルは既定で 4096 次元です。dimensions に 32〜4096 の整数を指定すると、その次元に切り詰めた（Matryoshka）ベクトルが返ります。 次元を下げるとベクトル DB のストレージと検索コストが下がります。異なる次元のベクトルは比較できないため、 1 つのインデックス内では同じ値を使ってください。
• encoding_format に base64 を指定できます（既定は float）。
• ストリーミングには対応していません（stream: true は 400 を返します）。
• 課金は入力トークンのみです。出力はベクトルのためトークンを持たず、 レスポンスの usage.completion_tokens は常に 0 です。 定額プランの対象外で、クレジットから消費します。

動画生成（/v1/videos）

動画生成は /v1/videos です。テキスト生成とは別サーフェスのため、これらのモデル ID は GET /v1/models には含まれません（GET /v1/videos/models で対応モデルと単価を確認できます）。トライアルキーは対象外です（本番モデル + 有料キー）。

生成は分単位の非同期ジョブです。POST /v1/videos が 202 でジョブ ID を返し、GET /v1/videos/{id} で完了を確認してから GET /v1/videos/{id}/content で mp4 を取得します。OpenAI Video API 互換の形なので、OpenAI SDK の videos.create / videos.retrieve / videos.download_content がそのまま使えます。

curl https://hai-api.hcloud.ltd/v1/videos \
  -H "Authorization: Bearer hai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "prompt": "A product spin on a clean white table, soft studio light",
    "seconds": 5,
    "aspect_ratio": "16:9"
  }'

# 完了確認（status が completed になるまで繰り返す）
curl https://hai-api.hcloud.ltd/v1/videos/<id> \
  -H "Authorization: Bearer hai_..."

# mp4 の取得
curl -L https://hai-api.hcloud.ltd/v1/videos/<id>/content \
  -H "Authorization: Bearer hai_..." \
  -o out.mp4

import time
from openai import OpenAI

client = OpenAI(
    base_url="https://hai-api.hcloud.ltd/v1",
    api_key="hai_...",
)

video = client.videos.create(
    model="minimax-h3",
    prompt="A product spin on a clean white table",
    seconds="5",
)
while video.status in ("pending", "in_progress"):
    time.sleep(10)
    video = client.videos.retrieve(video.id)

client.videos.download_content(video.id).write_to_file("out.mp4")

• 参照画像の枚数は frame_images / input_reference / input_references の合計で数えます。上の表の上限を超えると 400 です。
• seed は非対応です（指定すると 400）。解像度は 2K 固定で、size は受け付けません。
• 課金は秒単価と参照画像の枚数で決まります（トークン課金ではないため、利用履歴の入力 / 出力トークンは 0 です）。単価は料金をご覧ください。
• 投入時に見積り全額をクレジットから予約します。残高不足の場合は 402 で送信しません。完了時に実額で精算し、失敗・期限切れのジョブは課金せず予約を全額解放します。
• /content は完了前に呼ぶと 409 です。レスポンスは Content-Type: video/mp4 固定で、保持期限は GET /v1/videos/{id} の expires_at（UNIX 秒）で確認できます。期限が切れる前に取得・保存してください。

Account API（残高・利用状況の参照）

API キーに account:read 権限を付けると、残高やクレジットの有効期限、利用状況を API から参照できます。コンソールの「API キー」画面で、キーの作成時にチェックするか、既存のキーに後から付与してください。既定はオフです。

ベース URL は推論と同じ https://hai-api.hcloud.ltd です（/v1 は付きません）。認証は Authorization: Bearer のみで、x-api-key は使えません。

curl https://hai-api.hcloud.ltd/api/credits \
  -H "Authorization: Bearer $HAI_API_KEY"

curl 'https://hai-api.hcloud.ltd/api/usage?from=2026-08-01T00:00:00Z' \
  -H "Authorization: Bearer $HAI_API_KEY"

• すべて参照のみです。チャージ、キーの作成・権限変更・無効化はコンソール（ログイン）からのみ行えます。
• /api/usage の期間は from / to で指定します。いずれもタイムゾーン付きの RFC 3339（例 2026-08-01T00:00:00Z / 2026-08-01T09:00:00+09:00）で、from <= 利用日時 < to の半開区間です。省略時は全期間、未来の to はリクエスト時刻まで切り詰められます。
• 金額は 2 種類返ります。calculatedCostJpy はモデル単価から算出した額、debitedJpy は残高から実際に引かれた額です。どちらも円・小数 6 桁の文字列（例 "0.054600"）で、切り上げや最低額はありません。debitedJpy が "0.000000" になるのは、HAI Go の定額枠での利用分（calculatedCostJpy は参考額として記録されます）と、決済時点で有効なクレジットロットが無く実控除が無かった場合です。
• 残高が 0 でも参照できます。アカウントが停止中の場合は 403 です。
• レート制限は IP 単位が 300 回/分、キー単位は JSON が 60 回/分・CSV が 2 回/分です。制限はハンドラ実行前に適用されるため、HTTP 400 も 1 回として数えます。超過時は 429 と Retry-After を返します。
• ブラウザからの直接呼び出しは想定しておらず、CORS ヘッダーは付きません。サーバーや CLI から利用してください。

課金について

• トークン数は実測の usage に基づいて課金されます。
• キャッシュ読取単価は、推論基盤のプレフィックスキャッシュから供給された入力トークンに適用されます。ヒットは保証されず、同一プロンプトでも割引が出ないことがあります。
• サーバーエラーでリクエストが失敗した場合は課金されません。
• 残高からは 0.000001 円単位で計算どおりに控除します。通常は calculatedCostJpy と debitedJpy は一致します。HAI Go の定額枠での利用分は残高から控除されないため debitedJpy が 0 になります（calculatedCostJpy は参考額）。

HAI Go（定額プラン）

定額プラン HAI Go（月額 ¥1,980・税込）または HAI Go Plus（月額 ¥4,980・税込） に加入すると、対象モデルを利用枠まで定額でご利用いただけます。 API の使い方は変わりません（同じキー・同じエンドポイントで、 残高の代わりに定額枠が適用されます）。

• 対象モデル: qwen3.8-27b-uncensored・deepseek-v4.1-flash・gemma-4-31b-it・llm-jp-4-vl-9b・deepseek-v4-flash（2 プラン共通・今後拡大予定）。対象外のモデルは従来どおりクレジット消費です
• HAI Go Plus は HAI Go と同じ対象モデルのまま、利用枠・ 混雑時の同時実行枠を広げたプランです。切り替えはコンソールから即時に行えます （差額を日割りで請求し、その月ここまでの枠の消化はそのまま引き継がれます）
• クレジット残高がある間は残高から優先して消費されます。残高を 使い切ると自動的に定額枠に切り替わります
• 対象モデルのうち一部にはモデルごとに独立した月間利用枠があります。qwen3.8-27b-uncensored / llm-jp-4-vl-9b には月間利用枠の制限はありません。 短期枠（5 時間 / 週）は全対象モデルにあります。 枠は個人の通常利用に十分な水準で、上限の絶対値は公開していません （混雑状況に応じて調整する場合があります）。HAI Go Plus は HAI Go を基準に 次の倍率で枠が広がります。
  • qwen3.8-27b-uncensored: 月間利用枠の制限はなし、短期枠は 2 倍
  • deepseek-v4.1-flash: 月間枠は HAI Go の 2 倍、短期枠は 2 倍
  • gemma-4-31b-it: 月間枠は HAI Go の 2 倍、短期枠は 2 倍
  • llm-jp-4-vl-9b: 月間利用枠の制限はなし、短期枠は 2 倍
  • deepseek-v4-flash: 月間枠は HAI Go の 2 倍、短期枠は 2 倍
• あるモデルが枠に達しても、他の対象モデルは引き続き利用できます。 月間枠のあるモデルを使い切ると 402（insufficient_quota / billing_error）を返します。 他の対象モデルを利用するか、クレジットをチャージすると従量でご利用いただけます
• 短期枠に達すると 429（rate_limit_error）と Retry-After を返します。 時間をおいて再試行するか、他の対象モデルをご利用ください
• 月間枠のあるモデルの消化率はコンソールで確認できます（月間枠のみ・%表示）。 枠の消化は利用量に比例し、リクエストごとの利用量は利用明細（GET /api/usage）で確認できます
• stream: true なら最大 4 分、stream: false なら最大 1 分まで順番待ちします。待機上限を超えた 非ストリーミングは 429 と Retry-After を返します。ストリーミングは 200 のまま SSE の error イベントで 終わります。429 を受け取ったら Retry-After ヘッダーの秒数だけ待ってから再送してください。エージェント利用では stream: true とクライアント側タイムアウト 300 秒以上を推奨します
• 429 は複数あります。どれも HTTP 429 で type は rate_limit_error です。区別するなら message か Retry-After を見てください（短期枠・混雑）
• 混雑で順番待ちしきれなかった場合、message は Too many concurrent requests. Please retry.、Retry-After は即時拒否が 15 秒、待機上限到達が 30 秒です
• 公式 SDK（OpenAI / Anthropic）は 429 をまとめて自動リトライし、Retry-After を尊重します
• 定額枠からクレジットへの自動フォールバックは行いません（意図しない 課金を防ぐため）
• お支払いに失敗した場合、定額枠は一時停止します。お支払い方法を 更新すると自動で再開されます

よくある質問

推論の実施場所・ZDR・個人情報保護法上の整理についてはよくある質問とセキュリティをご覧ください。