# 第2章　APIとは何か（言語サービスの文脈で）

> **ナビゲーション**
>
> * 前の章: [第1章　言語サービスとは何か](/ja/solutions/part1-vision/ch01-language-services.md)
> * 次の章: [第3章　言語サービスAPIの分類軸](/ja/solutions/part2-taxonomy/ch03-taxonomy.md)

***

![第2章：APIとは何か（言語サービスの文脈で）— 言語サービスAPIの基礎概念と通信プロセスの完全図解](/files/oVFVauWHYP0JsSDbNnYv)

***

## 2.1 APIを「言語サービスの窓口」として理解する

### APIとは何か——レストランの例え

**API（Application Programming Interface）** という言葉は、聞いたことはあっても「よくわからない」という方が多いでしょう。まずは日常的な例えから始めましょう。

レストランに行ったとき、あなたは厨房に直接入って料理を作りません。代わりに **メニューを見て注文し、ウェイターを通じて厨房に注文が伝わり、料理が届きます**。

APIはまさにこのウェイターの役割です。

![APIとは、1日あたり数万件にのぼる翻訳を自動化し、あらゆるシステムを連携させる「言語サービスの窓口」である](/files/O0rC9h062xVWJ12wEeao)

* **メニュー** = APIドキュメント（何をどう頼めるか）
* **注文** = APIリクエスト（あなたのアプリが送るデータ）
* **料理** = APIレスポンス（返ってくる結果）

![内部の仕組み（厨房）を知らなくても、API（ウェイター）に頼めば結果（料理）が届く](/files/HiOk9aOO7Qa0Vw1SBtnC)

あなたは厨房の仕組みを知らなくていい。ただメニューに従って注文すればいい——これがAPIの本質です。

### 言語サービスAPIの具体的なイメージ

**DeepL API** を例に取りましょう。DeepLは高品質なニューラル機械翻訳を提供するサービスです。DeepL APIを使えば、あなたのアプリから「この英語テキストを日本語に翻訳して」と依頼し、翻訳結果を受け取ることができます。

DeepLのエンジン内部がどう動いているかを理解する必要は一切ありません。APIという窓口を通じて、翻訳機能を「借りて使う」だけです。

![複雑なニューラル機械翻訳エンジンを、自社アプリから「借りて使う」ことができる](/files/6Q6jFVei72b0u7vNs61y)

### なぜAPIが重要なのか

| 観点       | 説明                                   |
| -------- | ------------------------------------ |
| **スケール** | 1日1件の手動翻訳依頼ではなく、1日数万件単位の自動翻訳が可能になる   |
| **自動化**  | 人間の操作なしに、翻訳をワークフローに組み込める             |
| **統合**   | ECサイト・CRM・CMS・チャットボットなど、他のシステムと連携できる |
| **標準化**  | 複数のベンダーを同じ方法で呼び出せるため、切り替えや比較が容易      |

![APIは「スケール・自動化・統合・標準化」の4つの次元で業務を劇的に変革する](/files/al2vZobRubsmlUMCGHyW)

***

## 2.2 リクエストとレスポンス——注文と納品のアナロジー

### HTTPリクエスト/レスポンスの基本

言語サービスAPIのほとんどは **HTTP（HyperText Transfer Protocol）** を使って通信します。HTTPはWebブラウザとサーバーが会話するための共通言語で、私たちがWebサイトを見るときにも使われています。

APIの通信は大きく2ステップです：

1. **リクエスト（Request）**: あなたのアプリがAPIサーバーにデータを送る
2. **レスポンス（Response）**: APIサーバーが結果を返す

データのフォーマットとしては **JSON（JavaScript Object Notation）** が広く使われています。JSONは人間にも読みやすいテキスト形式で、キーと値のペアでデータを表現します。

![APIの通信は、HTTPを用いた「リクエスト」と「レスポンス」の2ステップで完結する](/files/y8dAFkNn8WtAGMEpLEse)

### 言語サービスAPIのリクエスト例

DeepL APIにテキスト翻訳をリクエストする例を示します。

```http
POST https://api-free.deepl.com/v2/translate
Authorization: DeepL-Auth-Key [あなたのAPIキー]
Content-Type: application/json

{
  "text": ["Hello, world!"],
  "source_lang": "EN",
  "target_lang": "JA"
}
```

各フィールドの意味：

* `text`: 翻訳したいテキストの配列（複数まとめて送ることも可能）
* `source_lang`: 入力言語（EN = 英語）
* `target_lang`: 出力言語（JA = 日本語）

![リクエストは、人間にも読みやすいJSON形式で「翻訳対象テキスト」と「言語」を指定する](/files/zCPLEHWZYlHeoOaXBBKh)

### レスポンスの読み方

上記のリクエストに対して、APIは以下のようなレスポンスを返します。

```json
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "こんにちは、世界！"
    }
  ]
}
```

レスポンスの構造：

* `translations`: 翻訳結果の配列（リクエストで複数テキストを送った場合、対応する順番で返ってくる）
* `detected_source_language`: APIが検出した入力言語（`source_lang` を省略した場合に有用）
* `text`: 翻訳されたテキスト本体

エラーが発生した場合は、HTTPステータスコードとともにエラー情報が返ります：

```json
{
  "message": "Wrong endpoint. Use v2 API endpoints."
}
```

