DeepL API を使ってみる


DeepL Proが日本から利用できるようになったのをきっかけとして、DeepL APIを試してみると同時に、DeepLについてまとめてみます。

# DeepLの概要

ディープラーニングを軸とした、言語向けの人工知能システムを開発しているドイツの会社が、2017年夏にリリースした機械翻訳です。
翻訳の精度や、今までになかったような自然な翻訳が魅力です。

DeepLホーム
https://www.deepl.com/home

DeepL会社概要
https://www.deepl.com/publisher.html

## DeepLの無料版とPro版の違いについて

ちょっと翻訳するだけなら、特にProアカウントを登録しなくても翻訳できます。
https://www.deepl.com/translator

ただPro版にすると以下の機能が使えるようになります。
・文字数制限なし
・文書ファイル（.docx,.pptx,.txt）をまるごと翻訳できるようになる[^1]
・データセキュリティ（翻訳する文字列が保護され、不要になったら即削除される）

[^1]: 無料版でも文書ファイルを翻訳できるが、翻訳語のファイルを編集できず、「編集したい場合はDeepL Proを使ってね」、的な文言が入る

簡単に書くと、無料版は制限付き、Pro版だと制限が解放された状態になっています。

## Pro版の種類
Pro版と一言に言えども、複数の種類があります。

- 個人向け　(Starter/Advanced/Ultimate)
- チーム向け(Starter/Advanced/Ultimate)
- 開発者向け(DeepL API)

### 個人向け/チーム向け
個人向け・チーム向けの違いは、1人で使うかチームで使うかの違いだけだと思われます。

また、Starter/Advanced/Ultimateの違いは、翻訳支援ツールとの連携の有無と、文書翻訳の制限数の違いで費用が変わってくる点です。

費用に関しては、ユーザー一人当たり以下

| 期間           |        Starter |      Advanced |      Ultimate |
|:---------------|---------------:|--------------:|--------------:|
| 年払い         |           750円 |       2,500円 |       5,000円 |
| 月払い         |         1,200円 |       3,800円 |       7,500円 |
| 無料体験期間   | 30日無料体験期間あり | 30日無料体験期間あり | 無料体験期間なし |

今はStarterとAdvancedなら30日間無料試用期間があるのでとりあえず触ってみるのもありでしょう。
（ただし無料でもクレジットカード情報の登録は必要でした）

### 開発者向け

そして開発者向けというのが、APIを使うためのプランです。

開発者向けのプランを契約すると、APIが使えるようになります。
これは **月に630円＋従量課金** となります。
翻訳数の制限はないですが、利用分だけ課金されます。
翻訳済みのテキスト1,000,000文字あたり2,500円 で計算されるようです。
（ちなみに、さっきアカウントを確認したところ、5,571文字使用していて ¥13.93 と出ていました）

翻訳数の上限は設定できます。



このプランはUltimateと同様に試用期間がありません。
また、開発者プランでは通常の翻訳はできないため、通常の翻訳もしたい場合は個人/チームの契約を別にする必要があります。


#### DeepL API Free プラン (2021/07/08 Update)
いつの間にか **DeepL API Free** という無料のプランが追加されています。

- 1ヶ月あたり500,000文字の上限あり
- 法人向けレベルのデータセキュリティなし

というプランなので、取り扱うテキストやファイルの内容には注意が必要ですが、とりあえず開発に着手したい、試してみたい、という試用期間的な扱いで使用する場合にはこのプランで良さそうです。

ただし、通常のPro版の試用期間と同様、無料でもアカウントの登録にはクレジットカードの登録が必要です。



## DeepLのAPIを使えるようにする
さて、実際にAPIを使えるようにしていきます。

### 1.開発者向けのアカウントを登録
姓名メールアドレスやパスワード、住所などを入力し、登録します。

### 2.登録完了したら、ログインしてアカウントを確認
入力されている内容に間違いないか念の為確認します。

### 3.認証キーを取得
アカウントを確認するのと同じ画面に、「DeepL APIで使用する認証キー」欄があるので認証キーを取得します。



これで準備が整いました。

なお、アカウント画面では、上限設定、利用状況、契約と支払い情報、請求先情報、登録解除のメニューや、プランと請求書も確認できます。



## API仕様

REST APIなのでシンプルに実装できます。
詳細は技術仕様書で確認します。

API技術仕様書
https://www.deepl.com/docs-api/introduction/

シミュレータ
https://www.deepl.com/docs-api/simulator/

ちなみにシミュレータでの翻訳も文字数カウントされてました。


ここから後は、実際にAPIを試していきます。
基本的には、APIは私の手元ではPostmanで実行していますが
動かすだけならシミュレータでも試すことができますし、
API技術仕様書にはcurlやHTTP Requestの例が載っているので参考にしてください。

また、APIにはオプションも用意されていますが、この投稿では最低限で動かすようにしています。



#### 無料版のAPIについて (2021/07/08 Update)

