変更履歴版数修正日修正箇所修正内容 /10/19 初版 /2/ 処理受付 ID 保有数の上限値を記載処理受付 ID 保有数が上限値の場合のレスポンスコードを 400 へ変更 /4/ 暗号化プロトコルのサポートについて記載

Size: px

Start display at page:

Download "変更履歴版数修正日修正箇所修正内容 /10/19 初版 /2/ 処理受付 ID 保有数の上限値を記載処理受付 ID 保有数が上限値の場合のレスポンスコードを 400 へ変更 /4/ 暗号化プロトコルのサポートについて記載"

ときあいしま
5 years ago
Views:

1 感情認識 API リファレンス第 1.3 版 2018 年 8 月 2 日富士通株式会社 1 / 25

2 変更履歴版数修正日修正箇所修正内容 /10/19 初版 /2/ 処理受付 ID 保有数の上限値を記載処理受付 ID 保有数が上限値の場合のレスポンスコードを 400 へ変更 /4/ 暗号化プロトコルのサポートについて記載 /8/ ステータスコードの追記エラーメッセージの修正 2 / 25

3 はじめに本書の目的本書は Zinrai プラットフォームサービスが提供する API について説明しています本書の対象読者本書は Zinrai プラットフォームサービスでアプリケーションやサービスを開発運用する方を対象に記述します本書を読むためには以下の知識が必要ですインターネットに関する基本的な知識使用するオペレーティングシステムに関する基本的な知識 WebAPI に関する基本的な知識お願い本書で使用している画面イメージ実行例などは最新環境のものとは異なることがあります本書は予告に変更されることがあります本書を無断で他に転用しないようお願いします本書に記載されたデータの使用に起因する第三者の特許権およびその他の権利の侵害については当社はその責を負いません輸出管理規制について本ドキュメントを輸出または第三者へ提供する場合はお客様が居住する国および米国輸出管理関連法規等の規制をご確認のうえ必要な手続きをおとりください登録商標について本書に記載されている会社名および製品名はそれぞれ各社の商標または登録商標である場合がありますなお本書では会社名および製品名に付記される登録表示 ((TM) または (R)) は省略しています 3 / 25

4 目次第 1 章 API 概要基本利用方法 API 一覧... 6 第 2 章共通仕様エンドポイントプロトコル文字コード HTTP ヘッダ HTTP ステータスコードエラー形式共通ヘッダ関連のエラー第 3 章 API 詳細感情認識リクエストレスポンス実行例感情認識処理状態取得リクエストレスポンス実行例感情認識処理キャンセルリクエストレスポンス実行例感情認識処理受付 ID 一覧取得リクエストレスポンス実行例感情認識処理結果削除リクエストレスポンス実行例感情認識モデル一覧取得リクエストレスポンス / 25

5 3.6.3 実行例付録 A パラメータ仕様 / 25

6 第 1 章 API 概要感情認識ではお客様が入力した会話データの感情を分析します 1.1 基本利用方法本 API の基本的な利用方法は以下の通りです 1. 感情認識 API により指定したフォーマットに従って会話データを基に感情 ( 満足不満足 ) の結果を得ることが出来ます 1.2 API 一覧提供する API 一覧は以下の通りです概要 URI メソッド参照感情認識 /EmotionRecognition/v1/recognitions POST 3.1 感情認識処理状態取得 /EmotionRecognition/v1/recognitions/{a GET 3.2 ct_id} 感情認識処理キャンセル /EmotionRecognition/v1/recognitions/{a POST 3.3 ct_id}/cancel 感情認識処理受付 ID 一覧 /EmotionRecognition/v1/recognitions GET 3.4 取得感情認識処理結果削除 /EmotionRecognition/v1/recognitions/{a DELETE 3.5 ct_id} 感情認識モデル一覧取得 /EmotionRecognition/v1/models GET / 25