> **よくあるHTTPステータスコード**
>
> * `200 OK`: 成功
> * `400 Bad Request`: リクエストの形式が不正
> * `403 Forbidden`: 認証失敗（APIキーが間違いなど）
> * `429 Too Many Requests`: リクエスト数の上限を超えた（レート制限）
> * `500 Internal Server Error`: サーバー側のエラー

![レスポンスには翻訳結果が返り、通信状態はステータスコードで瞬時に判別できる](/files/thZhEIVBbq2NulKp43a1)

***

## 2.3 同期・非同期・ストリーミング——速さと規模のトレードオフ

APIのリクエスト/レスポンスの方式には3つの主要なパターンがあります。それぞれ異なるトレードオフがあり、ユースケースに応じて使い分ける必要があります。

![処理の「速さ」と「規模」に応じて、3つの通信方式を使い分ける必要がある](/files/uheRGCMHuJtqIQy8X8Uq)

### 同期API（Synchronous API）

**仕組み**: リクエストを送ったら、処理が完了するまで待ち、その場で結果を受け取る。

```
アプリ → [リクエスト送信] → APIサーバー
アプリ ←  [結果を即返却]  ← APIサーバー
（通常ミリ秒〜数秒以内）
```

**適したユースケース**:

* 短文テキストの翻訳（1〜数百文字程度）
* 単語の言語検出
* チャットボットのリアルタイム返答翻訳

**特徴**:

* シンプルで実装が簡単
* レスポンスタイムが長い処理や大量データには不向き
* タイムアウトのリスクがある（処理が長引くと接続が切れることも）

![リクエスト後その場で待機し、即座に結果を受け取る「同期API」は、短文翻訳に最適である](/files/AGDMcFQdl3dWxRtZefb4)

### 非同期API（Asynchronous API）

**仕組み**: リクエストを送ると「ジョブID」が即座に返ってくる。処理は裏で進行し、後から別リクエストで結果を取りに行く（ポーリング）か、処理完了時にコールバック通知を受ける。

```
アプリ → [ジョブ投入リクエスト] → APIサーバー
アプリ ←  [ジョブID: "job_abc123"]  ← APIサーバー（即返却）

（しばらく後に…）

アプリ → [結果取得リクエスト: job_abc123] → APIサーバー
アプリ ←  [翻訳完了テキスト]  ← APIサーバー
```

非同期リクエストの例（ドキュメント翻訳の投入）:

```json
POST /v1/document
{
  "file": "[PDFファイルの内容]",
  "source_lang": "EN",
  "target_lang": "JA"
}
```

レスポンス（即時返却）:

```json
{
  "document_id": "doc_xyz789",
  "document_key": "secret_key_for_retrieval",
  "status": "queued"
}
```

**適したユースケース**:

* 大容量ドキュメントの翻訳（PDF・Word・PowerPointなど）
* 大量テキストの一括翻訳バッチ処理
* 音声ファイルの文字起こし

![巨大なファイルは、ジョブを投げて後から結果を取りに行く「非同期API」で処理する](/files/RDJ5a2kqYMPh1nqOH0cN)

### ストリーミング（Streaming）

**仕組み**: サーバーが処理結果を少しずつリアルタイムで流し続ける。処理の完了を待たずに、生成された部分から受け取ることができる。

```
アプリ → [ストリーミングリクエスト] → APIサーバー
アプリ ←  「こんに」 ← APIサーバー（部分的に即流す）
アプリ ←  「ちは」
アプリ ←  「、世界」
アプリ ←  「！」
アプリ ←  [ストリーム終了]
```

**適したユースケース**:

* 同時通訳・リアルタイム通訳の支援
* LLM（大規模言語モデル）による翻訳や校正のライブ表示
* 長文生成をユーザーに段階的に見せたい場合

![ライブ翻訳などでは、完了を待たずに生成された部分から「ストリーミング」でリアルタイムに受け取る](/files/nUFTFgkboE8rxh5ljcoZ)

### 3方式の比較表

| 方式          | 結果受け取り      | 実装難度 | 適した処理量   | 代表ユースケース       |
| ----------- | ----------- | ---- | -------- | -------------- |
| **同期**      | 即時          | 簡単   | 小〜中      | 短文翻訳、言語検出      |
| **非同期**     | 後から取得       | 中程度  | 中〜大      | ドキュメント翻訳、バッチ処理 |
| **ストリーミング** | リアルタイムに少しずつ | やや複雑 | 小〜中（継続的） | 同時通訳、LLM翻訳     |

![処理量と受け取り方の特性を理解し、システムの要件に最適なAPI方式を選択する](/files/SKobYx2CLa52jmgiEmjm)

***

> **まとめ**
>
> * APIはレストランのウェイターのように、あなたのアプリとサービスの仕組みを仲介する窓口
> * リクエスト（注文）にはJSONで「何を・どの言語に」を指定し、レスポンス（料理）として翻訳テキストが返ってくる
> * 同期・非同期・ストリーミングの3方式はそれぞれ速さと規模のトレードオフがあり、ユースケースに応じて選択する

![APIの基本概念を理解したら、次は自社の要件に合わせたAPIの選定に進む](/files/EyEYSi7Km5Ij1QtcZ3ME)

***

> 次の章: [第3章　言語サービスAPIの分類軸](/ja/solutions/part2-taxonomy/ch03-taxonomy.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://translationlab.gitbook.io/ja/solutions/part1-vision/ch02-what-is-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.