> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiperai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# チャットの完了
> The main endpoint for AI chat completions with optional knowledge base retrieval (RAG).
This endpoint supports multiple AI models, security policies, and can search your
knowledge bases for relevant context to enhance responses.
# チャットの完了
オプションのナレッジ ベース取得 (RAG)、モデルの冗長性/フェイルオーバー、通話ごとのセキュリティ ポリシー、ストリーミングを備えた AI チャット完了のメイン エンドポイント。
## エンドポイント
```
POST /chat/completions
```
## 説明
オプションのナレッジ ベース取得 (RAG) を備えた AI チャット完了のメイン エンドポイント。以下をサポートします。
* **2 つの入力形式** - 単一の `prompt` 文字列 (レガシー) **または** OpenAI スタイルの `messages` 配列。
* **モデルの冗長性** — 呼び出し元定義のフェイルオーバー チェーン (プライマリ + 最大 2 つのフォールバック)。 「冗長性とフェイルオーバー」(/ja/ja/api/redundancy) を参照してください。
* **通話ごとのセキュリティ** - SMLTP ポリシーの選択とインライン プロンプト シールドのオーバーライド。
* **ストリーミング** — サーバー送信イベント (SSE)。
* **署名済み受領書** — ゲートウェイを介してルーティングされた応答に関する SMLTP 準拠の受領書参照。
**OpenAI SDK の互換性**
**コード変更なし**で SecureAI を既存の OpenAI 統合にドロップしたい場合は、代わりに `/api/external/v1/chat/completions` の [OpenAI 互換エンドポイント](/ja/en/api/chat/openai-compatibility) を使用してください。このクラシック エンドポイントは、RAG をサポートする唯一のエンドポイントです。
## 認証
必須: API キー
```bash theme={null}
Authorization: Bearer sk-your-api-key-here
```
## ヘッダー
| ヘッダー | 必須 | 説明 |
| ----------------- | --- | --------------------------------------------------------------------------- |
| `Authorization` | はい | `Bearer sk-...` |
| `Content-Type` | はい | `application/json` |
| `Idempotency-Key` | いいえ | 完了 POST を安全に再試行できるようにする一意のキー。同じキーを使用してリクエストを繰り返すと、2 回請求されるのではなく、元の結果が返されます。 |
## リクエスト本文
### 入力パラメータ
\*\*`prompt` **または** `messages` の両方を指定することはできません。
| パラメータ | タイプ | 必須 | 説明 |
| ---------------- | --- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt` | 文字列 | 条件付き | ユーザーのメッセージ (従来の 1 ターン フォーム)。 |
| `messages` | 配列 | 条件付き | `{ role, content }` の OpenAI スタイルの配列。 `role` は `system`、`user`、または `assistant` です。 `system` メッセージは最大 1 つ、最初のエントリとしてのみ。最大 100 メッセージ、合計コンテンツ 256 KB。 |
| `system_message` | 文字列 | いいえ | カスタム システム プロンプト (レガシー)。 `messages` の帯域内 `system` ロールと組み合わせることはできません。 |
### モデルと冗長パラメータ
| パラメータ | タイプ | 必須 | 説明 |
| ----------------- | ------ | ---- | -------------------------------------------------------------------------------------------------------------------------- |
| `model` | 文字列 | 条件付き | AI モデル (例: `"openai/gpt-5-nano"`)。 `models` が指定されていない場合は必須です。 |
| `models` | 配列 | いいえ | 明示的なフェイルオーバー チェーン (`model` をオーバーライドします)。最大 3 つの異なるエントリ。各エントリはモデル文字列または `{ model, timeout_ms, first_token_timeout_ms }` です。 |
| `fallback_models` | 配列 | いいえ | フォールバックは `model` の後に追加されます。 `models`との併用はできません。 |
| `redundancy` | オブジェクト | いいえ | チェーン全体のオプション: `{ timeout_ms, first_token_timeout_ms, on: [...] }`。 「冗長性とフェイルオーバー」(/ja/ja/api/redundancy) を参照してください。 |
### パラメータの取得と生成
| パラメータ | タイプ | 必須 | 説明 |
| ----------------- | ------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `index` | 文字列 | **はい** | クエリするナレッジベース名。 RAG を使用しない直接 AI には `"Zero-Knowledge"` を使用します。このフィールドは必須です。`index` のないリクエストは `400 "Index required"` を返します。 |
| `use_rag` | ブール値 | いいえ | ナレッジの検索を有効にします (デフォルト: `true`)。 `use_rag: false` を設定しても、`index` 要件が免除されるわけではありません。つまり、`index: "Zero-Knowledge"` が送信されます。 |
| `smltp_policy` | 文字列 | いいえ | セキュリティ ポリシー (`"internal"`、`"public"`、`"confidential"`、またはテナント カスタム ポリシー)。 |
| `prompt_shield` | オブジェクト | いいえ | 通話ごとのプロンプト シールド コントロール: `{ enabled?: boolean, policy?: string }`。 [プロンプト シールド API](/ja/en/api/threat-defense/prompt-shield#per-call-control-on-completions) を参照してください。 |
| `temperature` | 番号 | いいえ | ランダムネス制御 (0 ～ 2、デフォルト: 0.7)。 |
| `max_tokens` | 整数 | いいえ | 最大応答トークン (デフォルト: 1000、上限は 4000)。 |
| `stream` | ブール値 | いいえ | 応答を SSE としてストリーミングします (デフォルト: `false`)。 |
| `conversation_id` | 文字列 | いいえ | 追跡用のオプションの会話 ID。 |
| `user_id` | 文字列 | いいえ | このリクエストの請求先となるユーザーの MongoDB ObjectId (管理者ゲート。[請求モード](/ja/en/api/billing-modes) を参照)。 |
## リクエストの例
```bash theme={null}
curl -X POST "https://{customer.name}.hiperai.ai/api/external/chat/completions" \
-H "Authorization: Bearer sk-your-api-key-here" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-4821-summary" \
-d '{
"messages": [
{ "role": "system", "content": "You are a helpful assistant." },
{ "role": "user", "content": "What is the company policy on remote work?" }
],
"model": "openai/gpt-5-nano",
"fallback_models": ["anthropic/claude-sonnet-4"],
"redundancy": { "timeout_ms": 30000, "on": ["timeout", "server_error", "rate_limit"] },
"index": "Zero-Knowledge",
"smltp_policy": "internal",
"temperature": 0.7,
"max_tokens": 1000
}'
```
## 応答
### 成功の応答 (200)
```json theme={null}
{
"success": true,
"id": "req-abc123",
"object": "chat.completion",
"created": 1705312200,
"model": "openai/gpt-5-nano",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Based on the company's remote work policy..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 150,
"completion_tokens": 200,
"total_tokens": 350,
"input_tokens": 150,
"output_tokens": 200
},
"metadata": {
"conversation_id": "conv-123",
"index_used": "Zero-Knowledge",
"smltp_policy_used": "internal",
"smltp_policy_source": "request",
"smltp_policy_hash": "a1b2c3...",
"prompt_shield_policy": null,
"served_model": "openai/gpt-5-nano",
"requested_model": "openai/gpt-5-nano",
"rag_enabled": true,
"documents_retrieved": 0,
"sources": []
}
}
```
### メタデータ オブジェクト
| フィールド | タイプ | 説明 |
| ---------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `conversation_id` | 文字列 | 会話 ID (エコーまたは生成)。 |
| `index_used` | 文字列 | ナレッジベースが使用されます。 |
| `smltp_policy_used` | 文字列 | 適用された SMLTP ポリシー名。 |
| `smltp_policy_source` | 文字列 | ポリシーの取得元 (`request`、キーのデフォルトなど)。 |
| `smltp_policy_hash` | 文字列 \|ヌル | 検証のために適用されたポリシーのハッシュ。 |
| `prompt_shield_policy` | オブジェクト \|ヌル | この通話に適用される Prompt Shield ポリシー (存在する場合)。 |
| `served_model` | 文字列 | 実際に答えを出したモデル。 |
| `requested_model` | 文字列 | 要求されたチェーンの最初のモデル。 |
| `failover` | オブジェクト | **マルチモデル チェーンが実行されている場合にのみ存在します。** `{ occurred, attempts[] }` — [冗長性とフェイルオーバー](/ja/en/api/redundancy) を参照してください。 |
| `smltp` | オブジェクト | SMLTP 資格が通話に対して作成されるときに存在します。 `{ bundle_id, receipt_url }`。 `bundle_id` (権利 ID、例: `jti-…`) は、ネイティブ/直接展開でも返されます。 `receipt_url` の署名付きレシートは、トラフィックが SMLTP ゲートウェイを介してルーティングされる場合にのみ取得できます (それ以外の場合、[Receipts](/ja/en/api/receipts) は `404` を返します)。 |
| `rag_enabled` | ブール値 | RAG が使用されたかどうか。 |
| `documents_retrieved` | 整数 | 取得されたドキュメントの数。 |
| `sources` | 配列 | 最大 3 つの文書ソースを取得 `{ source, score }`。 |
## ストリーミング
サーバー送信イベントを受信するには `"stream": true` を設定します。各 SSE 行は `data: ` で、ストリームは `data: [DONE]` で終わります。フレームは `type` フィールドを介して入力されます。
| フレーム `type` | ペイロード |
| ----------- | ----------------------------------------------------------------------------------------------------------------------- |
| `metadata` | 応答エンベロープ (`id`、`object`、`created`、`model` = サービング モデル、および上記の `metadata` オブジェクト)。最初に送信されました。 |
| `chunk` | 増分デルタ: `{ id, object: "chat.completion.chunk", model, choices: [{ index, delta: { role, content }, finish_reason }] }`。 |
| `usage` | 最終的なトークンの使用法。 |
| `error` | ストリームの途中でプロバイダーが中断されました (最初のトークンの後、フェイルオーバーは不可能になります)。 |
```text theme={null}
data: {"type":"metadata","data":{"success":true,"id":"req-abc123","object":"chat.completion","created":1705312200,"model":"openai/gpt-5-nano","metadata":{...}}}
data: {"type":"chunk","data":{"id":"req-abc123","object":"chat.completion.chunk","model":"openai/gpt-5-nano","choices":[{"index":0,"delta":{"role":"assistant","content":"Based"},"finish_reason":null}]}}
data: {"type":"usage","data":{"usage":{"prompt_tokens":150,"completion_tokens":200,"total_tokens":350}}}
data: [DONE]
```
## エラー応答
### 400 不正なリクエスト
```json theme={null}
{
"success": false,
"error": "Invalid messages",
"message": "a system message is only allowed as the first entry of messages"
}
```
### 401 不正
```json theme={null}
{
"success": false,
"error": "Invalid API key",
"message": "The provided API key is invalid or has been revoked"
}
```
### 403 禁止
```json theme={null}
{
"success": false,
"error": "Access denied",
"message": "Model, index, or policy not allowed"
}
```
### 429 / 502 — 冗長チェーンが枯渇しました
冗長チェーン内のすべてのモデルに障害が発生すると、応答で各試行が報告されます。すべての障害がレート制限であった場合、ステータスは `429`、それ以外の場合は `502` です。
```json theme={null}
{
"success": false,
"error": "All model attempts failed",
"message": "All 2 model attempt(s) failed (last: anthropic/claude-sonnet-4 — server_error)",
"request_id": "req-abc123",
"attempts": [
{ "model": "openai/gpt-5-nano", "status": "failed", "reason": "timeout", "latency_ms": 30012 },
{ "model": "anthropic/claude-sonnet-4", "status": "failed", "reason": "server_error", "latency_ms": 812 }
]
}
```
### 500 内部サーバーエラー
```json theme={null}
{
"success": false,
"error": "Internal server error",
"message": "An unexpected error occurred"
}
```
## 使用例
### JavaScript/Node.js
```javascript theme={null}
const response = await fetch('https://{customer.name}.hiperai.ai/api/external/chat/completions', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-your-api-key-here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
messages: [{ role: 'user', content: 'What is the company policy on remote work?' }],
model: 'openai/gpt-5-nano',
fallback_models: ['anthropic/claude-sonnet-4'],
smltp_policy: 'internal',
temperature: 0.7,
max_tokens: 1000
})
});
const data = await response.json();
console.log('Served by:', data.metadata.served_model);
console.log('Response:', data.choices[0].message.content);
```
### パイソン
```python theme={null}
import requests
url = "https://{customer.name}.hiperai.ai/api/external/chat/completions"
headers = {
"Authorization": "Bearer sk-your-api-key-here",
"Content-Type": "application/json"
}
data = {
"messages": [{"role": "user", "content": "What is the company policy on remote work?"}],
"model": "openai/gpt-5-nano",
"fallback_models": ["anthropic/claude-sonnet-4"],
"smltp_policy": "internal",
"temperature": 0.7,
"max_tokens": 1000
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print("Served by:", result["metadata"]["served_model"])
print("Response:", result["choices"][0]["message"]["content"])
```
## 注意事項
* `index`は必須です。 RAG を使用しない直接 AI 応答の場合は `index: "Zero-Knowledge"` を送信します。
* `user_id` パラメーターは、リクエストを別のユーザー アカウント (管理者ゲート) に請求します。
* 温度は 0 ～ 2 に固定されます。 `max_tokens` の上限は 4000 です。
* モデルの呼び出しやポイントの消費を**せずに**、すべてのポリシーに対してリクエストを検証するには、[ポリシー チェック](/ja/ja/api/policy-check) を使用します。
* フェイルオーバー チェーンのセマンティクス (トリガー、タイムアウト、ストリーミング動作、枯渇ステータス コード) については、[冗長性とフェイルオーバー](/ja/ja/api/redundancy) を参照してください。
## OpenAPI
````yaml POST /chat/completions
openapi: 3.0.3
info:
title: SecureAI External API
description: >
SecureAI External API provides AI chat completion and image generation
capabilities with knowledge base retrieval,
security policies, and comprehensive usage tracking. This API is designed
for external developers
and integrations using API key authentication.
## Key Features
- **RAG (Retrieval-Augmented Generation)**: Automatically search knowledge
bases for relevant context
- **Multi-Model Support**: OpenAI, Anthropic, Google, Meta, and other AI
models
- **Model Redundancy & Failover**: Caller-defined failover chains (primary +
fallbacks) with per-attempt timeouts
- **OpenAI-Compatible Endpoint**: Point any OpenAI SDK at `/api/external/v1`
— no code changes
- **Image Generation**: Generate and edit images using Google Gemini 2.5
Flash Image
- **Speech-to-Speech (S2S)**: Real-time voice conversations using OpenAI
Realtime API with WebRTC
- **Security Policies**: SMLTP policy enforcement, per-call Prompt Shield,
and signed compliance receipts
- **Usage Tracking**: Comprehensive usage monitoring, self-service quota,
and rate limiting
- **Knowledge Base Integration**: Access to personal and shared knowledge
bases
- **User Management**: Complete user, group, and role management
capabilities
- **Audit Logging**: Comprehensive activity and security audit logs
## Authentication
All endpoints (except health check) require API key authentication using
Bearer token:
```
Authorization: Bearer sk-your-api-key-here
```
## Billing and Usage
By default, API requests are billed to the user account that owns the API
key. You can specify
a different user to bill by including the `user_id` parameter in your
request. This allows for:
- Multi-tenant applications with per-user billing
- Flexible completion limit management
- Per-user "Usage by Model" settings
## Rate Limits
- Default: 60 requests per minute, 1000 requests per hour
- Daily limits: 100 requests (configurable)
- Monthly limits: 10,000 requests (configurable)
## Base URL
```
https://secureai.hiperai.ai/api/external
```
version: 1.1.0
contact:
name: SecureAI Support
email: support@secureai.hiperai.ai
license:
name: Proprietary
url: https://secureai.hiperai.ai/terms
servers:
- url: https://secureai.hiperai.ai/api/external
description: Production server
- url: http://localhost:3010/api/external
description: Development server
security:
- ApiKeyAuth: []
tags:
- name: System
description: System health and status endpoints
- name: Discovery
description: Endpoints to discover available models, indexes, and policies
- name: Chat
description: AI chat completion endpoints
- name: User Management
description: Endpoints for managing user accounts and roles
- name: Index Management
description: Endpoints for managing knowledge base indexes
- name: Group Management
description: Endpoints for managing user groups
- name: SMLTP Security
description: Endpoints for managing SMLTP security policies and audit logs
- name: Role Management
description: Endpoints for managing user roles
- name: Activity Logs
description: Endpoints for retrieving activity logs
externalDocs:
description: SecureAI Documentation
url: https://secureai.hiperai.ai/docs
paths:
/chat/completions:
post:
tags:
- Chat
summary: Chat Completion
description: >
The main endpoint for AI chat completions with optional knowledge base
retrieval (RAG).
This endpoint supports multiple AI models, security policies, and can
search your
knowledge bases for relevant context to enhance responses.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- prompt
properties:
model:
type: string
description: The AI model to use for completion
example: openai/gpt-4.1-mini
index:
type: string
description: >-
Knowledge base to search for context (use 'Zero-Knowledge'
for direct AI responses)
example: my-knowledge-base
smltp_policy:
type: string
description: Security policy to apply
example: internal
prompt:
type: string
description: The user's message/prompt
example: What is the company's policy on remote work?
temperature:
type: number
format: float
minimum: 0
maximum: 2
default: 0.7
description: >-
Controls randomness in the response (0 = deterministic, 2 =
very random)
example: 0.7
max_tokens:
type: integer
minimum: 1
maximum: 4000
default: 1000
description: Maximum number of tokens in the response
example: 1000
stream:
type: boolean
default: false
description: Whether to stream the response
example: false
conversation_id:
type: string
description: Optional conversation ID for tracking
example: conv-123
system_message:
type: string
description: Optional custom system message
example: You are a helpful assistant.
use_rag:
type: boolean
default: true
description: Whether to use RAG (knowledge base retrieval)
example: true
user_id:
type: string
description: >-
MongoDB ObjectId of the user to bill for this request. If
not provided, the API key owner will be billed
example: 60a7c8f5e8b4f5001f7a8c23
example:
model: openai/gpt-4.1-mini
index: my-knowledge-base
smltp_policy: internal
prompt: What is the company's policy on remote work?
temperature: 0.7
max_tokens: 1000
stream: false
conversation_id: conv-123
system_message: You are a helpful assistant.
use_rag: true
user_id: 60a7c8f5e8b4f5001f7a8c23
responses:
'200':
description: Successful chat completion
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
id:
type: string
example: req-abc123
object:
type: string
example: chat.completion
created:
type: integer
example: 1705312200
model:
type: string
example: openai/gpt-4.1-mini
choices:
type: array
items:
type: object
properties:
index:
type: integer
example: 0
message:
type: object
properties:
role:
type: string
example: assistant
content:
type: string
example: Based on the company's remote work policy...
finish_reason:
type: string
example: stop
usage:
type: object
properties:
prompt_tokens:
type: integer
example: 150
completion_tokens:
type: integer
example: 200
total_tokens:
type: integer
example: 350
input_tokens:
type: integer
example: 150
output_tokens:
type: integer
example: 200
metadata:
type: object
properties:
conversation_id:
type: string
example: conv-123
index_used:
type: string
example: my-knowledge-base
smltp_policy_used:
type: string
example: internal
rag_enabled:
type: boolean
example: true
documents_retrieved:
type: integer
example: 3
sources:
type: array
items:
type: object
properties:
source:
type: string
example: remote-work-policy.pdf
score:
type: number
format: float
example: 0.95
example:
success: true
id: req-abc123
object: chat.completion
created: 1705312200
model: openai/gpt-4.1-mini
choices:
- index: 0
message:
role: assistant
content: Based on the company's remote work policy...
finish_reason: stop
usage:
prompt_tokens: 150
completion_tokens: 200
total_tokens: 350
input_tokens: 150
output_tokens: 200
metadata:
conversation_id: conv-123
index_used: my-knowledge-base
smltp_policy_used: internal
rag_enabled: true
documents_retrieved: 3
sources:
- source: remote-work-policy.pdf
score: 0.95
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Access denied (model, index, or policy not allowed)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit or usage limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- ApiKeyAuth: []
components:
schemas:
ErrorResponse:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Invalid API key
message:
type: string
example: The provided API key is invalid or has been revoked
request_id:
type: string
example: req-abc123
description: Request ID for tracking (if available)
RateLimitError:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Rate limit exceeded
message:
type: string
example: Please reduce your request rate
reset_time:
type: string
format: date-time
example: '2024-01-15T11:00:00.000Z'
description: When the rate limit will reset
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
description: |
API key authentication using Bearer token format.
Example: `Authorization: Bearer sk-your-api-key-here`
````