OpenAI 互換 API

OpenAI 互換エンドポイント（/v1/*）。既存の OpenAI SDK / ツールから、base URL と API キーを差し替えて使う。Anthropic 互換の /v1/messages にも対応する。

エンドポイント一覧

OpenAI / Anthropic 互換

DigitalBase 独自（管理系）

組み込み API リファレンス

• オフラインでも表示できる。[API キー] 画面の [API リファレンス] からも開ける。
• GATEWAY_DOCS_ENABLED=false で両 URL を非公開にする（404）。
• GET /v1/tools は、キーに提示するツールを OpenAI function 形式で返す。基準は MCP の tools/list と同じ。アシスタントを紐づけていないキーは空。
• xdb.level は必要権限。xdb.write_level は書込文で上がる権限（query_dataset / query_sql）。

利用例

curl でチャット補完を呼ぶ。

curl http://<HOST>:8000/v1/chat/completions \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "messages": [{"role": "user", "content": "こんにちは"}],
    "stream": true
  }'

OpenAI Python SDK は base_url を差し替えて使う。

from openai import OpenAI

client = OpenAI(base_url="http://<HOST>:8000/v1", api_key="<API_KEY>")
res = client.chat.completions.create(
    model="<model>",
    messages=[{"role": "user", "content": "こんにちは"}],
)

リクエストパラメータとモデル別の挙動

/v1/chat/completions のパラメータの扱いは接続先モデルで異なる。stream（SSE）は全モデルで対応する。n は 1 のみで、2 以上は 400。

• tools / tool_choice は、API キーの tool_passthrough（ツール呼び出しの透過）が ON の時だけモデルへ渡し、tool_calls を返す。ローカルは tool 対応モデルのみ。
• OFF のキーでは tools / tool_choice を無視し、紐づけたアシスタントのツールをサーバー側で実行する。
• サーバー側でツールを実行する応答では、stop / response_format などは使えない。無視して xdb.warnings で通知する。

reasoning_effort（思考の深さ）

値は "none" / "low" / "medium" / "high" / "max"。未指定はモデル既定。

• metadata.xdb.thinking（bool 可: true=high / false=none）でも指定できる。両方ある場合は metadata が優先。
• 思考非対応モデルに指定してもエラーにならない。

アシスタント（Bot）を指定する

model にアシスタントの名前（または asst_ で始まる ID）を渡すと、そのアシスタントの設定（ナレッジ・プロンプト・ツール）で応答する。

• GET /v1/models はチャット用モデルとアシスタント名を列挙する。埋め込みモデルは含まない。
• 一覧に無いモデル名と model 省略時は、既定のチャットモデルで応答する。応答の model は実際に使ったモデル ID。
• 存在しない / 参照できないアシスタント ID は 404（code: model_not_found）。

エラー応答

OpenAI と同じ形の JSON を返す（/v1/messages* は Anthropic 形式 {"type":"error","error":{"type","message"}}）。

{"error": {"message": "The model 'asst_xxxx' does not exist or you do not have access to it", "type": "invalid_request_error", "param": "model", "code": "model_not_found"}}

RAG の出典

RAG を使う応答は、参照した社内文書（出典）を拡張フィールド xdb.sources に含む。

ツール実行の経過

ツールを使った応答は、実行したツールを実行順に拡張フィールド xdb.tool_steps に含む（ストリームでは最終チャンク）。

/v1/messages と /v1/responses では、metadata.xdb.extra_events: true を指定した時だけ、経過を独自イベント（xdb_tool_step / xdb.tool_step）で逐次送出する。

画像生成

POST /v1/images/generations / POST /v1/images/edits で画像を生成・編集する。OpenAI の画像 API と同じ形で、管理者が設定した画像エンジン（AIエージェントの画像生成）が処理する。

from openai import OpenAI
import base64
client = OpenAI(base_url="https://<host>/v1", api_key="sk-...")
r = client.images.generate(model="gpt-image-1", prompt="夕焼けの工場の水彩画", size="1024x1024")
open("out.png", "wb").write(base64.b64decode(r.data[0].b64_json))

• model は受け付けるが、処理は設定済みのエンジン（IMAGE_GEN_MODEL）が行う。
• 応答は base64（response_format は b64_json のみ）。
• n: 1〜4。size: 幅x高さ か auto。output_format: png / jpeg / webp。
• 編集の入力は multipart の image（複数は image[]）。PNG / JPEG / WEBP、1 枚 25 MB まで。mask は非対応。
• エラー: エンジン未設定 503（image_generation_not_configured）、エンジン側エラー 502、時間切れ 504。
• 利用量はチャネル image で記録する（レート制限・月次上限の対象）。

動画生成

/v1/videos で動画を生成する。OpenAI の動画 API と同じ非同期ジョブ形式で、管理者が設定した動画エンジン（AIエージェントの動画生成）が処理する。

from openai import OpenAI
import time
client = OpenAI(base_url="https://<host>/v1", api_key="sk-...")
video = client.videos.create(model="grok-imagine-video-1.5", prompt="夕焼けの工場をドローンで横切る映像", seconds="8", size="1280x720")
while video.status in ("queued", "in_progress"):
    time.sleep(5)
    video = client.videos.retrieve(video.id)
if video.status == "completed":
    client.videos.download_content(video.id).write_to_file("out.mp4")

作成すると status: "queued" のジョブを返す。完成後に /content で mp4 を取得する。

• model は受け付けるが、処理は設定済みのエンジン（VIDEO_GEN_MODEL）が行う。
• seconds: 1〜15。size（例 1280x720）、または aspect_ratio / resolution（480p / 720p / 1080p、既定 VIDEO_GEN_RESOLUTION）。
• input_reference: 最初のコマの画像。reference_images: 参照画像（最大 4 枚）。PNG / JPEG / WEBP、25 MB まで。
• 状態: queued / in_progress / completed / failed / cancelled。VIDEO_GEN_TIMEOUT_SEC を過ぎたものは failed。
• 状態確認・取得はジョブを作った API キーのみ。未完成ジョブの /content は 409（video_not_ready）。
• 完成した動画はキーの持ち主の 個人フォルダ/generated-videos/ にも保存する。
• エラー: エンジン未設定 503（video_generation_not_configured）、入力の誤り 400、エンジン側エラー 502。
• 利用量はチャネル video で記録する（レート制限・月次上限の対象）。

文字起こし

POST /v1/audio/transcriptions で文字起こしする。OpenAI の Audio Transcriptions と同じ multipart 形式で、この環境の Whisper が処理する（音声を外部に送らない）。

from openai import OpenAI
client = OpenAI(base_url="https://<host>/v1", api_key="sk-...")
with open("meeting.m4a", "rb") as f:
    r = client.audio.transcriptions.create(model="whisper-1", file=f, language="ja")
print(r.text)

• model は受け付けるが、処理は導入済みの Whisper モデルが行う。
• 入力: wav / mp3 / m4a / webm / ogg / flac / aac（動画ファイルの音声トラックも可）。1 ファイル FILE_UPLOAD_MAX_MB まで（既定は空 = 上限なし）。
• language（ja / en など。省略時は WHISPER_LANGUAGE、未設定なら自動判定）、prompt（社名・専門用語などの語彙）。
• response_format: json（既定）/ text / verbose_json（区間付き）。
• エラー: Whisper モデル未導入 503（model_not_installed）、非対応の形式 400、上限超過 413。

Anthropic 互換（/v1/messages）

Anthropic Messages API 形式。Claude 向け SDK / ツールから、base URL と API キー（sk-）を差し替えて使う。

• system / messages・tools / tool_choice・ストリーミング（SSE）に対応する。応答は Anthropic 形式。
• 認証は x-api-key: sk-... または Authorization: Bearer sk-...。
• tools は tool_passthrough が ON のキーだけモデルへ渡す（Claude Code 接続）。
• thinking と output_config.effort は reasoning_effort と同じ思考制御に変換する。

関連

• APIアクセスキー — 認証キーの発行・制限
• MCP — ツールを外部エージェントに公開
• AIエージェント