qzira AI API Gateway
テクニカルリファレンス

複数のAIモデルを「たった1つのキー」で管理・統合する

qzira は、複数のAI APIプロバイダー（OpenAI・Anthropic・Google AI・DeepSeek）を 1つのエンドポイント で統合管理できるAI APIゲートウェイです。

BYOK（Bring Your Own Key）方式 — お持ちのAPIキーをそのまま使えます。qziraがリクエストのプロキシ、使用量の可視化、フェイルオーバー、レート制限を自動処理します。

qzira を使うメリット

• コスト可視化: ダッシュボードでリクエスト数・トークン消費量をリアルタイム確認
• フェイルオーバー: プロバイダー障害時に自動で別プロバイダーに切替
• レート制限の自動処理: 429エラーのリトライをqziraが代行
• APIキー管理の統一: 複数プロバイダーのキーをqzira側で一元管理し、アプリには gw_ キー1つだけ
• 予算アラート・自動停止: AIエージェントの暴走によるコスト超過を防止
• 使用量エクスポート: CSV形式でログをダウンロードし、社内報告や経費精算に活用NEW

アーキテクチャ概要

qziraはアプリケーションとAIプロバイダーの間に位置するプロキシ（中継サーバー）です。APIキーは gw_ の1本だけで、すべてのプロバイダーにアクセスできます。

1. アカウント作成

1ダッシュボードにアクセス

https://app.qzira.com にアクセスします。

2Googleアカウントでログイン

「Googleでログイン」ボタンをクリックし、お使いのGoogleアカウントで認証します。

2. APIキー発行

ログイン後、サイドバーの「APIキー」をクリックします。

1新しいAPIキーを作成

「新しいAPIキーを作成」ボタンをクリックし、キーの名前を入力します（例: my-app-key、cursor-dev など）。

2APIキーをコピー

作成直後に表示される gw_xxxxxxxx 形式のキーを 必ずコピーして安全な場所に保存 してください。このキーは一度しか表示されません。

3. プロバイダーAPIキー登録（BYOK）

サイドバーの「プロバイダー」をクリックします。

対応プロバイダー

登録手順

1. 使用するプロバイダーの「APIキーを登録」をクリック
2. お持ちのAPIキーを入力
3. 「登録」をクリック — qzira側でキーの有効性を自動検証します

4. プロバイダー有効化

APIキーを登録しただけでは、まだそのプロバイダー経由でのリクエストはできません。有効化 が必要です。

有効化の手順

プロバイダー画面で、使用したいプロバイダーの「有効化」ボタンをクリックします。

プラン別の同時有効化数

5. コード移行

qziraはOpenAI互換のAPIエンドポイントを提供します。既存コードの Base URL と APIキー を変更するだけで移行完了です。

基本情報

移行例: Python（OpenAI SDK）

Before（直接呼び出し）:

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxx"  # OpenAI APIキー
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

After（qzira経由）:

from openai import OpenAI

client = OpenAI(
    api_key="gw_xxxxxxxx",                  # qzira APIキー
    base_url="https://api.qzira.com/v1"     # qzira エンドポイント
)

response = client.chat.completions.create(
    model="gpt-4o",  # モデル名はそのまま
    messages=[{"role": "user", "content": "Hello"}]
)

移行例: Python（Anthropic SDK → OpenAI互換形式）

Before（Anthropic SDK 直接呼び出し）:

import anthropic

client = anthropic.Anthropic(api_key="sk-ant-xxxxxxxx")

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="You are a helpful assistant.",
    messages=[{"role": "user", "content": "Hello"}]
)

After（qzira経由 — OpenAI互換形式）:

from openai import OpenAI

client = OpenAI(
    api_key="gw_xxxxxxxx",
    base_url="https://api.qzira.com/v1"
)

response = client.chat.completions.create(
    model="claude-sonnet-4-20250514",  # Claudeモデルもそのまま指定
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello"}
    ]
)

移行例: Python（Google Gemini → OpenAI互換形式）

from openai import OpenAI

client = OpenAI(
    api_key="gw_xxxxxxxx",
    base_url="https://api.qzira.com/v1"
)

response = client.chat.completions.create(
    model="gemini-2.0-flash",  # Geminiモデルもそのまま指定
    messages=[{"role": "user", "content": "Hello"}]
)

移行例: JavaScript / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "gw_xxxxxxxx",
  baseURL: "https://api.qzira.com/v1",
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-4-20250514",
  messages: [{ role: "user", content: "Hello" }],
});

環境変数での管理（推奨）

.env ファイル:

QZIRA_API_KEY=gw_xxxxxxxx
QZIRA_BASE_URL=https://api.qzira.com/v1

Python:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("QZIRA_API_KEY"),
    base_url=os.getenv("QZIRA_BASE_URL")
)

ストリーミング対応

qziraはSSE（Server-Sent Events）形式のストリーミングに全プロバイダーで対応しています。

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

移行例: Anthropic SDK（ネイティブ形式） NEW

Anthropic SDKを使用している場合、/v1/messages エンドポイントでネイティブ形式のまま利用できます。

Before（直接呼び出し）:

import anthropic

client = anthropic.Anthropic(
    api_key="sk-ant-xxxxxxxx"  # Anthropic APIキー
)

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

After（qzira経由 — 2行変更するだけ）:

import anthropic

client = anthropic.Anthropic(
    api_key="gw_xxxxxxxx",       # qzira APIキー
    base_url="https://api.qzira.com"  # ⚠️ /v1 なし
)

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

移行例: TypeScript / JavaScript（Anthropic SDK）

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: "gw_xxxxxxxx",        // qzira APIキー
  baseURL: "https://api.qzira.com"  // ⚠️ /v1 なし
});

const message = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }]
});

対応モデル一覧（主要なもの）

6. curlでのテスト

qziraの動作をすぐに確認したい場合は、curlコマンドで試せます。

OpenAIモデル

curl -X POST https://api.qzira.com/v1/chat/completions \
  -H "Authorization: Bearer gw_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Anthropicモデル

curl -X POST https://api.qzira.com/v1/chat/completions \
  -H "Authorization: Bearer gw_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-haiku-20241022",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Google AIモデル

curl -X POST https://api.qzira.com/v1/chat/completions \
  -H "Authorization: Bearer gw_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.0-flash",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Anthropicネイティブ形式（/v1/messages） NEW