7 第 2 章共通仕様本章では本 API の共通仕様を説明します 2.1 エンドポイント zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com 2.2 プロトコル HTTPS 暗号化プロトコルは TLS1.2 のみサポートしています 2.3 文字コード UTF HTTP ヘッダヘッダ項目名値値の説明 X-Access-Token 例 : 5f744f66-56d9-4c8c-87b2-c8 70f3b82817 本サービスでは K5 の API 認証を利用したアクセス制限を行っております API 利用者は本サービスの API をコールする前に K5 認証よりアクセストークンを取得し本ヘッダの値にアクセストークンを設定して API をコールしてくださいアクセストークンの取得方法等についてはこちらのリファレンスをご参照ください X-Service-Code サービスコード [10 桁 ] - API 番号 [5 桁 ] 例 : FJAI K5 PaaS Portal で各サービスに割り振られたコード (10 桁 ) と各サービスの各 API が持つ固有の番号 (5 桁 ) をハイフンで繋ぎ合わせた文字列です実際の値は第 3 章 API 詳細のリクエストヘッダ仕様をご参照ください 7 / 25

8 2.5 HTTP ステータスコードステータスコード意味説明 200 OK リクエストは正常に処理されました 201 Created リクエストは正常に処理され新規リソースが作成されました 202 Accepted リクエストを正常に受け付けました 400 Bad Request リクエストの内容に誤りがあります 401 Unauthorized 認証に失敗しました 404 Not Found リソースが見つからなかった 408 Request Timeout リクエストタイムアウトが発生しました再度 API の実行をお願いします 415 Unsupported Media Type リクエストヘッダの Content-Type がサポート対象外です 500 Internal Server サーバ内部にエラーが発生しました Error 503 Service サービスを一時的に利用できません Unavailable 予期しないエラーが発生しました 2.6 エラー形式 JSON で以下の情報を返しますただし一部のエラーコードは HTML 形式で返却されます名前説明 error エラー情報のオブジェクト code エラーコード title エラータイトル ( 英語 ) message エラーメッセージ ( 英語 ) レスポンス例 JSON 形式 { "error": { "message": "audio file does not exist. ", "code": 400, "title": "BAD_REQUEST" } } 8 / 25

9 HTML 形式 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" " <html> <head> <title>glassfish Server Open Source Edition Error report</title> <style type="text/css"></style> </head> <body> <h1>http Status Unsupported Media Type</h1> <hr/> <p><b>type</b> Status report</p> <p><b>message</b>unsupported Media Type</p> <p><b>description</b>the server refused this request because the request entity is in a format not supported by the requested resource for the requested method (Unsupported Media Type).</p> <hr/> <h3>glassfish Server Open Source Edition 3.1</h3> </body> </html> 9 / 25

10 2.6.1 共通ヘッダ関連のエラーコードタイトルメッセージ 400 Bad Request You have requested incorrect parameters. (XXXXXXXX) 上記のエラーが返却された場合以下を確認してくださいリクエストに X-Access-Token ヘッダが無い X-Access-Token ヘッダの値が正しくないリクエストに X-Service-Code ヘッダが無い X-Service-Code ヘッダの値のフォーマットが正しくないコードタイトルメッセージ 401 Unauthorized This server could not verify your authorization to access. (XXXXXXXX) 上記のエラーが返却された場合以下を確認してください X-Access-Token ヘッダの値が正しくないコードタイトルメッセージ 404 Not Found We could not find the resource you requested. (XXXXXXXX) 上記のエラーが返却された場合以下を確認してください X-Service-Code ヘッダの値が正しくない HTTP メソッドまたは URL が誤っているコードタイトルメッセージ 500 Internal Server Error The server encountered an internal error. (XXXXXXXX) 上記のエラーが返却された場合以下を確認してください X-Access-Token ヘッダの値が正しくない XXXXXXXX には任意の文字列が入ります 10 / 25

11 第 3 章 API 詳細本章では各 API の詳細仕様を説明しますパラメータの表記については付録 A パラメータ仕様をご参照ください 3.1 感情認識入力された音声データの感情認識処理を受け付けます処理受付 ID 保有数の上限は 100 件です URI HTTP メソッド /EmotionRecognition/v1/recognitions POST リクエストヘッダ名前値補足 X-Service-Code FJAI Content-Type multipart/form-data - パラメータメッセージボディ形式 : フォーム名前説明必須既定値 model_name 使用するモデル名 - 指定がない場合デフォルトのモデルで感情認識処理を行います形式 : ファイル名前説明種別必須既定値 file 音声データ音声データファイル ( 仕様 ) - Content-Type 音声タイプ音声データのタイプを以下のいずれかから指定します audio/wav audio/mulaw - 11 / 25

