BLACKBOX-Free-Proxy

BLACKBOX AI の API を OpenAI 互換の REST API として変換するプロキシサーバー。

概要

このプロジェクトは BLACKBOX AI のバックエンド API をプロキシし、OpenAI と互換性のある REST API を提供します。TypeScript + Express で構築されており、ストリーミングレスポンスやツール呼び出し（Function Calling）をサポートしています。

主な機能

• OpenAI Response API 互換 - /v1/responses エンドポイント
• Chat Completions API 互換 - /v1/chat/completions エンドポイント
• Completions API 互換 - /v1/completions エンドポイント
• モデル一覧取得 - /v1/models エンドポイント
• ストリーミングレスポンス - SSE (Server-Sent Events) 対応
• ツール呼び出し (Function Calling) - ツール定義のサポート
• ビジョン（画像）処理 - image_url / input_image 形式の画像入力対応
• Upstream 4000 トークン制限の自動リトライ - truncation 検出 + continuation
• 多数のモデル - Claude, GPT, Gemini, Qwen など 300 以上のモデルを選択可能

クイックスタート

前提条件

• Node.js 20.x 以上
• npm

ローカル起動

# 1. リポジトリをクローン
git clone https://github.com/taigaoryakisoba/BLACKBOX-Free-Proxy.git
cd BLACKBOX-Free-Proxy

# 2. 依存関係をインストール
npm install

# 3. .env ファイルを作成（.env.example を参考）
cp .env.example .env
# .env を編集して必要な値を設定

# 4. 開発モード（ホットリロード）
npm run dev

# 本番モード
npm run build
npm start

デフォルトでは http://localhost:3030 で動作します。

Docker / Podman で起動

# イメージをビルドして起動
docker compose up -d

# または Podman の場合
podman compose up -d

Dockerfile はマルチステージビルドを採用しており、本番用の軽量イメージを生成します。 ヘルスチェックも組み込まれています。

環境変数

.env ファイルで以下の設定が可能です：

変数名	デフォルト値	説明
PORT	3030	サーバーがリスンするポート
PROXY_BEARER_TOKEN	(空)	プロキシ自体の Bearer 認証トークン。未設定時は認証なし
BLACKBOX_API_ENDPOINT	https://app.blackbox.ai/api/chat	BLACKBOX AI の API エンドポイント
BLACKBOX_VALIDATION_TOKEN	(空)	認証トークン。未設定時は live bundle から自動発見
BLACKBOX_MAX_TOKENS	1024	最大トークン数
BLACKBOX_CUSTOMER_ID	(空)	サブスクライバー ID
BLACKBOX_SESSION_TOKEN	(空)	セッショントークン
BLACKBOX_LOGIN_EMAIL	(空)	BLACKBOX へ自動ログインするメールアドレス
BLACKBOX_LOGIN_PASSWORD	(空)	BLACKBOX へ自動ログインするパスワード
BLACKBOX_LOGIN_EAGER	false	起動直後にログインをウォームアップするか
CORS_ORIGINS	(空)	許可される CORS オリジン（カンマ区切り）
DEBUG_LOG	false	デバッグログを有効化

PROXY_BEARER_TOKEN を設定した場合、各 API リクエストに Authorization: Bearer <token> ヘッダーが必要です。

API エンドポイント

POST /v1/chat/completions

OpenAI Chat Completions API 互換。ストリーミング・非ストリーミング両対応。

curl http://localhost:3030/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d ''{
    "model": "anthropic/claude-sonnet-4.6",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }''

POST /v1/completions

OpenAI Completions API 互換。

curl http://localhost:3030/v1/completions \
  -H "Content-Type: application/json" \
  -d ''{
    "model": "openai/gpt-4.1-nano",
    "prompt": "Once upon a time"
  }''

POST /v1/responses

OpenAI Responses API 互換。会話の継続（previous_response_id）にも対応。

GET /v1/models

利用可能なモデルの一覧を取得。

画像入力（Vision）

Chat Completions API で画像を含むメッセージを送信できます：

{
  "model": "openai/gpt-4.1-nano",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "この画像を説明してください"},
      {"type": "image_url", "image_url": {"url": "https://example.com/image.png"}}
    ]
  }]
}

• http://https:// URL は自動的に Base64 に変換されます
• data: URI はそのまま送信されます
• Responses API の input_image 形式にも対応しています

Upstream トークン制限の自動リトライ

BLACKBOX AI では約 4000 トークンでレスポンスが途切れる制限があります。本プロキシでは以下の仕組みで自動的に対処します：

1. Truncation 検出 - レスポンスが不自然に途切れていないかヒューリスティックで判定
2. 自動 Continuation - 途切れを検出した場合、continuation プロンプトを付与して再リクエスト
3. Sentinel 検出 - モデルが $$CONTINUE_COMPLETE$$ を返した場合、応答完了と判断
4. 最大 3 回リトライ - 無限ループを防止

この機能は streaming / non-streaming の両方で動作します。

利用可能なモデル（主要なもの）

pro 以上の課金アカウント利用時は 300 以上のモデルをサポートしています。 /v1/models エンドポイントで全一覧を取得できます。

プロバイダー	主なモデル
Anthropic	anthropic/claude-sonnet-4.6, anthropic/claude-opus-4.6
OpenAI	openai/gpt-5.2-codex, openai/gpt-4.1-nano
Google	google/gemini-3.1-pro-preview, google/gemini-3-pro-preview
Qwen	qwen/qwen3-coder:free, qwen/qwen3-32b
DeepSeek	deepseek/deepseek-r1, deepseek/deepseek-chat
Meta	meta-llama/llama-4-maverick, meta-llama/llama-4-scout
xAI	x-ai/grok-4, x-ai/grok-3
BLACKBOX	blackbox/free（無料アカウントでも利用可能）

その他 AI21, Baidu, ByteDance, Cohere, IBM, Nvidia, Perplexity, Tencent, Xiaomi 等多数。

アーキテクチャ

+-------------+    +------------------+    +-----------------+
|  Client     |--->| BLACKBOX-Proxy   |--->| Blackbox AI     |
|  (OpenAI    |    | (Express/TS)     |    | Chat API        |
|   Client)   |<---|                  |<---|                 |
+-------------+    +------------------+    +-----------------+

コンポーネント

• src/routes/v1/ - API エンドポイント
• src/services/ - ビジネスロジック（Blackbox API 通信、認証、バリデーション）
• src/utils/ - ユーティリティ（ID 生成、ストリーミング処理、truncation 検出）
• src/configs/ - 設定（モデル定義、環境変数）

開発

npm run dev        # 開発モード（ホットリロード）
npm run build      # ビルド
npm run typecheck  # 型チェック
npm run lint       # リント
npm run lint:fix   # リント自動修正

OpenAPI 仕様は openapi.yaml を参照してください。

謝辞

• BLACKBOX AI - バックエンド API
• OpenAI - API デザイン
• kuwacom/BLACKBOX-OpenAI-Proxy - フォーク元

---

注意 このプロキシは非公式です。 BLACKBOX AI の利用条件に従って使用してください。