> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldbase.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# はじめに

> シームレスなドキュメントアップロード、強力なセマンティック検索、効率的な会話管理のために設計された API ワークフローを探索する

## ようこそ

Shieldbase AI API ドキュメントへようこそ。私たちの API は、ドキュメントのシームレスなアップロード、高度なセマンティック検索の実行、動的な会話の管理を行える、直感的なエンドポイントを提供します。これらの強力な機能を効果的に活用するための主要な 2 つのワークフローを以下で紹介します。

### 認証

開始する前に、すべての API リクエストに次の 3 つのヘッダーを含める必要があります。これらのヘッダーは、システムへのアクセスを認証・認可するためにすべてのリクエストで必須です。

* **client-id**: 一意のクライアント識別子。
* **private-key**: API 呼び出しの認証に使用するプライベートキー。
* **secret**: 追加のセキュリティ層を提供するシークレットキー。

<Note>
  `client-id`、`private-key`、`secret` を取得するには、
  [https://app.sbai.cloud/](https://app.sbai.cloud/) にアクセスしてアカウントにサインインするか、
  [support@shieldbase.ai](mailto:support@shieldbase.ai) までメールでお問い合わせください。これらの認証情報が揃ったら、認証付きリクエストの送信を開始できます。
</Note>

これらのヘッダーは、API に送信するすべてのリクエストに含める必要があります。

***

## Models API

`GET /external/models` エンドポイント経由で、セマンティック検索や会話管理などのタスクで利用可能なモデルを取得します。レスポンスは、参照しやすいように `label` と `value` を持つモデルの配列を返します。

### エンドポイント

**GET** `/external/models`

### ヘッダー

認証のために、リクエストに次のヘッダーを必ず含めてください。

* **client-id**: 一意のクライアント識別子。
* **private-key**: API 呼び出しの認証に使用するプライベートキー。
* **secret**: 追加のセキュリティを提供するシークレットキー。

### レスポンス

リクエストが成功すると、レスポンスには利用可能なモデルの配列が含まれます。各モデルは次のプロパティを持つオブジェクトとして表されます。

* **label**: モデルの人間が読める名前。
* **value**: モデルの識別子。使用するモデルを指定する際に使います。

### レスポンス例

```json theme={null}
[
  {
    "label": "GPT-3.5",
    "value": "gpt-3.5"
  },
  {
    "label": "GPT4o",
    "value": "gpt4o"
  }
]
```

***

### ワークフロー 1: アップロードとセマンティック検索

このワークフローでは、ドキュメントをアップロードし、アップロード済みのファイルに対してセマンティック検索を行えます。2 段階のプロセスです。まずドキュメントをアップロードし、次にセマンティック検索エンドポイントで関連コンテンツを取得します。

#### ステップ 1: ドキュメントのアップロード

<Card title="ドキュメントのアップロード" icon="file" href="/jp/api-reference/endpoint/public/upload-document">
  最初に、ドキュメントアップロード API エンドポイントを使って 1 つ以上のドキュメントをアップロードします。これがプロセスの最初のステップで、ファイルを `multipart/form-data` リクエストの一部として送信する必要があります。`client-id`、`private-key`、`secret` などの必須ヘッダーを必ず含めてください。
</Card>

ドキュメントを 1 つまたは複数アップロードするには、`PUT /external/upload` エンドポイントを使用します。これにより、さまざまな形式のファイルをアップロードできます。ファイルはフォームデータ内にバイナリデータとして含める必要があり、サーバーが処理することでセマンティック検索などの機能が利用できるようになります。アップロードが成功すると、サーバーから確認メッセージが返されます。

#### ステップ 2: セマンティック検索の実行

<Card title="セマンティック検索" icon="magnifying-glass" href="/jp/api-reference/endpoint/public/search-index">
  ドキュメントをアップロードした後は、キーワードやコンテキストを使ってセマンティックにドキュメントとその内容を取得できます。私たちのセマンティック検索エンドポイントは、コンテンツと類似性に基づいてドキュメントを検索し、より簡単かつ効率的な取得を可能にします。
</Card>

ドキュメントのアップロードが完了したら、`POST /external/semantic-search` エンドポイントを使用して、指定したキーワードやクエリに基づいてコンテンツを取得できます。必要に応じてコンテキスト ID を指定することで、検索範囲を絞り込むこともできます。このエンドポイントは、最も関連性の高いドキュメントを返し、必要な情報に簡単にアクセスできるようにします。

***

### ワークフロー 2: 会話管理

会話管理 API では、プログラムから会話を開始、継続、管理できます。会話のフローは、新しい会話の開始、それに対するメッセージの送信、必要に応じた会話の継続、という流れで進みます。

#### ステップ 1: 新しい会話の開始

<Card title="会話の開始" icon="comments" href="/jp/api-reference/endpoint/public/start-conversation-public">
  会話 API に最初のメッセージを送信して、新しい会話を開始します。このエンドポイントは、会話を追跡するために使われる新しい会話 ID を作成します。
</Card>

新しい会話を開始するには、`POST /external/start-conversation` エンドポイントを使用します。会話を始めたいメッセージを指定する必要があります。サーバーは `conversation_id` と `model` のほか、メッセージ、ner カウント、タイムスタンプなどの初回会話の詳細を返します。

### Start Conversation のレスポンス例

```json theme={null}
{
  "conversation_id": "<string>",
  "title": "<string>",
  "messages": {
    "id": "<string>",
    "text": "<string>",
    "redacted": "<string>",
    "synthetic": "<string>",
    "ner_count": 123,
    "response": "<string>",
    "ner_items": [],
    "timestamp": "2023-11-07T05:31:56Z"
  }
}
```

#### ステップ 2: 会話にメッセージを送信

<Card title="メッセージの送信" icon="paper-plane" href="/jp/api-reference/endpoint/public/send-conversation-public">
  会話が開始されたら、追加のメッセージを送信して対話を続けられます。これにより、新しい情報で会話を拡張できます。
</Card>

対話を続けるには、`POST /external/send` エンドポイントを使用します。`start-conversation` エンドポイントから受け取った `conversation_id` と、新しいメッセージをリクエストボディに含めてください。これにより、各メッセージが正しく会話に紐づけられ、会話のフローが保たれます。

### Send Conversation のレスポンス例

```json theme={null}
{
  "conversation_id": "<string>",
  "sender": "ai | sender",
  "message_text": "<string>",
  "redacted_text": "<string>",
  "syntactic_text": "<string>",
  "model": "gpt-4o",
  "related_questions": ["<string>"],
  "id": "<string>",
  "typing_completed": true,
  "created_at": "2023-11-07T05:31:56Z"
}
```

#### ステップ 3: 会話を継続

<Card title="会話の継続" icon="arrow-right" href="/jp/api-reference/endpoint/public/continue-conversation-public">
  このエンドポイントは、既存の会話に新しい応答を追加して継続するために使います。これにより、会話を時間とともに発展させられます。
</Card>

さらに会話を拡張したい場合は、`POST /external/continue` エンドポイントを使用し、`conversation_id` と `model`、その他必要な情報を提供して会話を続けます。`continue-conversation` を呼び出した後は、同じ会話コンテキスト内で新しいメッセージを送るために `send-conversation` エンドポイントに戻ることができます。

### Continue Conversation のレスポンス例

```json theme={null}
{
  "conversation_id": "d0c73687-cc8d-4628-be2d-01050d32dfb6",
  "sender": "user",
  "message_text": "<string>",
  "redacted_text": "<string>",
  "syntactic_text": "<string>",
  "typing_completed": true,
  "created_at": "2024-08-16T09:24:07.865867",
  "ner_items": [],
  "ner_count": 123,
  "title": "Dropbox: A Popular File Sharing Service",
  "id": "ac3ca0a0-69ee-49c3-a6a5-86ee9b9f4c0e"
}
```