12 入力音声データ仕様データフォーマット type=audio/wav の場合ファイルフォーマット :WAV 形式 ( リニア PCM) サンプリングレート :8kHz 量子化ビット数 :16bit チャネル : モノラル或いはステレオ ( ステレオの場合 Rch に感情認識対象の音声が入っている必要があります ) type=audio/mulaw の場合ファイルフォーマット :WAV 形式 (G.711 μlaw) サンプリングレート :8kHz 量子化ビット数 :8bit チャネル : モノラル或いはステレオ ( ステレオの場合 Rch に感情認識対象の音声が入っている必要があります ) データ長 40 秒以上 1800 秒 (30 分 ) 以下 ( 長時間の音声データを入力するとレスポンスが遅くなる場合があります ) 入力音声データ条件感情認識対象 ( ステレオの場合 Rch) の音声が以下に該当する場合適切な結果が得られない可能性があります音声レベルが適正ではない場合例 ) 音声レベルが大きく振幅クリップ( 音割れ ) が発生している場合音声レベルが小さい場合 1 人の話者以外の音声が含まれている場合例 ) 2 人以上の話者の会話音声が含まれている場合途中で別の話者の音声が含まれている場合呼出音や保留音等が含まれている場合レスポンスヘッダ名前値補足 Content-Type application/json X-Asynchronous- CallId 任意非同期処理用の ID 12 / 25

13 メッセージボディ形式 :JSON 名前説明型 act_id 処理受付 ID string エラー情報コードタイトルメッセージ 400 BAD_REQUEST audio file does not exist. 音声ファイルがない場合に本メッセージが出力されます 400 BAD_REQUEST audio file content type is unsupported format. 音声タイプが未サポートの場合に本メッセージが出力されます 400 BAD_REQUEST audio file extension is unsupported format. 音声ファイルの拡張子が.wav ではない場合に本メッセージが出力されます 400 BAD_REQUEST audio file is file max size over. 音声ファイルのサイズが上限値を超過している場合に本メッセージが出力されます 400 BAD_REQUEST The number of acceptances is the maximum. 処理受付 ID 保有数上限に達し処理受付ができない場合に本メッセージが出力されます 404 NOT_FOUND user default model does not exist. ユーザ指定のデフォルトモデルがない場合に本メッセージが出力されます 404 NOT_FOUND model name does not exist. 指定されたモデルがない場合に本メッセージが出力されます 503 SERVICE_UNAVAILABLE Service temporarily unavailable. 一時的に処理受付ができない場合に本メッセージが出力されます 13 / 25

14 3.1.3 実行例例 1) モデル名指定で audio/wav タイプの音声データを入力した場合リクエスト curl -X POST " su.com/emotionrecognition/v1/recognitions" -H "X-Access-Token: " -H "X-Service-Code: FJAI " -H "Content-Type: multipart/form-data" -F ;type=audio/wav" レスポンス { "act_id": "000025_ " } 例 2) モデル名指定で audio/wav タイプの音声データを入力した場合リクエスト curl -X POST " su.com/emotionrecognition/v1/recognitions" -H "X-Access-Token: " -H "X-Service-Code: FJAI " -H "Content-Type: multipart/form-data" -F "file=@test.wav ;type=audio/wav" -F "model_name=model1" レスポンス { "act_id": "000025_ " } 3.2 感情認識処理状態取得非同期で実施中の感情認識処理の状態を確認します URI HTTP メソッド /EmotionRecognition/v1/recognitions/{act_id} GET 結果は以下のような構造で返します 14 / 25

15 状態タイムライン [ 配列 ] 秒数 # タイムラインのスコア # 配列満足区間 [ 配列 ] 音声データ感情認識結果開始秒 # 終了秒 # 満足区間の配列不満足区間 [ 配列 ] 開始秒 # 不満足区間の終了秒 # 配列エラー情報エラーコードエラータイトルエラーメッセージリクエストヘッダ名前値補足 X-Service-Code FJAI パラメータ名前説明種別必須既定値 act_id 処理受付 ID path 〇 - メッセージボディレスポンスヘッダ名前値補足 Content-Type application/json メッセージボディ形式 :JSON 名前説明型 15 / 25

