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

Conversions API

概要: 文書ファイルをテキストに変換するAPIです。非同期処理でレイアウト情報やメタデータと共に構造化されたテキストデータを取得できます。

POST /v1/api/conversions​

アップロードファイルを非同期でテキストに変換します。

処理はジョブとして非同期に実行されます。 ページ数を指定した場合はfrom_page〜to_pageを対象に変換を実施します。

ジョブ結果を確認するための変換ID(conversion_id)を返します。

ヒント

スペースIDはスペース作成のタイミング以外でも、URLから確認できます。

URLから、スペースID確認できます
URLから、スペースID確認できます
POST /v1/api/conversions

Headers​

  • api-key : string(required) - rokadoc APIキー

Request Example​

curl -X 'POST' \
'https://api.rokadoc.ntt.com/v1/api/conversions' \
-H "api-key: ${ROKADOC_API_KEY}" \
-F 'upload_file=@sample.pdf' \
-F "space_id=${SPACE_ID}" \
-F 'from_page=1' \
-F 'to_page=1' \
-F 'vllm_name=vllm_router_openai' \
-F 'vllm_prompt=詳細に説明してください' \
-F 'layout_algo_names=miner_layout_text_line' \
-F 'layout_algo_names=com_layout_only' \
-F 'layout_algo_names=com_layout_text_line' \
-F 'image_tag=false' \
-F 'contextual_retrieval=false'

Request Body (multipart/form-data)​

必須パラメータ​
  • upload_file : file(required) - 対象のファイルを指定します
    • 対応フォーマット: .pdf .docx .doc .ppt .pptx .xlsx .xls .png .jpeg .jpg
オプショナルパラメータ
  • space_id : string(optional) - スペース機能を利用する場合はスペースIDを指定
  • from_page : integer(optional) - 開始ページ数
  • to_page : integer(optional) - 終了ページ数
  • is_overwrite : boolean(optional) - 同名ファイルの既存ジョブを削除して上書きする場合はTrueを指定 (デフォルト: false)。同名ファイルにPending/Running中のジョブが存在する場合はエラーとなります
  • vllm_prompt : string(optional) - ドキュメント上の画像をテキスト化する際のカスタムプロンプト。指定しない場合デフォルトプロンプトが利用されます
  • vllm_name : string(optional) - vllmで利用するAI名 (デフォルト: vllm_router_openai)
  • layout_algo_names : array(optional) - どのレイアウト解析ツールを使用するかを指定(複数指定も可)
    • 推奨の構成: ["com_layout_only", "com_layout_text_line", "miner_layout_text_line"]
  • image_tag : boolean(optional) - イメージをタグとして出力する場合はTrueを指定 (デフォルト: false)
  • contextual_retrieval : boolean(optional) - 各チャンクに前後文脈を付与する場合はTrueを指定 (デフォルト: false)
  • knowledge_ids : array(optional) - 独自知識のIDリスト。VLLM等に事前知識を与える際に使用

ドキュメント変換速度改善方法​

ヒント

ドキュメント変換を高速化したい場合は、画像のキャプション生成を無効にすることで、変換速度の改善が見込めます。
指定した場合、キャプション生成されていた領域は、通常のテキストとして処理されます。
また、ページ数が多い場合、変換するページ数を指定することでも改善が見込めます。

画像のキャプション生成を無効にするオプション

  • vllm_prompt : 設定不要
  • vllm_name : nullを設定

画像のページを指定するオプション

  • from_page : integer(optional) - 開始ページ数
  • to_page : integer(optional) - 終了ページ数

画像のキャプション生成を無効にする場合の最小サンプル
ページを指定する場合は追加で、from_pageとto_pageを設定してください。

curl -X 'POST' \
'https://api.rokadoc.ntt.com/v1/api/conversions' \
-H "api-key: ${ROKADOC_API_KEY}" \
-F 'upload_file=@sample.pdf' \
-F 'vllm_name=null' \
-F 'layout_algo_names=miner_layout_text_line' \
-F 'layout_algo_names=com_layout_only' \
-F 'layout_algo_names=com_layout_text_line'

Response​

202 Accepted - ジョブ受付完了​
{
    "code": 202,
    "status": "Pending", 
    "conversion_id": "xxxx"
}
  • code : integer - ステータスコード
  • status : string - ジョブのステータス
  • conversion_id : string - 変換ID。ジョブ結果を確認するために使用
422 Validation Error​
{
  "detail": [
    {
      "type": "enum",
      "loc": [
        "body",
        "layout_algo_names",
        0
      ],
      "msg": "Input should be 'cloud_layout_all', 'miner_layout_text_line', 'com_layout_only' or 'com_layout_text_line'",
      "input": "[\"miner_layout_text_line,com_layout_only,com_layout_text_line\"]",
      "ctx": {
        "expected": "'cloud_layout_all', 'miner_layout_text_line', 'com_layout_only' or 'com_layout_text_line'"
      }
    }
  ]
}

注意事項​

  • ファイルサイズや処理時間に制限があります
  • 非同期処理のため、結果はステータス確認APIで取得してください
  • 変換IDを使用してジョブの進行状況を確認できます