# 辞書を用いた書き起こしを開始する このページでは、登録済みの辞書データを用いてmocoVoice APIで効率的な書き起こしを行う方法を説明します。 ## 前提条件 以下の準備が完了していることを前提とします。 * **APIキーの作成:** [APIキーの作成](https://docs.mocomoco.ai/mocovoice/guides/start-transcription#api%E3%82%AD%E3%83%BC%E3%81%AE%E4%BD%9C%E6%88%90)の手順に従って、APIキーが発行済みであること。 * **辞書の登録:** [辞書を登録する](https://docs.mocomoco.ai/mocovoice/guides/regist-dictionary)の手順に従って、辞書が登録済みであること。 ## 音声ファイルのアップロード 音声ファイルのアップロードを開始するには以下のステップを実行します。 1. 音声認識ジョブを作成する 2. アップロード用URLにファイルをアップロード ### 1. 音声認識ジョブを作成する ジョブの作成 API リクエストは、音声ファイルのURLを指定して、mocoVoice API 非同期 HTTP インターフェースのエンドポイントにリクエストを送信します。 `POST https://api.mocomoco.ai/api/v1/transcriptions/upload` 例えば、curl コマンドで、`test.wav` の音声認識のリクエストを送るには以下のようにします。 ```bash curl -X 'POST' \ 'https://api.mocomoco.ai/api/v1/transcriptions/upload' \ -H 'accept: application/json' \ -H 'X-API-KEY: {API_KEY}' \ -H 'Content-Type: application/json' \ -d '{ "filename": "test.wav", "dictionary_id": "{dictionary_id}", "language": "ja" }' ``` ### オプションの説明 以下は、HTTPリクエストで使用されるオプションの説明です。 | パラメータ名 | 型 | 必須 | 説明 | | --- | --- | --- | --- | | `filename` | `string` | 必須 | アップロードする音声ファイルの名前 | | `dictionary_id` | `string` | 任意 | 書き起こし時に使用する辞書ID | | `language` | `string` | 任意 | 音声ファイルの言語コード（`'en'`または`'ja'`） | 対応言語は[FAQの対応言語一覧](https://docs.mocomoco.ai/faq#:~:text=%E3%81%A9%E3%81%AE%E8%A8%80%E8%AA%9E%E3%81%AB%E5%AF%BE%E5%BF%9C%E3%81%97%E3%81%A6%E3%81%84%E3%81%BE%E3%81%99%E3%81%8B%EF%BC%9F)を参照ください。 **成功した場合** 成功時のレスポンスには `transcription_id` が含まれています。 これは、ユーザーの音声認識リクエストに対するジョブの ID で、ジョブの状態を確認したり、結果を得るために利用します。 `audio_upload_url`には、音声をアップロードできるURLになります。 ```json { "transcription_id": "string", "dictionary_id": "string", "team_id": "string", "name": "string", "transcription_path": "string", "audio_path": "string", "transcription_model": "default", "status": "PENDING", "speaking_duration": 0, "created_at": "2024-10-03T01:10:15.403Z", "updated_at": "2024-10-03T01:10:15.403Z", "audio_upload_url": "https://mocovoice..." } ``` ### 2. アップロード用URLにファイルをアップロードする `audio_upload_url` にファイルをアップロードします。認証情報はURLに含まれているため、この段階でAPIキーは不要です。 ```jsx curl -X 'PUT'\ '{audio_upload_url}'\ -H 'Content-Type: audio/wav' \ --upload-file test.wav ``` `Content-Type`は、ファイルに合わせて設定します。例では`audio/wav`を設定しましたが、mp3の場合は、`audio/mpeg`を設定してください。 ## 書き起こしジョブの実行 ファイルがアップロードされたら、手順1で取得した `transcription_id` を用いて書き起こしを実行します。 ここでは、`transcription_id` が `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` であるとします。 ```jsx curl -X 'POST' \ 'https://api.mocomoco.ai/api/v1/transcriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/transcribe' \ -H 'accept: application/json' \ -H 'X-API-KEY: {API_KEY}' \ -d '' ``` *※書き起こしを実行は、1回のみリクエストが可能です。以降のジョブの状態確認は、次の「音声認識ジョブの状態を確認する」セクションをご確認ください。* レスポンス例： ```json { "transcription_id": "string", "dictionary_id": "string", "team_id": "string", "name": "string", "transcription_path": "string", "audio_path": "string", "transcription_model": "default", "status": "IN_PROGRESS", "speaking_duration": 0, "created_at": "2024-10-03T01:15:02.975Z", "updated_at": "2024-10-03T01:15:02.975Z", "audio_upload_url": "null" } ``` ## 音声認識ジョブの状態を確認する 音声認識ジョブ作成リクエストが成功したら、ジョブの状態を確認します。`status` が `completed` または `error` になるまで定期的に確認（ポーリング）してください。 **ジョブの状態取得** ジョブはサーバー側で順次実行されます。 状態の確認や結果の取得には、結果取得用エンドポイント `GET /v1/transcriptions/{transcription_id}` に問い合わせます。 `transcription_id` には、ジョブ作成時に取得したジョブIDを設定します。 リクエストパラメータの認証情報として、`X-API-KEY` ヘッダーにAPIキーを指定してください。 curlで実行する場合は以下のようになります。 ここでは、`transcription_id` が `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` であるとします。 ```bash curl -X 'GET' \ 'https://api.mocomoco.ai/api/v1/transcriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \ -H 'accept: application/json' \ -H 'X-API-KEY: {API_KEY}' ``` **PENDING状態** アップロードリクエスト直後は、`status` は `PENDING` 状態です。 ```json { "transcription_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "dictionary_id": "string", "team_id": "string", "name": "string", "transcription_path": "string", "audio_path": "string", "transcription_model": "default", "status": "PENDING", "speaking_duration": 0, "created_at": "2024-10-03T01:15:02.975Z", "updated_at": "2024-10-03T01:15:02.975Z", "audio_upload_url": "string" } ``` **IN_PROGRESS状態** 実際に音声認識処理が開始されると、`status` は `IN_PROGRESS` 状態に変わります。 ```json { "transcription_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "dictionary_id": "string", "team_id": "string", "name": "string", "transcription_path": "string", "audio_path": "string", "transcription_model": "default", "status": "IN_PROGRESS", "speaking_duration": 0, "created_at": "2024-10-03T01:15:02.975Z", "updated_at": "2024-10-03T01:15:02.975Z", "audio_upload_url": "string" } ``` `IN_PROGRESS` から次の `COMPLETED` 状態になるまでの時間は、音声の長さに依存しますが、通常は音声の長さの0.2〜0.8倍程度です。 mocoVoiceは高速処理を特長としており、これより短い時間で処理が完了する場合があります。 **COMPLETED状態** 音声認識が完了すると、`status` は `COMPLETED` 状態になります。 この時、レスポンスの `transcription_path` で指定された場所から音声認識結果を取得できます。 結果は、音声認識サーバーでの処理完了後、一定期間保存されます。 ```json { "transcription_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "dictionary_id": "string", "team_id": "string", "name": "string", "transcription_path": "string", "audio_path": "string", "transcription_model": "default", "status": "COMPLETED", "speaking_duration": 33.5, "created_at": "2024-10-03T01:15:02.975Z", "updated_at": "2024-10-03T01:15:02.975Z", "audio_upload_url": "string" } ``` **FAILED状態** 何らかの理由で音声認識に失敗した場合、`status` は `FAILED` 状態になります。 ```json { "transcription_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "dictionary_id": "string", "team_id": "string", "name": "string", "transcription_path": "string", "audio_path": "string", "transcription_model": "default", "status": "FAILED", "speaking_duration": 0, "created_at": "2024-10-03T01:15:02.975Z", "updated_at": "2024-10-03T01:15:02.975Z", "audio_upload_url": "string" } ``` ## 書き起こしデータの取得 ジョブの状態が `completed` になったら、レスポンスフィールドの `transcription_path` から書き起こしデータを取得できます。 ```bash curl -X 'GET' \ '{transcription_path}' \ ``` ```json [ {"text": "string", "lang": "string", "start": number, "end": number, "speaker": "SPEAKER_00"}, {"text": "string", "lang": "string", "start": number, "end": number, "speaker": "SPEAKER_01"}, . . . ] ``` ### より詳細な操作については、[こちら](/mocovoice/apis)をご確認ください。