16 status timeline satisfy dissatisfy error 処理状態以下の 3 種類 "processing": 処理中 "completed": 完了 "error": エラー発生タイムライン status が "completed" の場合に有効満足区間 status が "completed" の場合に有効不満足区間 status が "completed" の場合に有効エラー情報 status が "error" の場合に有効 string object(timeline) [] object(satisfy) [] object(dissatisfy) [] object(error) timeline 名前説明型 second 秒数 number( 整数 ) score 満足度スコア 0~100 の間の実数値 (0: 不満足 50: 平常 100: 満足 ) number( 浮動小数点 ) satisfy 名前説明型 start 満足区間の開始位置 ( 単位 : 秒 ) number( 浮動小数点 ) end 満足区間の終了位置 ( 単位 : 秒 ) number( 浮動小数点 ) dissatisfy 名前説明型 start 不満足区間の開始位置 ( 単位 : 秒 ) number( 浮動小数点 ) end 不満足区間の終了位置 ( 単位 : 秒 ) number( 浮動小数点 ) error 名前説明型 code エラーコード number( 整数 ) 16 / 25

17 title エラータイトル ( 英語 ) string message エラーメッセージ ( 英語 ) string 以下にエラー発生時の内容の詳細を示しますコードタイトルメッセージ 400 BAD_REQUEST playback time exceeds 30 minutes. 音声ファイルの長さが 30 分を超過している場合に本メッセージが出力されます 400 BAD_REQUEST playback time is less than 40 seconds. 音声ファイルの長さが 40 秒未満である場合に本メッセージが出力されます 400 BAD_REQUEST audio file is unsupported format. 音声ファイルが未サポートである場合に本メッセージが出力されますエラー情報コードタイトルメッセージ 404 NOT_FOUND act_id does not exist. {act_id} が存在しない場合に本メッセージが出力されます実行例リクエスト curl -X GET " nrecognition/v1/recognitions/000025_ " -H "X-Access-Token: " -H "X-Service-Code: FJAI " レスポンス感情認識処理中の場合 { "status": "processing", "timeline": [], "satisfy": [], "dissatisfy": [], "error": {} } 17 / 25

18 感情認識処理完了の場合 { "status": "completed", "timeline": [ {"second": 1, "score": }, :: ( 省略 ) {"second", 41, "score": }, :: ( 省略 ) ], "satisfy": [ {"start": 110.0, "end": }, :: ( 省略 ) ], "dissatisfy": [ {"start": 50.0, "end": 60.0 }, :: ( 省略 ) ], "error": {} } 感情認識処理エラーの場合 { "status": "error", "timeline": [], "satisfy": [], "dissatisfy": [], "error": { "code": 400, "title": "BAD_REQUEST", "message": "audio file is unsupported format." } } 3.3 感情認識処理キャンセル処理中の感情認識処理をキャンセルします URI /EmotionRecognition/v1/recognitions/{act_id}/cancel 18 / 25

19 HTTP メソッド POST リクエストヘッダ名前値補足 X-Service-Code FJAI X-Asynchronous- CallId 3.1 感情認識のレスポンスヘッダの X-Asynchronous-CallId 非同期処理用の ID パラメータ名前説明種別必須既定値 act_id 処理受付 ID path 〇 - メッセージボディキャンセル受付後実際のキャンセル完了まで時間が掛かる場合がありますキャンセル完了後処理受付 ID に関連する一時データは全て削除されますキャンセルを受け付けても感情認識処理完了のタイミングによってはキャンセルできない場合がありますレスポンスヘッダメッセージボディエラー情報コードタイトルメッセージ 404 NOT_FOUND act_id does not exist. {act_id} が存在しない或いは処理中ではない場合に本メッセージが出力されます実行例リクエスト 19 / 25

20 curl -X POST " su.com/emotionrecognition/v1/recognitions/000025_ /cancel" -H "X-Access-Token: " -H "X-Service-Code: FJAI " H "X-Asynchronous-CallId : _ " レスポンス 3.4 感情認識処理受付 ID 一覧取得感情認識処理中の処理受付 ID 一覧を取得します URI HTTP メソッド /EmotionRecognition/v1/recognitions GET リクエストヘッダ名前値補足 X-Service-Code FJAI パラメータメッセージボディレスポンスヘッダ名前値補足 Content-Type application/json メッセージボディ形式 :JSON 名前説明型 20 / 25

