ドキュメント

認証

Kunavoの認証方式はOpenAIと同じです。Authorizationヘッダーに単一のBearerトークンを指定します。一般的なOpenAI連携と異なるのは、ベースURLだけです。

すべてのAPI呼び出しは https://api.kunavo.com/v1 に Authorization: Bearer sk-kn-XXX を付けて送信します。それだけです。

ベースURL

すべてのモデルとモダリティに対応する単一のエンドポイントです。

フィールド	値
ベースURL	`https://api.kunavo.com/v1`
リージョン	米国（アッシュバーン）をプライマリとし、マルチリージョンのエッジで前段を構成
TLS	TLS 1.2以降を必須とします。HTTPSのみ利用できます。

パスの構成はOpenAIの規約に準拠しています。

モダリティ	パス
チャット	`POST /v1/chat/completions`
モデル一覧の取得	`GET /v1/models`
画像生成	`POST /v1/images/generations`
画像編集 / i2i	`POST /v1/images/edits`
動画生成	`POST /v1/video/generations`
TTS	`POST /v1/audio/speech`
音楽	`POST /v1/audio/music`

APIキー

ダッシュボードの /app/keys からAPIキーを発行できます。各キーの特徴は次のとおりです。

sk-kn- で始まり、その後に30文字以上のランダムな文字列が続きます。
作成時に一度だけ表示されます。その後、Kunavoはハッシュのみを保存します。
ダッシュボードで識別しやすい名前を付けられます（例：prod-web）。
いつでも無効化できます。無効化後、キーはただちに401を返すようになります。
キーごとに月間利用額の上限とIP許可リストを設定できます。どちらも /app/keys から設定でき、すべての呼び出しに適用されます。

キーごとの利用額上限（任意）

キーごとに月間の利用額上限を米ドルで設定できます。そのキーの当暦月の確定済み利用額が上限を超えることになると、そのキーを使った呼び出しには 402 insufficient_quota が返され、月初に上限がリセットされるまで一切課金されません。他のキーには影響しません。これはアカウント全体ではなく、1つの認証情報に適用される上限です。

無人エージェントには、このような制限が必要です。ウォレット残高はすべてのキーで共有されるため、それだけでは1つの暴走したループによる全額消費を防げません。エージェント専用のキーを作成し、そのジョブに合わせた上限を設定すれば、最悪の場合の利用額をその数字以内に抑えられます。上限を $0 に設定すると、キーを無効化せずに一時停止できます。

キーごとのIP許可リスト（任意）

キーの利用元を特定のアドレスに制限することもできます。IPv4/IPv6アドレスまたはCIDRブロックを1行に1つずつ入力してください（203.0.113.7、198.51.100.0/24、2001:db8::/32）。それ以外からそのキーを使用した呼び出しは、403 permission_error で拒否されます。この制限は /v1/models を含むすべてのエンドポイントに適用されます。空欄にすると、任意のアドレスから利用できます。

検証するアドレスは、当社のエッジプロキシが確認したものであり、クライアントがヘッダーで申告できるものではありません。そのため、X-Forwarded-For を偽装して許可リストを回避することはできません。一方、許可リストを設定したキーは、呼び出し元が新しいホスト、NATゲートウェイ、またはネットワークに移動すると動作しなくなります。許可リストは、送信元IPが安定しているサーバーに設定し、ノートPCには設定しないでください。

リクエストヘッダー

最小限のリクエストには、次の2つのヘッダーが必要です。

Authorization: Bearer sk-kn-...
Content-Type: application/json

すべてのエンドポイントは、Authorization の代わりに、Anthropic SDKが送信する x-api-key ヘッダーからもキーを読み取ります。そのため、Anthropic API向けに構築されたクライアントは、カスタムヘッダーを設定せずに /v1/models を含むすべてのルートにアクセスできます。両方のヘッダーがリクエストに含まれる場合、読み取られるのは Authorization です。どちらのヘッダーでキーが送られても、キーの利用額上限とIP許可リストが適用されます。

任意ですが、アプリを識別する User-Agent の設定を推奨します。リクエスト元のデバッグに役立つよう、ユーザーエージェントは /app/usage ダッシュボードに記録されます。

OpenAI SDKを使用する

多くのチームは公式OpenAI SDKを使い続け、base_urlだけを変更しています。Python（v1.x以降）とNode（v4.x以降）のどちらでもこの方法が使えます。

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KUNAVO_API_KEY"],
    base_url="https://api.kunavo.com/v1",
)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KUNAVO_API_KEY,
  baseURL: "https://api.kunavo.com/v1",
});

OpenAI SDKでは、Nodeで baseURL、Pythonで base_url を使用します。どちらも同じエンドポイントを指定します。

キーのローテーション

APIキーは四半期ごと、または漏えいの可能性がある場合にローテーションするのがベストプラクティスです。Kunavoでは1つのアカウントに複数のキーを同時に保持できるため、キーを切り替える際も、旧キーを無効化する前に新しいキーを併用できます。

# 1. Create a new key in /app/keys, set its name to e.g. "prod-2026-Q2"
# 2. Deploy new key to your servers
# 3. Verify traffic is flowing on the new key (dashboard shows usage)
# 4. Revoke the old key from /app/keys → it 401s immediately

# In code, swap one env var:
export KUNAVO_API_KEY="sk-kn-new-..."

無効化されたキーは即座に401を返します。猶予期間はありません。旧キーを無効化する前に、新しいキーへのトラフィックが確立していることを確認してください。

セキュリティに関する注意

キーをクライアント側に公開しないでください。ブラウザーのコードやモバイルアプリのバンドルは公開されています。必ずサーバー経由でプロキシしてください。
キーの権限は必要最小限にしてください。プロジェクトごとに異なるキーを使えば、他のワークロードに影響を与えずにキーを無効化できます。また、それぞれに利用額上限とIP許可リストを設定できるため、キーが漏えいしても、費用と利用元の両方を制限できます。
ダッシュボードを確認してください。/app/usageページでは、キーごとに分類されたトラフィックを確認できます。予期しないアクティビティを見つけやすくなります。
漏えいが疑われる場合は報告してください。support@kunavo.comにメールでご連絡ください。キーの無効化とインシデントの確認を支援します。