もともとある翻訳量やデータセキュリティがかからないなどの制限以外は有料版と違わないようですが、リクエストするサブドメインが異なります。

ですので、プランをアップグレードした際などは注意が必要です。
ちなみに無料版でもシミュレータでの翻訳で文字数がカウントされます。

| プラン | ドメイン　|
|------|------|
| 有料版 | api.deepl.com |
| 無料版 | api-free.deepl.com |



なお、API技術資料ですが、ログインしている場合は強制的にログインしているプランに合ったコードしか表示されません。
タブを選択しようとしても選択できない状態になっているので、もし有料版と無料版を比較したい場合はログアウトした状態であれば確認できます。


## シンプルなAPIを試す

### GET
#### リクエスト
https://api.deepl.com/v2/translate?auth_key={認証キー}&text={翻訳したい文字列}&target_lang={翻訳したい言語の指定}



| パラメータ名       |       説明 |    備考    |
|:-----------------|:------------------|:------------------|
| auth_key         | 認証キー             | 先ほど取得した認証キー。GETアクセスだと丸見えなので注意 |
| text             | 翻訳したい文字列      |  |
| target_lang      | 翻訳したい言語の指定  | "DE" - German / "EN" - English / "FR" - French / "IT" - Italian / "JA" - Japanese / "ES" - Spanish / "NL" - Dutch / "PL" - Polish / "PT" - Portuguese (all Portuguese varieties mixed) / "RU" - Russian / "ZH" - Chinese  |

※最低限のパラメータのみ記載。全パラメータは[技術仕様参照](https://www.deepl.com/docs-api/translating-text/)

なおGETアクセスの場合、auth_keyがurlから丸見えなので要注意です。

#### 返り値
```
{
    "translations": [
        {
            "detected_source_language": "{認識した翻訳元文字列の言語}",
            "text": "{翻訳結果}"
        }
    ]
}
```


### POST

#### リクエスト
https://api.deepl.com/v2/translate
Content-Type: application/x-www-form-urlencoded

bodyに指定するものはGETと同じです。
auth_key={認証キー}&text={翻訳したい文字列}&target_lang={翻訳したい言語の指定}

#### 返り値
GETと同じです。


## ファイルの翻訳を試す

APIでもファイルを翻訳できます。
しかも.docx,.pptx,.txtだけでなく.htm/.htmlも翻訳できます。
1ファイルが10MBもしくは1.000.000文字が制限となっています。


現在のところ、ドキュメントタイトルが「[Translating documents (beta)](https://www.deepl.com/docs-api/translating-documents/)」なので、まだbetaの扱いのようです。


### 手順

ファイルの翻訳は3つの手順があります。

1. 翻訳したいファイルをアップロード
2. アップロード状況を確認する（省略可）
3. 翻訳されたファイルをダウンロード

これらはファイル関連の各APIで実行できます。

### 1.翻訳したいファイルをアップロード

#### リクエスト
POST
https://api.deepl.com/v2/document
Content-Type: multipart/form-data

| パラメータ名       |       説明 |    備考    |
|:-----------------|:------------------|:------------------|
| auth_key         | 認証キー             | 認証キー |
| file             | 翻訳したいファイル      |  |
| target_lang      | 翻訳したい言語の指定  | テキスト翻訳と同様 |

※最低限のパラメータのみ記載。全パラメータは[技術仕様参照](https://www.deepl.com/docs-api/translating-documents/)

#### 返り値

```
{
    "document_id": "{ドキュメントID}",
    "document_key": "{ドキュメントキー}"
}
```

### 2.アップロード状況を確認する
#### リクエスト
POST
https://api.deepl.com/v2/document/{ドキュメントID}
Content-Type: application/x-www-form-urlencoded
※ドキュメントIDはアップロードの返り値で取得できる

| パラメータ名       |       説明 |    備考    |
|:-----------------|:------------------|:------------------|
| auth_key         | 認証キー             | 認証キー |
| document_key      | ドキュメントキー  | アップロードの返り値で取得できる |

#### 返り値
実際に試せていないため、ドキュメントから転記。

```
{
	"document_id": "[documentId] ",
	"status":"translating",
	"seconds_remaining": 22
}
```


### 3.翻訳されたファイルをダウンロード
#### リクエスト
POST
https://api.deepl.com/v2/document/{ドキュメントID}/result
Content-Type: application/x-www-form-urlencoded
※ドキュメントIDはアップロードの返り値で取得できる

| パラメータ名       |       説明 |    備考    |
|:-----------------|:------------------|:------------------|
| auth_key         | 認証キー             | 認証キー |
| document_key      | ドキュメントキー  | アップロードの返り値で取得できる |


#### 返り値
ファイルそのものが返ってくる。

## DeepLのその他の使い方

APIなしでも、GET的には使えるようです。


日本語の「翻訳」を英語に翻訳する
https://www.deepl.com/ja/translator#ja/en/%E7%BF%BB%E8%A8%B3
英語の「translation」を日本語に翻訳する
https://www.deepl.com/ja/translator#en/ja/translation