21 list 処理受付 ID 一覧 object(list) [] List 名前説明型 act_id 処理受付 ID string エラー情報実行例リクエスト curl -X GET " u.com/emotionrecognition/v1/recognitions" -H "X-Access-Token: " -H "X-Service-Code: FJAI " レスポンス {"list": [ { "act_id", "000025_ " }, :: ( 省略 ) ] } 3.5 感情認識処理結果削除感情認識処理結果を削除します URI HTTP メソッド /EmotionRecognition/v1/recognitions/{act_id} DELETE リクエストヘッダ名前値補足 X-Service-Code FJAI / 25

22 パラメータメッセージボディレスポンスヘッダメッセージボディエラー情報コードタイトルメッセージ 404 NOT_FOUND act_id does not exist. {act_id} が存在しない場合に本メッセージが出力されます 409 CONFLICT act_id is in use. {act_id} が現在処理中である場合に本メッセージが出力されます実行例リクエスト curl -X DELETE " itsu.com/emotionrecognition/v1/recognitions/000025_ " -H "X-Access-Token: " -H "X-Service-Code: FJAI " レスポンス 22 / 25

23 3.6 感情認識モデル一覧取得登録済みの感情認識モデルの一覧を取得します URI HTTP メソッド /EmotionRecognition/v1/models GET リクエストヘッダ名前値補足 X-Service-Code FJAI パラメータメッセージボディレスポンスヘッダ名前値補足 Content-Type application/json メッセージボディ形式 :JSON 名前説明型 model-list 感情認識モデル一覧 ( モデル名 ) string [] エラー情報実行例リクエスト curl -X GET " u.com/emotionrecognition/v1/models" -H "X-Access-Token: " -H "X-Service-Code: FJAI " 23 / 25

24 レスポンス { } "model-list": ["model1", "model2", ] 24 / 25

25 付録 A パラメータ仕様本書では API 毎にパラメータを以下のように種別分けしています種別説明 path URI の中でクエリ文字列以外 ( リソース名など ) で指定する値のみでパラメータ名は記述されない例 :/Sample/v1/samp_file/0001 query URI の中でクエリ文字列で指定する例 :/Sample/v1/samp_file/0001?param1=AAA 本 API におけるリクエスト / レスポンスボディの形式は JSON を基本とします JSON の場合本書では型について以下のように表記します型説明 string ダブルクォーテーションで括った文字列 number 数値 ( 整数浮動小数点数 ) boolean 真偽値 (true と false) array [] 表記配列 object () 内にオブジェクト名表記オブジェクト ( キーと値の組の集まり ) 25 / 25

変更履歴版数修正日修正箇所修正内容 /4/27 初版 /7/27 - クリップボードへのコピーで不要な文字が含まれる事象を修正 /10/ 音声テキスト化非同期処理機能追加最大

変更履歴版数修正日修正箇所修正内容 /4/27 初版 /7/27 - クリップボードへのコピーで不要な文字が含まれる事象を修正 /10/ 音声テキスト化非同期処理機能追加最大音声テキスト化 API リファレンス第 1.5 版 2018 年 8 月 2 日富士通株式会社 1 / 27 変更履歴版数修正日修正箇所修正内容 1.0 2017/4/27 初版 1.1 2017/7/27 - クリップボードへのコピーで不要な文字が含まれる事象を修正 1.2 2017/10/19 1.2 2.5 音声テキスト化非同期処理機能追加 3.2 3.3 3.4 3.5 3.6

変更履歴 版数 修正日 修正箇所 修正内容 /10/19 初版 /2/ 処理受付 ID 保有数の上限値を記載処理受付 ID 保有数が上限値の場合のレスポンスコードを 400 へ変更 /4/ 暗号化プロトコルのサポートについて記載

変更履歴版数修正日修正箇所修正内容 /10/19 初版 /2/ 処理受付 ID 保有数の上限値を記載処理受付 ID 保有数が上限値の場合のレスポンスコードを 400 へ変更 /4/ 暗号化プロトコルのサポートについて記載