Chat Completion

curl --request POST \
  --url https://secureai.hiperai.ai/api/external/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "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"
}
EOF

import requests

url = "https://secureai.hiperai.ai/api/external/chat/completions"

payload = {
    "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"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
  })
};

fetch('https://secureai.hiperai.ai/api/external/chat/completions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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
      }
    ]
  }
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "Rate limit exceeded",
  "message": "Please reduce your request rate",
  "reset_time": "2024-01-15T11:00:00.000Z"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

POST

chat

completions

Chat Completion

curl --request POST \
  --url https://secureai.hiperai.ai/api/external/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "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"
}
EOF

import requests

url = "https://secureai.hiperai.ai/api/external/chat/completions"

payload = {
    "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"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
  })
};

fetch('https://secureai.hiperai.ai/api/external/chat/completions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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
      }
    ]
  }
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "Rate limit exceeded",
  "message": "Please reduce your request rate",
  "reset_time": "2024-01-15T11:00:00.000Z"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

チャットの完了

オプションのナレッジベース取得 (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 互換エンドポイントを使用してください。このクラシックエンドポイントは、RAG をサポートする唯一のエンドポイントです。

認証

必須: API キー

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 を参照してください。
`temperature`	番号	いいえ	ランダムネス制御 (0 ～ 2、デフォルト: 0.7)。
`max_tokens`	整数	いいえ	最大応答トークン (デフォルト: 1000、上限は 4000)。
`stream`	ブール値	いいえ	応答を SSE としてストリーミングします (デフォルト: `false`)。
`conversation_id`	文字列	いいえ	追跡用のオプションの会話 ID。
`user_id`	文字列	いいえ	このリクエストの請求先となるユーザーの MongoDB ObjectId (管理者ゲート。請求モードを参照)。

リクエストの例

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)

{
  "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[] }` — 冗長性とフェイルオーバーを参照してください。
`smltp`	オブジェクト	SMLTP 資格が通話に対して作成されるときに存在します。 `{ bundle_id, receipt_url }`。 `bundle_id` (権利 ID、例: `jti-…`) は、ネイティブ/直接展開でも返されます。 `receipt_url` の署名付きレシートは、トラフィックが SMLTP ゲートウェイを介してルーティングされる場合にのみ取得できます (それ以外の場合、Receipts は `404` を返します)。
`rag_enabled`	ブール値	RAG が使用されたかどうか。
`documents_retrieved`	整数	取得されたドキュメントの数。
`sources`	配列	最大 3 つの文書ソースを取得 `{ source, score }`。

ストリーミング

サーバー送信イベントを受信するには "stream": true を設定します。各 SSE 行は data: <json> で、ストリームは 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`	ストリームの途中でプロバイダーが中断されました (最初のトークンの後、フェイルオーバーは不可能になります)。

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 不正なリクエスト

{
  "success": false,
  "error": "Invalid messages",
  "message": "a system message is only allowed as the first entry of messages"
}

401 不正

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked"
}

403 禁止

{
  "success": false,
  "error": "Access denied",
  "message": "Model, index, or policy not allowed"
}

429 / 502 — 冗長チェーンが枯渇しました

冗長チェーン内のすべてのモデルに障害が発生すると、応答で各試行が報告されます。すべての障害がレート制限であった場合、ステータスは 429、それ以外の場合は 502 です。

{
  "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 内部サーバーエラー

{
  "success": false,
  "error": "Internal server error",
  "message": "An unexpected error occurred"
}

使用例

JavaScript/Node.js

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);

パイソン

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 です。
モデルの呼び出しやポイントの消費をせずに、すべてのポリシーに対してリクエストを検証するには、ポリシーチェックを使用します。
フェイルオーバーチェーンのセマンティクス (トリガー、タイムアウト、ストリーミング動作、枯渇ステータスコード) については、冗長性とフェイルオーバーを参照してください。

承認

Authorization

string

header

必須

API key authentication using Bearer token format. Example: Authorization: Bearer sk-your-api-key-here

ボディ

application/json

prompt

string

必須

The user's message/prompt

例:

"What is the company's policy on remote work?"

model

string

The AI model to use for completion

例:

"openai/gpt-4.1-mini"

index

string

Knowledge base to search for context (use 'Zero-Knowledge' for direct AI responses)

例:

"my-knowledge-base"

smltp_policy

string

Security policy to apply

例:

"internal"

temperature

number<float>

デフォルト:0.7

Controls randomness in the response (0 = deterministic, 2 = very random)

必須範囲: 0 <= x <= 2

例:

0.7

max_tokens

integer

デフォルト:1000

Maximum number of tokens in the response

必須範囲: 1 <= x <= 4000

例:

1000

stream

boolean

デフォルト:false

Whether to stream the response

例:

false

conversation_id

string

Optional conversation ID for tracking

例:

"conv-123"

system_message

string

Optional custom system message

例:

"You are a helpful assistant."

use_rag

boolean

デフォルト:true

Whether to use RAG (knowledge base retrieval)

例:

true

user_id

string

MongoDB ObjectId of the user to bill for this request. If not provided, the API key owner will be billed

例:

"60a7c8f5e8b4f5001f7a8c23"

レスポンス

Successful chat completion

success

boolean

例:

true

string

例:

"req-abc123"

object

string

例:

"chat.completion"

created

integer

例:

1705312200

model

string

例:

"openai/gpt-4.1-mini"

choices

object[]

Show child attributes

usage

object

Show child attributes

metadata

object

Show child attributes

導入 & セットアップ

モデル & AI 生成

ナレッジベース & RAG

セキュリティ、ガードレール & 監査

ユーザー & アクセス (IAM)

請求、クォータ & Webhook

チャットの完了

チャットの完了

エンドポイント

説明

認証

ヘッダー

リクエスト本文

入力パラメータ

モデルと冗長パラメータ

パラメータの取得と生成

リクエストの例

応答

成功の応答 (200)

メタデータオブジェクト

ストリーミング

エラー応答

400 不正なリクエスト

401 不正

403 禁止

429 / 502 — 冗長チェーンが枯渇しました

500 内部サーバーエラー

使用例

JavaScript/Node.js

パイソン

注意事項

承認

ボディ

レスポンス

​チャットの完了

​エンドポイント

​説明

​認証

​ヘッダー

​リクエスト本文

​入力パラメータ

​モデルと冗長パラメータ

​パラメータの取得と生成

​リクエストの例

​応答

​成功の応答 (200)

​メタデータ オブジェクト

​ストリーミング

​エラー応答

​400 不正なリクエスト

​401 不正

​403 禁止

​429 / 502 — 冗長チェーンが枯渇しました

​500 内部サーバーエラー

​使用例

​JavaScript/Node.js

​パイソン

​注意事項

承認

ボディ

レスポンス

チャットの完了

エンドポイント

説明

認証

ヘッダー

リクエスト本文

入力パラメータ

モデルと冗長パラメータ

パラメータの取得と生成

リクエストの例

応答

成功の応答 (200)

メタデータオブジェクト

ストリーミング

エラー応答

400 不正なリクエスト

401 不正

403 禁止

429 / 502 — 冗長チェーンが枯渇しました

500 内部サーバーエラー

使用例

JavaScript/Node.js

パイソン

注意事項