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

API経由でrokadocを利用する

本ページではrokadocをAPI経由で利用する方法について説明します。
APIを利用することで、文書変換からRAGまでの一連の処理を自動化し、任意のアプリケーションと接続できます。

前提
  1. 本応用ガイドではHTTPクライアントとしてcurlコマンドを利用します。もしご利用の環境でcurlコマンドが使えない場合は、任意のHTTPクライアントを利用してください。
  2. 変換対象のPDFファイルを用意してください。
  3. APIキーを発行していることが前提です。APIキーの発行方法はAPIリファレンスのAPIキーをご覧ください。
このページとAPIリファレンスの違い

本ページ（API応用ガイド）は 使い方の流れ を順に解説します。各エンドポイントのパラメータやレスポンスの詳細仕様は APIリファレンス を参照してください。

1. ファイルを変換APIでアップロードする​

rokadocの変換機能をAPI経由で利用できます。以下ではcurlコマンドを使ってPDFファイルをアップロードし、変換ジョブを開始します。

ROKADOC_API_KEY="YOUR_API_KEY" # 発行したAPIキー

curl -X 'POST' \
'https://api.rokadoc.ntt.com/v1/api/conversions' \
-H "api-key: $ROKADOC_API_KEY" \
-F 'upload_file=@sample.pdf'

正常にリクエストが完了すると以下のようなレスポンスが返ってきます。

{
    "code": 202,
    "status": "Pending",
    "conversion_id": "your_conversion_id_here"
}

conversion_idは後のステップ（ステータス確認・結果取得）で必要になるため保存してください。

アップロード先について

今回のようにスペース(space_id)を指定しない場合、個人スペースにアップロードされます。

2. 変換ステータスを確認する​

変換は非同期で実行されるため、ステータス確認APIで処理状況を監視します。

CONVERSION_ID="your_conversion_id_here" # 1.で取得したconversion_id

curl -X 'GET' \
"https://api.rokadoc.ntt.com/v1/user/conversions/${CONVERSION_ID}/status" \
-H "api-key: $ROKADOC_API_KEY" \
-H 'accept: application/json'

処理中の場合は以下のようなレスポンスが返ってきます：

{
    "code": 200,
    "data": {
        "status": "Running",
        "conversion_id": "your_conversion_id_here",
        "document_name": "sample.pdf"
    }
}

statusが"Succeeded"になるまで定期的に確認してください。

3. 変換結果を取得する​

変換が完了したら、結果を取得します。

curl -X 'GET' \
"https://api.rokadoc.ntt.com/v1/user/conversions/${CONVERSION_ID}/document" \
-H "api-key: $ROKADOC_API_KEY" \
-H 'accept: application/json'

正常に完了すると、変換されたテキストデータとレイアウト情報を含む詳細な結果が返ってきます：

{
  "code": 200,
  "data": {
    "status": "Succeeded",
    "conversion_id": "your_conversion_id_here",
    "document_name": "sample.pdf",
    "roka_response": {
      "meta": {
        "separate_method": "page"
      },
      "document_summary": "",
      "units": [
        {
          "unit": 1,
          "title": "",
          "body": "",
          "chunk_context": "",
          "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
        }
      ]
    }
  }
}

主なフィールドの意味は以下のとおりです。抽出したテキストを取り出したいだけの場合は、units[].elements[].text（要素ごとのテキスト）または units[].description（まとまり単位の全文）を参照してください。

フィールド意味
units意味のまとまり（チャンク）の配列
units[].elementsページ内の個別要素（タイトル・本文・表・画像など）の配列
elements[].type要素の種別（title / text / table / image など）
elements[].text要素から抽出したテキスト
elements[].coordinates要素のページ上の座標 [[xmin,ymin],[xmax,ymax]]
units[].descriptionそのまとまりを統合した全文テキスト
document_summary / chunk_context文脈保持（contextual_retrieval）を有効にしたときのみ生成
tips

coordinatesはページ上の要素の位置を示す左上基準の座標情報（[[xmin,ymin],[xmax,ymax]]）です。
widthとheightはPDFのページサイズを示します。

4. RAGで対話的に質問する​

変換したドキュメントに対してRAG（Retrieval-Augmented Generation）を使って質問できます。
メッセージはプレーンテキストでmultipart/form-dataとして送信します。 会話を継続する場合は、前回のレスポンスで返却されたchatlog_idを指定します。

検索の対象範囲

space_idを指定しない場合は個人スペース内のすべてのドキュメントが検索の対象となります。 特定の conversion_id を指定する必要はありません（ステップ1〜3で取得した conversion_id は、ステータス確認・変換結果取得に使うものです）。

ROKADOC_API_KEY="YOUR_API_KEY" # 発行したAPIキー

curl -X POST \
"https://api.rokadoc.ntt.com/v1/api/rag" \
-H "api-key: $ROKADOC_API_KEY" \
-F "message=このドキュメントの概要を3点で教えてください"  # ← アップロードした内容に合わせて変更してください

RAGの結果として、関連する文書の検索結果と共にLLMによる回答が返ってきます：

{
  "assistant_message_id": "xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "user_message_id": "xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "chatlog_id": "xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "search_result": [
    {
      "context": "<チャンク化されたテキスト>",
      "unit": {
        "unit": 1,
        "title": "",
        "body": "",
        "chunk_context": "",
        "elements": [
          {
            "type": "title",
            "coordinates": [[305.0,254.0],[802.0,343.0]],
            "text": "<ここにタイトルが入ります>",
            "page": 1,
            "reading_order": 1
          }
        ],
        "description": "<elementsが統合されたチャンク化される前の全量テキスト>",
        "width": 2481,
        "height": 3508
      },
      "pdf_name": "sample.pdf",
      "page_number": 1,
      "roka_algorithm": null,
      "conversion_id": "xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "user_id": "xxxxxxxxxxxx",
      "tags": []
    }
  ],
  "chat_response": "<ここにAIの回答が入ります>",
  "chat_request": "[指示]\n以下の関連情報に沿って質問に対して回答してください。\n\n[関連情報]\n<検索されたチャンク>\n\n[質問]\n<ユーザーの質問>\n\n",
  "highlight_elements": [
    {
      "type": null,
      "coordinates": [
        [
          0.0,
          0.0
        ],
        [
          0.0,
          0.0
        ]
      ],
      "text": "",
      "page": 1,
      "reading_order": 0,
      "element_id": "xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx__1__0",
      "chat_message_id": "xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "conversion_id": "xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "pdf_name": "sample.pdf",
      "page_width": 2484,
      "page_height": 3509,
      "score": 2.4173874855041504
    },
    {
      "type": "table",
      "coordinates": [
        [
          311.54559326171875,
          2175.313232421875
        ],
        [
          2174.080322265625,
          3138.05810546875
        ]
      ],
      "text": "<該当elementに含まれるテキスト>",
      "page": 1,
      "reading_order": 4,
      "element_id": "xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx__1__4",
      "chat_message_id": "xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "conversion_id": "xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "pdf_name": "sample.pdf",
      "page_width": 2484,
      "page_height": 3509,
      "score": 2.4173874855041504
    }
  ]
}

まとめ​

以上がrokadocを使った文書変換からRAGまでの一連のAPI利用方法です。

API仕様の詳細についてはAPIリファレンスを参照ください。