curl -X POST https://api.qzira.com/v1/messages   -H "x-api-key: gw_xxxxxxxx"   -H "Content-Type: application/json"   -H "anthropic-version: 2023-06-01"   -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

/v1/messages ストリーミング

curl -N -X POST https://api.qzira.com/v1/messages   -H "x-api-key: gw_xxxxxxxx"   -H "Content-Type: application/json"   -H "anthropic-version: 2023-06-01"   -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Count from 1 to 5"}],
    "stream": true
  }'

ストリーミングテスト

curl -N -X POST https://api.qzira.com/v1/chat/completions \
  -H "Authorization: Bearer gw_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Count from 1 to 5"}],
    "stream": true
  }'

PowerShell（Windows）

$headers = @{
  "Authorization" = "Bearer gw_xxxxxxxx"
  "Content-Type"  = "application/json"
}
$body = '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello"}]}'

Invoke-RestMethod -Uri "https://api.qzira.com/v1/chat/completions" `
  -Method POST -Headers $headers -Body $body

正常なレスポンス例

{
  "id": "chatcmpl-xxxxx",
  "object": "chat.completion",
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 9,
    "total_tokens": 17
  },
  "provider": "openai"
}

Tool Calling（Function Calling）対応 NEW

qziraは全3プロバイダーでTool Callingに対応しています。OpenAI互換の tools パラメータをそのまま送信するだけで、各プロバイダーに適切な形式で中継されます。

プロバイダー別 Tool Calling 対応状況

Tool Calling テスト（curl）

以下のリクエストで、天気取得ツールを使ったTool Callingをテストできます。

OpenAIモデル

curl -X POST https://api.qzira.com/v1/chat/completions \
  -H "Authorization: Bearer gw_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "What is the weather in Tokyo?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get current weather for a location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "City and country, e.g. Tokyo, Japan"
              }
            },
            "required": ["location"]
          }
        }
      }
    ]
  }'

Geminiモデル（自動変換）

# OpenAIと同じtools形式でOK — qziraが自動変換
curl -X POST https://api.qzira.com/v1/chat/completions \
  -H "Authorization: Bearer gw_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.0-flash",
    "messages": [
      {"role": "user", "content": "What is the weather in Osaka?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get current weather for a location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "City and country, e.g. Osaka, Japan"
              }
            },
            "required": ["location"]
          }
        }
      }
    ]
  }'

Tool Calling レスポンス例

モデルがツールの呼び出しを判断した場合、以下のようなレスポンスが返されます。

{
  "id": "chatcmpl-xxxxx",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_xxxxx",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"Tokyo, Japan\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 53,
    "completion_tokens": 6,
    "total_tokens": 59
  },
  "provider": "openai"
}

tool_choice オプション

ストリーミング時の Tool Calling

ストリーミング（"stream": true）でも Tool Calling は正常に動作します。ツール呼び出し時のチャンク構造:

# チャンク1: role
data: {"choices":[{"delta":{"role":"assistant"},...}]}

# チャンク2: tool_calls（関数名＋引数）
data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"call_xxx","type":"function","function":{"name":"get_weather","arguments":"{...}"}}]},...}]}

# チャンク3: 完了
data: {"choices":[{"delta":{},"finish_reason":"tool_calls",...}]}

# チャンク4: 使用量
data: {"usage":{"prompt_tokens":24,"completion_tokens":6}}

data: [DONE]

7. Cursor / AIエージェント統合

Cursor 検証済み

Cursorの設定で、OpenAI互換のAPIプロバイダーとしてqziraを追加できます。OpenAI / Anthropic / Google の全モデルを1つのAPIキーで管理できます。

前提条件

• Cursor Pro以上のサブスクリプション（Cursor料金ページ）
• qziraアカウント（Freeプランから利用可能）
• qziraダッシュボードで使用するプロバイダーが有効化済みであること（セクション5参照）

Step 1: qzira側の準備

1. app.qzira.com にログイン
2. サイドバーの「プロバイダー」で、使用したいプロバイダーを有効化:
   • OpenAI: GPT-4o, GPT-4o-mini 等を使う場合
   • Anthropic: Claude Sonnet, Claude Haiku 等を使う場合
   • Google AI: Gemini 2.0 Flash, Gemini 2.5 Pro 等を使う場合
   • DeepSeek: DeepSeek V3 (deepseek-chat), DeepSeek R1 (deepseek-reasoner) を使う場合
3. サイドバーの「APIキー」で、Cursor用のAPIキーを作成（例: cursor-dev）
4. 表示された gw_xxxxxxxx 形式のキーをコピー（⚠️ 一度しか表示されません）

Step 2: Cursorの設定

1. Cursorを開き、Settings → Models を開く
2. OpenAI API Key にqziraのAPIキーを入力:

   gw_xxxxxxxx

3. Override OpenAI Base URL に以下を入力:

   https://api.qzira.com/v1

4. 使用したいモデルを手動で追加（「+ Add model」ボタン）:
   • gpt-4o-mini（OpenAI）
   • gpt-4o（OpenAI）
   • claude-sonnet-4-20250514（Anthropic）
   • gemini-2.0-flash（Google）
   • gemini-2.5-pro（Google）
5. 追加したモデルのトグルをONにして有効化

動作確認ポイント

• モデル選択: Cursorのチャットやエディタで、手動追加したモデル（例: gemini-2.0-flash）を選択
• テスト送信: 簡単なプロンプト（「Hello」など）を送信し、応答が返ることを確認
• ダッシュボード確認: app.qzira.com → 使用量ログにリクエストが記録されていることを確認
• プロバイダー確認: ログの provider 列に正しいプロバイダー名（openai / anthropic / google）が表示されること

トラブルシューティング

Claude Code NEW

Claude Codeは環境変数を設定するだけでqzira経由に切り替わります。すべてのリクエストがダッシュボードに記録され、予算管理・自動停止が適用されます。

Linux / macOS

# 環境変数を設定
export ANTHROPIC_BASE_URL="https://api.qzira.com"
export ANTHROPIC_API_KEY="gw_xxxxxxxx"

# Claude Code 起動
claude

PowerShell（Windows）

# 環境変数を設定
$env:ANTHROPIC_BASE_URL = "https://api.qzira.com"
$env:ANTHROPIC_API_KEY = "gw_xxxxxxxx"

# Claude Code 起動
claude

永続化（~/.bashrc や ~/.zshrc に追記）

# ~/.bashrc または ~/.zshrc に追記
export ANTHROPIC_BASE_URL="https://api.qzira.com"
export ANTHROPIC_API_KEY="gw_xxxxxxxx"

動作確認ポイント

• 初回起動時: Anthropic OAuthの認証画面が表示されます（Anthropic Console → 組織を選択）。これはClaude Code自体の認証であり、qziraとは無関係です。
• Auth conflict 警告: 「Using ANTHROPIC_API_KEY instead of Anthropic Console key」と表示されれば、qziraキーが優先使用されています ✅
• モデル自動使い分け: Claude CodeはHaiku（軽量タスク）とSonnet（応答生成）を自動的に使い分けます。すべてのリクエストがダッシュボードに記録されます。
• ダッシュボード確認: app.qzira.com → 使用量ログで、provider: anthropic のリクエストが記録されていることを確認してください。

Cline（VS Code拡張）

Clineの設定画面で「API Provider」を「OpenAI Compatible」に変更し、以下を入力します:

• Base URL: https://api.qzira.com/v1
• API Key: gw_xxxxxxxx
• Model: 使用したいモデル名（例: claude-sonnet-4-20250514）

Windsurf

⚠️ 現在、Windsurfはqzira経由での利用に対応していません。

WindsurfのBYOK（Bring Your Own Key）機能はClaude 4 Sonnet / Opusのみ対応しており、APIキーはWindsurf管理画面（windsurf.com/subscription/provider-api-keys）で設定します。カスタムBase URLやOpenAI Compatibleプロバイダーの設定項目が存在しないため、qziraのようなAPIゲートウェイ経由でのルーティングはできません。

出典: Windsurf Docs — AI Models（2026年2月確認）

Roo Code（VS Code拡張）

Roo CodeではOpenAI CompatibleモードとAnthropicモードの両方で動作確認済みです（v3.47.3）。

方法A: OpenAI Compatibleモード（推奨）

• API Provider: OpenAI Compatible
• Base URL: https://api.qzira.com/v1
• API Key: gw_xxxxxxxx
• Model: gpt-4o-mini（または gpt-4o）

方法B: Anthropicモード

• API Provider: Anthropic
• ☑ Use custom base URL にチェック
• Base URL: https://api.qzira.com（⚠️ /v1 なし）
• API Key: gw_xxxxxxxx
• Model: claude-sonnet-4-20250514

その他のAIエージェント

OpenAI互換のBase URLとAPIキーを設定できるツールであれば、同様の方法で統合可能です。

ツール × プロバイダー 対応マトリクス

各AIコーディングツールのqzira経由での動作検証状況です（2026年2月時点）。

8. ダッシュボードで使用量を確認

https://app.qzira.com/dashboard にログインすると、以下の情報をリアルタイムで確認できます。

ダッシュボード概要

• 今月のリクエスト数: 月間の合計リクエスト数（プラン上限との比較）
• 使用率: プラン上限に対する使用割合
• 入力トークン / 出力トークン: 合計トークン消費量
• 日別リクエスト数グラフ: 過去のリクエスト推移を視覚化

最近のリクエスト

各リクエストの詳細を確認できます:

使用量エクスポート（CSV）NEW

リクエストログをCSV形式でダウンロードできます。経費精算や社内レポートに活用できます。

ダッシュボードの「リクエストログ」セクションにある 「CSVエクスポート」 ボタンをクリックすると、表示中のログデータがCSVファイルとしてダウンロードされます。

CSVに含まれる項目

ログ保持期間NEW

リクエストログはプランに応じた期間で自動的に保持されます。保持期間を過ぎたログは毎日自動削除されます。

9. 予算アラート・自動停止

サイドバーの「予算設定」から、コスト管理の設定ができます（Starter以上）。

予算管理モード

qzira では、リクエスト数ベースとコスト（USD）ベースの2つのモードで予算管理ができます。ダッシュボードの予算設定ページで切り替えられます。

設定項目

為替レート表示（USD / JPY）NEW

コストモードでは、USD建ての予算設定に加えて日本円（JPY）換算表示に対応しています。

コスト推定について

コストモードでの推定コストは、各リクエストのトークン使用量と各モデルの公開料金に基づいて算出されます。以下の点にご注意ください。

• 推定コストは概算であり、プロバイダーの実際の請求額と一致しない場合があります
• プロバイダーが料金を変更した場合、反映にタイムラグが生じることがあります
• 一部のモデルや特殊なリクエスト（画像入力等）では、コスト推定の精度が低下する場合があります

10. プランアップグレード

サイドバーの「プラン・請求」からプラン変更が可能です。

プラン比較

プラン別の主要機能

11. APIキーローテーションNEW

セキュリティのベストプラクティスとして、APIキーの定期的なローテーション（再発行）を推奨します。qziraではダッシュボードからワンクリックでローテーションが可能です。

ローテーションとは

ローテーションを実行すると、既存のAPIキーが即座に無効化され、新しい gw_ キーが発行されます。キーのID（内部識別子）と名前はそのまま維持されるため、ダッシュボード上の使用量履歴や設定は引き継がれます。

ローテーション手順

1. サイドバーの「APIキー」をクリック
2. ローテーションしたいキーの「ローテーション」ボタン（🔄アイコン）をクリック
3. 確認ダイアログで「ローテーション実行」を選択
4. 新しいキーが表示されるので、必ずコピーして安全な場所に保存

ローテーションが推奨されるタイミング

• APIキーが意図せず公開された可能性がある場合（ログ出力、Git履歴など）
• チームメンバーの退職・異動時
• 定期的なセキュリティ対策として（30〜90日ごとを推奨）
• 不審なリクエストがダッシュボードで確認された場合

ローテーション後の更新例

# .env ファイルを更新
QZIRA_API_KEY=gw_yyyyyyyy    # ← 新しいキーに置き換え
QZIRA_BASE_URL=https://api.qzira.com/v1

アプリケーションを再起動（またはデプロイ）すれば、新しいキーが自動的に使用されます。

12. レスポンスキャッシュ

同一リクエストに対するAIプロバイダーの応答をキャッシュし、2回目以降の応答を高速化・トークン節約できます（Pro以上）。

メリット

• コスト削減: 同一リクエストでプロバイダーAPIコールをスキップし、トークン消費ゼロ
• レスポンス高速化: KVキャッシュから即座に返却（数百ms → 数十ms）
• プロバイダー障害の緩和: キャッシュ期間中はプロバイダー障害の影響を受けない
• 設定不要: トグルONにするだけで即座に有効化。コード変更不要

デメリット・注意点

• ストリーミングリクエストは対象外
• 完全一致のみ（表現の揺れにはセマンティックキャッシュを併用推奨）
• TTL期間中は古い回答が返る可能性がある
• PII（個人情報）を含むリクエストもキャッシュされるリスクがある

向き・不向き

対応プランとTTL（キャッシュ保持期間）

有効化手順

1. サイドバーの「キャッシュ」をクリック
2. 「キャッシュを有効にする」トグルをONにする
3. 必要に応じてカスタムTTLやTemperature制限を設定

設定項目

キャッシュの仕組み

リクエストの以下の要素をSHA-256ハッシュ化し、同一キーのリクエストを検出します:

• ユーザーID
• モデル名
• メッセージ内容
• temperature / top_p / max_tokens

キャッシュヒット時はプロバイダーへのリクエストをスキップし、保存済みの応答を即座に返却します。これによりトークン消費量が節約されます。

レスポンスヘッダー

キャッシュが有効な場合、レスポンスに以下のヘッダーが付加されます:

キャッシュ対象外のリクエスト

• ストリーミングリクエスト（"stream": true）: SSE形式はキャッシュに不向きなため対象外
• Temperature制限超過: 設定したTemperature制限を超えるリクエスト
• エラーレスポンス: プロバイダーからのエラー応答はキャッシュされません

キャッシュ統計の見方

キャッシュ設定ページの下部に、キャッシュの利用状況を示す統計が表示されます。

全期間統計

今月の統計

当月分のヒット数・節約トークン数が表示されます。月初にリセットされます。

最近のキャッシュヒット

直近のキャッシュヒットが一覧表示されます。各エントリには以下の情報が含まれます:

• プロバイダー名・モデル名
• 節約された入力/出力トークン数
• ヒット回数
• 最終ヒット日時

13. APIキー別予算設定

APIキーごとに個別の予算上限を設定し、特定のアプリケーションやエージェントのリクエスト数を制御できます（Business以上）。

対応プラン

設定手順

1. サイドバーの「APIキー」をクリック
2. 予算設定したいキーの ウォレットアイコン をクリック
3. 予算設定モーダルで以下を設定:
   • 月間リクエスト上限: 月間の最大リクエスト数
   • 日次リクエスト上限: 1日の最大リクエスト数
   • 自動停止: 上限到達時にリクエストを自動ブロック
4. 「保存」をクリック

設定項目

動作の仕組み

リクエスト受信時に以下の順序でチェックされます:

1. ユーザー単位の予算チェック（セクション9の設定）
2. APIキー単位の予算チェック（本セクションの設定）
3. 両方を通過した場合のみ、プロバイダーにリクエストを転送

上限到達時のレスポンス:

{
  "error": {
    "message": "API key budget exceeded",
    "type": "budget_exceeded",
    "code": 403
  }
}

通知

• 閾値通知: 50% / 80% 到達時にメール通知（5分おきのCronで判定）
• 上限到達通知: 100% 到達時に即座にメール通知

通知メールにはAPIキー名が記載されるため、どのキーが上限に達したか一目で判別できます。

現在の使用量の確認

予算設定モーダルには、日次・月次のプログレスバーが表示され、現在の使用量をリアルタイムで確認できます。

ユースケース例

• エージェント別制御: Cursor用キーに日次100件、Claude Code用キーに日次200件など、エージェントごとに上限を設定
• プロジェクト別管理: プロジェクトAのキーとプロジェクトBのキーで個別に予算管理
• 夜間実行の安全策: 自律実行するエージェントのキーに日次上限 + 自動停止を設定し、暴走を防止

14. アクセス制御（Per-Key Access Control）

APIキーごとに、使用可能なプロバイダーとモデルをホワイトリスト方式で制限できます。チーム内のエージェントごとに「何を使えるか」を細かく制御することで、意図しないプロバイダー利用や高額モデルの誤使用を防ぎます。

対象プラン

設定方法

1. ダッシュボード → APIキー 画面を開きます
2. 対象キーの 🔐 アクセス制限 ボタンをクリックします（Pro プラン以上で表示）
3. プロバイダー制限: 「全プロバイダー許可」または特定のプロバイダーのみを選択します
   • 選択肢: openai / anthropic / google
4. モデル制限: 「全モデル許可」または特定のモデルのみを入力します
   • 例: gpt-4o, gpt-4o-mini, claude-sonnet-4-20250514
5. 保存 をクリックして設定を反映します

チェック優先順位

APIリクエストが送信されると、以下の順序でアクセス制御チェックが行われます。

リクエスト受信
  │
  ├─ 1. プロバイダー制限チェック（先に評価）
  │     allowed_providers が設定されている場合
  │     → 対象プロバイダーがリストにない → 403 provider_not_allowed
  │
  ├─ 2. モデル制限チェック（プロバイダー通過後）
  │     allowed_models が設定されている場合
  │     → 対象モデルがリストにない → 403 model_not_allowed
  │
  └─ 3. 両方通過 → 通常のプロキシ処理へ

エラーレスポンス

アクセス制御に違反したリクエストは、以下の形式でエラーが返されます。

レスポンス例:

// プロバイダー制限エラー
{
  "error": {
    "message": "Provider 'google' is not allowed for this API key",
    "code": "provider_not_allowed"
  }
}

// モデル制限エラー
{
  "error": {
    "message": "Model 'o1-mini' is not allowed for this API key",
    "code": "model_not_allowed"
  }
}

ユースケース

デフォルト動作

• 制限未設定（デフォルト）: すべてのプロバイダー・モデルが利用可能（従来と同じ動作）
• プロバイダーのみ制限: 指定プロバイダー配下の全モデルが利用可能
• モデルのみ制限: 指定モデルであれば、どのプロバイダーでも利用可能
• 両方制限: プロバイダーとモデルの両方を満たすリクエストのみ通過

15. セマンティックキャッシュ

セマンティックキャッシュは、AIベクトル検索を使用して意味的に類似したリクエストを検出し、キャッシュされたレスポンスを再利用する機能です。レスポンスキャッシュ（セクション12）が完全一致のみに対応するのに対し、セマンティックキャッシュは表現が異なっていても同じ意図のリクエストをヒットさせることができます。

メリット

• 表現の揺れに対応: 「TypeScriptのメリットは？」と「なぜTypeScriptを使うべき？」を同一意図として認識
• 大幅なコスト削減: 完全一致では拾えないリクエストも再利用し、トークン消費を削減
• 二段構えの最適化: セマンティックヒット時にExact Cache（レスポンスキャッシュ）にも自動保存
• 安全設計: PII検出・短文・マルチターンのリクエストは自動的に除外

デメリット・注意点

• 誤ヒットの可能性（類似度閾値を0.95以上に設定することで軽減可能）
• Embeddingコストが発生（月200Kクエリで約$0.30と低コスト）
• 非ストリーミング・シングルターンのリクエストのみ対応
• ベクトルストレージに上限あり（Business: 10,000件 / Scale: 50,000件）
• eventual consistency（新規キャッシュが検索可能になるまで数分かかる場合あり）

向き・不向き

レスポンスキャッシュとの比較

動作フロー

セマンティックキャッシュは、レスポンスキャッシュ（完全一致）の後に評価されます。完全一致でヒットした場合、セマンティックキャッシュの処理は実行されません。

リクエスト受信
  ↓
認証 + プラン確認（Business以上？）+ Feature Toggle ON？
  │ NO → 通常フロー（セマンティックキャッシュをスキップ）
  ↓ YES
ストリーミング？ → YES → スキップ（X-Cache-Skip-Reason: streaming）
  ↓ NO
① Exact Cache Lookup（SHA-256 完全一致、KV get 1回）
  ├─ EXACT_HIT → 即座に返却（Embedding不要、最速）
  └─ MISS ↓
② 除外チェック（PII / 短文 / マルチターン）
  ├─ 除外 → 通常フロー（X-Cache-Skip-Reason で理由表示）
  └─ OK ↓
③ Embedding 生成（@cf/baai/bge-small-en-v1.5、384次元）
  ↓
④ Vectorize 検索（user_scope + meta_group フィルタ）
  ├─ スコア ≥ 閾値 → KV からレスポンス取得
  │   ├─ KV 成功 → SEMANTIC_HIT（+ Exact Cache にも保存）
  │   └─ KV 失敗 → MISS 扱い（X-Cache-Skip-Reason: kv_miss）
  └─ スコア < 閾値 → MISS
       ↓
⑤ プロバイダーにリクエスト送信
  ↓
⑥ レスポンス保存（Vectorize + KV + Exact Cache）

対応プランとストレージ上限

各プランでのベクトルストレージの上限と保持期間は以下の通りです。

自動クリーンアップ（CRON）

TTL を超過した古いベクトルは、日次の自動クリーンアップにより削除されます。

• 実行スケジュール: 毎日 UTC 15:00（JST 00:00）
• 処理内容: ユーザーごとにTTL切れのベクトルを検出・削除
• 削除上限: 1ユーザーあたり最大500件/日（5イテレーション × 100件）
• カウント同期: 削除されたベクトル数はD1のカウンタから自動的にデクリメントされます

手動で全ベクトルを削除したい場合は、ダッシュボードの「セマンティック」ページにある「全削除」ボタンを使用してください。

ダッシュボードでの設定

サイドバーの「セマンティック」をクリックして、セマンティックキャッシュの設定画面を開きます。

ベクトルストレージ

画面上部にベクトルストレージの使用状況がプログレスバーで表示されます。現在の使用量、上限値、使用率が一目で確認できます。TTLと自動クリーンアップの情報も併記されています。

キャッシュ設定

1. セマンティックキャッシュ ON/OFF: トグルスイッチで有効/無効を切り替えます
2. 類似度しきい値: スライダーで閾値を調整します（推奨: 0.92）
   • 値が高いほど → 精度重視（ヒット率は下がるが誤ヒットが少ない）
   • 値が低いほど → ヒット率重視（より多くのリクエストがヒットするが誤ヒットのリスクが上がる）
3. 「保存」をクリックして設定を反映します

キャッシュ統計

セマンティックキャッシュを有効にすると、画面下部にキャッシュの利用統計が表示されます。総ヒット数、節約トークン数、今月のヒット数、ユニークプロンプト数、および最近のセマンティックヒットの詳細が確認できます。

類似度閾値の設定ガイド

自動除外条件

以下の条件に該当するリクエストは、セマンティックキャッシュの対象外となります。

レスポンスヘッダー

セマンティックキャッシュに関連するレスポンスヘッダーは以下の通りです。

マッチング条件

セマンティックキャッシュがヒットするには、以下のすべての条件を満たす必要があります。

• 同一ユーザーのリクエストであること
• 同一の meta_group（モデル名 + system prompt + temperature の組み合わせ）であること
• ユーザーメッセージのコサイン類似度が設定閾値以上であること
• ベクトルのTTLが有効期間内であること

つまり、同じモデル・同じシステムプロンプト・同じ温度設定で、意味的に類似した質問をした場合にのみヒットします。異なるモデルや異なるシステムプロンプトのキャッシュが誤って返されることはありません。

保存されないレスポンス

以下のレスポンスはセマンティックキャッシュに保存されません。

• HTTP 4xx / 5xx エラーレスポンス
• finish_reason が "length"（出力が途中で切れたレスポンス）
• レスポンス本文が80文字未満の短いレスポンス

15. Agent Trace（エージェント・トレース）NEW

Agent Traceは、AIエージェントがqzira経由でリクエストを処理する際の内部処理ステップを可視化するデバッグ・監視機能です。Chrome DevToolsのネットワークパネルに似たWaterfallビューで、どのステップにどれだけ時間がかかったかを確認できます。

対象プラン

表示されるトレースステップ

ダッシュボードでの確認方法

1. ダッシュボード左メニュー「エージェント・トレース」をクリック
2. リクエスト一覧から確認したいトレースを選択
3. Waterfallバーをクリックして詳細ステップを展開
4. 各ステップの開始時刻・処理時間（ms）・結果（hit/miss等）を確認

外部トレースIDの付与

Claude CodeやCursorなど外部ツールからのリクエストに独自のトレースIDを付与することで、アプリケーション側のログと紐付けが可能です。

# リクエストヘッダーにトレースIDを付与
curl https://api.qzira.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_QZIRA_KEY" \
  -H "X-Trace-Id: my-agent-session-20260226-001" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

外部IDが付与されたトレースには、ダッシュボード上で [EXT] バッジが表示されます。

データ保持期間・注意事項

• トレースデータの保持期間は24時間です（日次CRONで自動削除）。
• プロンプト内容・レスポンス内容はトレースに保存されません（プライバシー保護のため）。
• トレース書き込みはノンブロッキングで行われ、レスポンス速度への影響はありません。
• フィーチャートグルからAgent Traceをオン/オフ切り替えできます（デフォルト: オフ）。

活用例

16. シークレット・シールド NEW

シークレット・シールドは、AIプロバイダーへ送信するリクエストに含まれる機密情報・個人情報（PII）を自動検出・マスキングする機能です。APIキー、クレジットカード番号、マイナンバーなどを正規表現ルールで定義し、プロバイダーに届く前に自動的に置換します。

対象プラン

処理フロー

リクエスト受信（proxy.routes.ts）
  ↓
[シークレット・シールド ON の場合]
  ├─ D1からカスタムルール取得（正規表現リスト）
  ├─ messages[] の全テキストをスキャン
  ├─ マッチ箇所をマスキング文字列に置換
  └─ フェイルオープン（エラー時もリクエスト継続）
  ↓
マスキング済みメッセージをAIプロバイダーへ送信
  ↓
使用ログもマスキング済み内容で記録

マスキング方式

プリセットレシピ（11件）

よく使われるパターンをワンクリックで適用できます。

設定手順

1. ダッシュボード左メニュー「シークレット・シールド」をクリック
2. 「フィーチャー管理」でシークレット・シールドをオンにする
3. プリセットから選ぶか、カスタムルールを追加
4. 「何を隠したいか」を日本語で入力 → ✨ AIで正規表現を生成（Workers AI使用）
5. 生成された正規表現を確認・編集し、マスキング方式を選択して保存
6. テスト欄にサンプルテキストを入力して動作確認

注意事項

• ルール上限は20件/ユーザーです。
• マスキング処理でエラーが発生しても、リクエストは継続されます（フェイルオープン）。マスキングが確実に必要な場合はプロバイダー側のアクセス制御との併用を推奨します。
• マスキングはリクエストの messages[] フィールドにのみ適用されます。カスタムヘッダー等は対象外です。
• 使用ログにはマスキング済みの内容が記録されます。元のテキストはqziraに保存されません。

17. 自動モデルルーティング（Smart Routing）NEW

Smart Routingは、リクエストされたモデルを自動的に最適なプロバイダーのモデルに振り分ける機能です（Scale プラン専用）。コスト最適化やレイテンシ改善を目的として、複数プロバイダーを効率的に活用できます。

3つのルーティング戦略

メリット

• コスト最適化: 同等性能で安価なプロバイダーへ自動切替（最大30-50%削減の可能性）
• レート制限回避: 複数プロバイダーに分散することでスロットリングを軽減
• コード変更不要: ダッシュボードでトグルONにするだけで有効化

デメリット・注意点

• モデル固有の挙動（出力形式、ツール呼び出し仕様）に依存するエージェントでは予期しない動作が発生する可能性
• プロバイダー間でレスポンス品質にばらつきが出る場合がある
• セマンティックキャッシュ使用時、ルーティング後のモデル名でマッチングが行われる点に注意

設定方法

1. ダッシュボードの「機能設定」ページを開く
2. 「自動モデル・ルーティング」のトグルをONにする
3. ルーティング戦略（コスト最適化 / レイテンシ最適化 / ラウンドロビン）を選択
4. 2つ以上のプロバイダーのAPIキーが登録・有効化されていることを確認

18. フェイルオーバー詳細NEW

フェイルオーバーは、AIプロバイダーがエラーを返した際に、自動的に別のプロバイダーの同等モデルに切り替えてリクエストを再送する機能です（Starter プラン以上）。

プラン別リトライ回数

動作フロー

フェイルオーバー対象外

• 400 系エラー（Bad Request, 認証エラーなど）: クライアント側の問題のため、別プロバイダーでも同じ結果になる
• 404 モデル不明: 指定されたモデルが存在しない場合
• 有効なプロバイダーが1つのみ: 切替先がない場合

設定方法

1. 2つ以上のプロバイダーのAPIキーを登録・有効化
2. ダッシュボードの「機能設定」ページを開く
3. 「フェイルオーバー」のトグルをONにする

責任分界と免責事項

qziraはBYOK（Bring Your Own Key）方式のAPIゲートウェイです。各領域の責任範囲を明確にしています。

責任分界表

コスト管理機能の限界

qziraの予算アラート・自動停止機能は、コスト管理を支援するものです。以下の点にご注意ください:

• 予算アラートはリクエスト数ベースで、実際のプロバイダー課金額とは異なる場合があります
• 自動停止は次のリクエスト受信時に判定されるため、既に処理中のリクエストは停止されません
• ネットワーク遅延やシステム障害時に、アラート・停止の発動が遅れる可能性があります
• コスト管理機能は「ベストエフォート」で提供されます
• 予算使用量の集計は一定間隔で更新されるため、集計タイミングにより設定上限を超過する場合があります

プラン別の保護レベル

AIエージェント利用時の注意

AIエージェント（Cursor、Claude Code、Devin等）は自律的にAPIリクエストを送信します。エージェントの動作はユーザーの責任範囲となりますので、以下の対策を推奨します:

• 日次リクエスト上限を設定する（Starter以上）
• 自動停止を有効にする（Pro以上）
• 定期的にダッシュボードで使用状況を確認する
• 夜間の自動実行タスクには特に注意する

SLA（サービスレベル）

qziraは可用性の維持に努めていますが、現時点ではSLA保証は提供していません。インフラの安全性確保のため、事前通知なくサービスを一時停止する場合があります。詳細は利用規約をご確認ください。

よくある質問（FAQ）

料金について

Q. Freeプランに期間制限はありますか？

いいえ、Freeプランは期間制限なく利用できます。月間1,000リクエストまで、1プロバイダーの有効化が可能です。

Q. qziraの料金以外にコストはかかりますか？

はい。qziraはBYOK方式のため、各AIプロバイダー（OpenAI、Anthropic、Google AI、DeepSeek）の利用料金は別途発生します。qziraの月額料金はゲートウェイ機能の利用料です。

Q. プラン変更はいつでもできますか？

はい、ダッシュボードからいつでもアップグレード・ダウングレードが可能です。アップグレードは即座に反映され、ダウングレードは現在の請求期間の終了時に反映されます。なお、ダウングレードは月1回までの制限があります。

セキュリティについて

Q. 登録したAPIキーはどのように保護されていますか？

APIキーは暗号化して保存されます。通信はすべてHTTPS（TLS 1.3）で暗号化されており、qziraのスタッフがAPIキーの平文を閲覧することはできません。

Q. qziraはリクエスト内容を学習に使用しますか？

いいえ。qziraはリクエスト内容をAIモデルの学習やサービス改善の目的で使用しません。データはリクエストの中継と使用量の計測のみに使用されます。

Q. データはどの地域に保存されますか？

qziraのインフラはCloudflareのグローバルネットワーク上で稼働しています。ユーザーデータはCloudflareのデータセンターに保存されます。

Q. APIキーが漏洩した場合はどうすればいいですか？

ダッシュボードの「APIキー」画面から、該当キーのローテーション（再発行）を即座に実行してください。旧キーは即座に無効化されます。詳しくはセクション11をご確認ください。

サービスについて

Q. qziraがダウンした場合、APIは使えなくなりますか？

qzira経由のリクエストは影響を受けます。即時切り戻し（Base URLとAPIキーを元に戻す）により、プロバイダーへの直接アクセスに切り替えることが可能です。

Q. 対応していないモデルを指定するとどうなりますか？

400 Invalid model エラーが返されます。対応モデル一覧はコード移行セクションをご確認ください。

Q. ストリーミングは全プロバイダーで使えますか？

はい。OpenAI、Anthropic、Google AI、DeepSeekすべてのプロバイダーでSSE形式のストリーミングに対応しています。全プランで利用可能です。

Q. レート制限に引っかかった場合はどうすればいいですか？

qziraのレート制限（429エラー）が発生した場合は、少し時間を置いてからリトライしてください。Starter以上のプランでは、qziraが自動リトライを代行します。

Q. アクセス制御でブロックされたリクエストは課金されますか？

いいえ。アクセス制御チェックはプロバイダーAPIへのリクエスト送信前に行われるため、ブロックされたリクエストに対してプロバイダーの課金は発生しません。qziraの使用量カウンターにも加算されません。

Q. アクセス制御はChat Completions APIとResponses APIの両方に適用されますか？

はい。アクセス制御はリクエストのルーティング前にチェックされるため、Chat Completions API（/v1/chat/completions）とResponses API（/v1/responses）の両方に適用されます。

Q. セマンティックキャッシュとレスポンスキャッシュの違いは何ですか？

レスポンスキャッシュ（セクション12）はリクエストが完全に一致した場合にのみヒットします。セマンティックキャッシュ（セクション15）はAIベクトル検索により、表現が異なっていても意味が似たリクエストを検出してキャッシュを再利用します。両方を併用することで、最大限のトークン節約が可能です。

Q. セマンティックキャッシュで誤った応答が返されることはありますか？

類似度閾値を適切に設定することで誤ヒットを最小限に抑えられます。推奨値は0.92です。精度を重視する場合は0.95以上に設定してください。また、ストリーミングリクエストやマルチターン会話は自動的に対象外となるため、AIエージェントの対話型利用では安全に使用できます。

Q. リクエストログはいつまで保持されますか？

プランに応じた期間で自動保持されます: Free（3日）、Starter（30日）、Pro（30日）、Business（90日）、Scale（365日）。保持期間を過ぎたログは自動削除され、復元できません。長期保存が必要な場合はCSVエクスポートをご利用ください。

Q. 使用量データをエクスポートできますか？

はい。ダッシュボードの「リクエストログ」セクションからCSV形式でエクスポートできます。モデル、プロバイダー、トークン数、レイテンシなどの情報が含まれます。全プランで利用可能です。

解約について

Q. 解約するとデータはどうなりますか？

アカウント削除を行うと、登録されたAPIキー、使用履歴、設定情報はすべて削除されます。この操作は取り消せません。

Q. 解約後も請求は発生しますか？

有料プランの場合、解約操作を行うと現在の請求期間の終了時にFreeプランにダウングレードされます。日割り返金には対応していません。

Smart Routing・フェイルオーバーについて

Q. Smart Routing（自動モデルルーティング）とフェイルオーバーの違いは何ですか？

Smart Routingは正常時の最適配分です。コスト・レイテンシ・負荷分散の観点から、リクエストを最適なプロバイダーに振り分けます（Scale専用）。フェイルオーバーは障害時の緊急切替です。プロバイダーが5xxエラーや429エラーを返した際に、自動的に別プロバイダーの同等モデルに切り替えます（Starter以上）。両方を有効にすると、Smart Routingで選ばれたプロバイダーが障害の場合にフェイルオーバーが発動します。

Q. フェイルオーバーでモデルが切り替わると、AIエージェントの動作に影響はありますか？

影響が出る可能性があります。プロバイダーによってJSON出力形式やツール呼び出しの仕様が異なるため、モデル固有の挙動に依存するエージェントでは予期しない動作が発生することがあります。このため、フェイルオーバーはデフォルトで無効に設定されています。有効化する前に、複数プロバイダーでの動作を確認することを推奨します。

Tool Calling（関数呼び出し）について

Q. qziraはプロバイダー間のTool Calling形式の違いを自動変換しますか？

はい。qziraはOpenAI形式の tools / tool_choice パラメータを受け取り、各プロバイダーのネイティブ形式に自動変換します。Cursor、Cline、Roo Code などのAIコーディングツールが送信するTool Calling リクエストは、OpenAI・Anthropic・Google AI のいずれのプロバイダーでも追加設定なしで動作します。

Q. Tool Callingの自動変換で対応していない形式はありますか？

現在の変換は OpenAI 互換形式（tools 配列 + function 定義）を基準としています。Anthropicネイティブの tool_use 形式やGoogleネイティブの function_declarations 形式で直接送信した場合、そのプロバイダーにはそのまま転送されますが、フェイルオーバーやSmart Routingで別プロバイダーに切り替わった際に変換が正しく行われない場合があります。OpenAI互換形式で統一して送信することを推奨します。

画像・マルチモーダルについて

Q. 画像を含むリクエストはqzira経由で送信できますか？

はい。qziraはリクエストボディをパススルー（そのまま中継）するため、各モデルが対応している画像入力（Base64エンコード / URL指定）をそのまま送信できます。

Q. OpenAI形式で送った画像を、Anthropicの形式に自動変換してくれますか？

いいえ。プロバイダー間での画像フォーマットの自動変換機能はありません。OpenAI形式（image_url）で画像を含むリクエストをAnthropicモデルに送信した場合、フォーマット不一致でエラーになります。画像を含むリクエストでは、送信先プロバイダーの仕様に合わせたフォーマットで送信してください。フェイルオーバーで別プロバイダーに切り替わった場合も同様に、画像部分は変換されない点にご注意ください。

緊急時の切り戻し（ロールバック）

Q. qziraの障害時に、最短で復旧する方法は？

以下の2点を変更するだけで、10秒でプロバイダーへの直接通信に復旧できます。

1. Base URL: 削除（デフォルトに戻す）、または各プロバイダーの公式URLに変更
2. API Key: gw_... から、各プロバイダー発行の元のキー（sk-... など）に差し替え

qziraはBase URLを変更するだけで導入・切り戻しができる設計です。SDKやコードの大幅な書き換えは不要です。詳しくはセクション16（責任分界と免責事項）の「即時切り戻し方法」をご確認ください。

Agent Traceについて

Q. Agent Traceはどのプランで使えますか？

Agent TraceはScaleプラン専用の機能です。フィーチャートグルからオン/オフを切り替えられます（デフォルト: オフ）。トレースデータは24時間保持後に自動削除されます。

Q. Agent Traceでプロンプトの内容は記録されますか？

シークレット・シールドについて

Q. シークレット・シールドはどのプランで使えますか？

シークレット・シールドはScaleプラン専用の機能です。フィーチャートグルからオン/オフを切り替えられます（デフォルト: オフ）。

Q. マスキングに失敗した場合、リクエストは止まりますか？

いいえ。マスキングエラーが発生してもリクエストはそのまま継続されます（フェイルオープン設計）。機密情報の送信を確実に防ぎたい場合は、Per-Keyアクセス制御やプロバイダー側の制限との併用を推奨します。

Q. マスキングされた元のテキストはどこかに保存されますか？

いいえ。マスキング処理はAPIリクエスト時にメモリ上のみで行われます。使用ログにはマスキング済みの内容のみ記録され、元テキストはどこにも保存されません。

いいえ。プロンプト内容・レスポンス内容はトレースに保存されません。記録されるのは処理ステップ名・処理時間（ms）・キャッシュヒット有無などのメタデータのみです。

トラブルシューティング

よくあるエラー

即時切り戻し方法

qzira経由で問題が発生した場合、Base URLとAPIキーを元に戻すだけで即座に直接呼び出しに切り替えられます。

# qzira経由 → 直接呼び出しに切り戻し
client = OpenAI(
    api_key="sk-xxxxxxxx",           # 元のAPIキーに戻す
    # base_url を削除（デフォルトに戻る）
)

環境変数で管理している場合は、.env ファイルの値を切り替えるだけです:

# QZIRA_API_KEY=gw_xxxxxxxx          ← コメントアウトで切り戻し
# QZIRA_BASE_URL=https://api.qzira.com/v1
OPENAI_API_KEY=sk-xxxxxxxx            # ← 元のキーがそのまま使える

法的ドキュメント

qziraの利用に関する法的ドキュメントは以下のリンクからご確認いただけます。

利用規約の重要条項

サポート

ご質問・不具合報告は以下よりお問い合わせください。

• お問い合わせフォーム: https://138io.com/contact/
• メール: [email protected]
• 運営: 138data（屋号: いちのみやデータ復旧室）

法的免責事項 / Legal Disclaimer

免責事項（日本語）

Legal Disclaimer (English)

1. Service Provided "As-Is"
To the maximum extent permitted by applicable law, this documentation and the qzira service are provided on an "as-is" and "as-available" basis without warranties of any kind, whether express, implied, or statutory, including but not limited to implied warranties of merchantability, fitness for a particular purpose, and non-infringement. The information contained herein reflects the state of the service as of the date of publication and may not reflect subsequent changes.

2. Third-Party Dependency and Provider Risks
qzira operates as an API gateway that routes requests to third-party AI providers including OpenAI, Anthropic, and Google. Core features — including but not limited to chat completions, streaming, Tool Calling (Function Calling), failover, smart routing, response caching, and semantic caching — depend on the continued availability and compatibility of these providers' APIs. Provider-side changes such as API specification updates, model deprecation, pricing modifications, rate limit adjustments, or service discontinuation may affect qzira's functionality without prior notice. Users are solely responsible for compliance with each provider's Terms of Service, Acceptable Use Policy, and data handling policies.

3. Limitation of Liability
To the maximum extent permitted by applicable law, qzira and its operator, 138data (屋号: いちのみやデータ復旧室), shall not be held liable for any direct, indirect, incidental, consequential, or special damages arising from the use of or inability to use the service, including but not limited to unexpected API billing, loss of data, business interruption, or loss of profits, regardless of the theory of liability.

4. Budget Controls and Auto-Stop Disclaimer
qzira provides budget management features including budget alerts, automatic stop (Auto-Stop), and per-API-key budget limits as tools to assist users in managing their API expenditure. These features operate on a best-effort basis and do not guarantee the prevention of all overspending. Factors such as processing delays, concurrent requests, provider-side latency, and exchange rate fluctuations may result in actual charges exceeding configured budgets. Users remain solely responsible for monitoring their own API usage and costs, and the availability of these features does not relieve users of this responsibility.

予算管理機能に関する免責

予算上限はベストエフォートで適用されます。使用量の集計処理のタイミングにより、設定上限を超過する場合があります。API利用料はユーザーと各AIプロバイダーとの契約に基づき発生し、超過分を含む利用料金は当該契約条件に従います。正確な使用状況はダッシュボードの利用ログをご確認ください。

qziraはAPIリクエストの仲介および制御を行うサービスであり、API利用料の請求主体ではありません。

5. Budget Management Disclaimer
Budget limits are enforced on a best-effort basis. Due to the timing of usage aggregation, actual spending may exceed the configured limit. API charges are incurred under the agreement between the user and each AI provider, and any overage is subject to those terms. Please refer to the usage logs in your dashboard for accurate usage details.

qzira acts solely as an API gateway and control layer and is not the billing entity for API usage charges.