メインコンテンツまでスキップ

Conversion Document API

概要: 完了した文書変換ジョブの結果を取得するAPIです。構造化されたテキストデータとレイアウト情報、座標データを含む詳細な解析結果を返却します。

GET /v1/user/conversions/{conversion_id}/document​

ジョブの実行結果を返却します。

まだ完了していない場合は、status が Pending で roka_response が null のレスポンスが返ります。

GET /v1/user/conversions/{conversion_id}/document

Headers​

  • api-key : string(required) - rokadoc APIキー
必須パラメータ​
  • conversion_id : string(required) - 変換ID（パスパラメータ）
オプショナルパラメータ
  • space_id : string(optional) - スペース機能を利用する場合はスペースIDを指定

Request Example​

curl -X 'GET' \
"https://api.rokadoc.ntt.com/v1/user/conversions/${CONVERSION_ID}/document?space_id=${SPACE_ID}" \
-H "api-key: ${ROKADOC_API_KEY}"

Response​

200 OK - ジョブの実行結果​
{
    "code": 200,
    "data": {
        "status": "Succeeded",
        "conversion_id": "your_conversion_id_here",
        "document_name": "sample.pdf",
        "roka_response": {
          "meta": {
            "separate_method": "page"
          },
          "document_summary": "<contextual_retrievalを要求した場合に、ドキュメント全体の概要が入ります>",
          "units": [
            {
              "unit": 1,
              "title": "",
              "body": "",
              "chunk_context": "<contextual_retrievalを要求した場合に、ページの要約が入ります>",
              "elements": [
                {
                  "type": "title",
                  "coordinates": [[305.0, 254.0], [802.0, 343.0]],
                  "text": "<ここにタイトルが入ります>",
                  "page": 1,
                  "reading_order": 1
                },
                {
                  "type": "text",
                  "coordinates": [[303.0, 522.0], [2044.0, 593.0]],
                  "text": "<ここにテキストが入ります>",
                  "page": 1,
                  "reading_order": 2
                }
              ],
              "description": "<elementsが統合された全量テキスト>",
              "width": 2481,
              "height": 3508
            }
          ]
        }
    }
}
  • code : integer - ステータスコード
  • data.status : string - ジョブのステータス
  • data.conversion_id : string - 変換ID
  • data.document_name : string - ドキュメント名
  • data.roka_response : object - rokadocによるドキュメント解析結果
    • meta : object - ドキュメント解析時のメタ情報
      • separate_method : string - 分割方法（現在はpageのみ）
    • document_summary : string - contextual_retrievalを要求した場合、ドキュメント全体の概要が設定され、要求しない場合は空文字が設定される
    • units : array - ページもしくは文節単位のユニット情報
      • unit : integer - 1から始まるユニット番号
      • title : string - elementsに集約したため、現在不使用
      • body : string - elementsに集約したため、現在不使用
      • chunk_context : string - contextual_retrievalを要求した場合、ユニット全体の簡潔な説明文が設定され、要求しない場合は空文字が設定される
      • elements : array - ドキュメントに含まれるレイアウト情報
        • type : string - 要素のタイプ（title, text, table, image）
        • coordinates : array - 要素の左上基準の座標情報 [[x1, y1], [x2, y2]]形式
        • text : string - 抽出したテキスト
        • page : integer - 要素が存在するページ番号
        • reading_order : integer - 1から始まる読み順
      • description : string - RAG用途を想定したユニット全体の説明文
      • width : integer - PDFを画像化したときのページの幅
      • height : integer - PDFを画像化したときのページの高さ
200 OK - 非同期で実行されているジョブの結果待ち​

ジョブが完了していない場合も HTTP 200 が返ります。status で実行状況を判定してください。

{
  "code": 200,
  "data": {
    "status": "Pending",
    "conversion_id": "xxxx",
    "document_name": "sample.pdf",
    "roka_response": null
  }
}
404 Not Found - 変換IDが存在しない​

指定した conversion_id が存在しない、または自身（または所属スペース）に紐付かない場合に返ります。

{
  "error": {
    "code": 404,
    "message": "Not Found",
    "details": "リソースが見つかりませんでした。"
  }
}

注意事項​

  • ジョブが完了していない場合も HTTP 200 が返り、data.status が Pending / data.roka_response が null になります
  • 変換IDが存在しない場合は404エラーが返されます
  • 自身のUserIDに関連しない変換結果は取得できません
  • スペース機能を利用している場合は適切なspace_idを指定してください