公開 API

API ドキュメント

SotaOCR を AI エージェントや LLM パイプラインに組み込めます。API は非同期で動作します。ドキュメントをアップロードし、ジョブ状態をポーリングして、最後に結果や OCR bbox と同じ座標系のページプレビュー画像を取得します。

ベース URL

公開 OCR エンドポイントはすべてこのホストから提供されます。

https://sotaocr.com

認証

すべての API リクエストには Bearer トークンが必要です。API キーはダッシュボードで作成できます。

ヘッダー

Authorization: Bearer YOUR_API_KEY

利用可能なルート

OCR サービスは API ルートを提供します: /v1/balance、/v1/extract、/v1/jobs/{job_id}、/v1/jobs/{job_id}/result、/v1/jobs/{job_id}/result.html、/v1/jobs/{job_id}/result.docx、/v1/jobs/{job_id}/pages/{page_number}/preview。model_profile を送る前に GET /api/v1/info の model_profiles を読んでください。HTML と DOCX の再構成エクスポートは現在 FAST モデルのジョブのみ対応しています。

OCR 前処理

メイン OCR の前に、サービスはページの向きを自動検出して回転し、必要な場合のみ document unwarping を適用します。検出された角度は doc_preprocessor_res.angle に入り、preview エンドポイントは OCR bbox と同じ座標系の正確なページ画像を返します。

ポーリングと準備状態

API の確認は 1 秒に 1 回までにしてください。OCR が終わるまでは、GET /v1/jobs/{job_id}/result は result_not_ready を持つ 202 Accepted を返します。

Pro OCR

Pro モデルが有効な場合は、より高品質な OCR を使うために /v1/extract へ model_profile=pro を送信します。Pro OCR は処理したドキュメント 1 ページごとに 2 scan pages を消費します。

cURL · Pro リクエスト

curl -X POST https://sotaocr.com/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F 'page_ranges=[{"start":1,"end":5}]' \
  -F "model_profile=pro"

JSON · レスポンス

{
  "id": "job_123456789",
  "account_id": "acct_123456789",
  "status": "pending",
  "page_count": 5,
  "pages_completed": 0,
  "model_profile": "pro",
  "upstream_job_id": "up_job_987654321",
  "created_at": "2026-03-24T12:00:00Z",
  "updated_at": "2026-03-24T12:00:00Z"
}

GET

ページ残高を確認

/v1/balance 認証済みアカウントの現在の scan page 残高を返します。まだ処理できるページ数の判断には remaining_pages または total_affordable_pages を使用します。

cURL · リクエスト

curl -X GET https://sotaocr.com/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON · レスポンス

{
  "entity_code": "scan_page",
  "remaining_pages": 63,
  "total_affordable_pages": 63,
  "monthly_pages": {"total": 40, "allocated": 5, "remaining": 35},
  "lifetime_pages": {"total": 20, "allocated": 2, "remaining": 18},
  "tokens": {"total": 120, "allocated": 20, "remaining": 100, "affordable_pages": 10},
  "token_price": 10
}

POST

1. ドキュメントをアップロード

/v1/extract OCR 用に PDF または画像をアップロードします。成功時には account_id、upstream_job_id、created_at、updated_at を含むジョブ情報とともに 202 Accepted を返します。

file: ドキュメントファイル (PDF, PNG, JPG)。
page_ranges: (任意) ページ範囲の配列を表す JSON 文字列。例: '[{"start":1,"end":3}]'
model_profile: 任意の OCR モデルプロファイル。省略するとサービス既定値を使います。指定する場合は GET /api/v1/info の model_profiles に含まれる値を送ってください。

cURL · リクエスト

curl -X POST https://sotaocr.com/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F 'page_ranges=[{"start":1,"end":5}]'

JSON · レスポンス

{
  "id": "job_123456789",
  "account_id": "acct_123456789",
  "status": "pending",
  "page_count": 5,
  "pages_completed": 0,
  "model_profile": "fast",
  "upstream_job_id": "up_job_987654321",
  "created_at": "2026-03-24T12:00:00Z",
  "updated_at": "2026-03-24T12:00:00Z"
}

GET

2. ステータスを確認

/v1/jobs/{job_id} 現在の処理状態を 200 OK で返し、account_id、upstream_job_id、page_count、pages_completed、created_at、updated_at も含みます。

cURL · リクエスト

curl -X GET https://sotaocr.com/v1/jobs/job_123456789 \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON · レスポンス

{
  "id": "job_123456789",
  "account_id": "acct_123456789",
  "status": "completed",
  "page_count": 5,
  "pages_completed": 5,
  "upstream_job_id": "up_job_987654321",
  "created_at": "2026-03-24T12:00:00Z",
  "updated_at": "2026-03-24T12:00:08Z"
}

GET

3. 結果を取得

/v1/jobs/{job_id}/result?format=markdown ジョブが completed のときは抽出結果を 200 OK で返します。format=json の場合、各ページには angle を含む doc_preprocessor_res と bbox 座標空間の page_preview メタデータが含まれることがあります。format=html は JSON エンベロープ内に再構成 HTML を返し、現在は FAST のみです。画像を埋め込んだ単体 HTML ファイルには /result.html を使ってください。完了前は result_not_ready を持つ 202 Accepted を返します。

format: (任意) レスポンス形式: json、markdown、text、html。既定は json。html は現在 FAST のみです。

cURL · リクエスト

curl -X GET "https://sotaocr.com/v1/jobs/job_123456789/result?format=markdown" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON · レスポンス

{
  "job_id": "job_123456789",
  "format": "json",
  "page_count": 1,
  "content": "{\"job_id\":\"job_123456789\",\"page_count\":1,\"pages\":[{\"page_number\":1,\"status\":\"completed\",\"text\":\"Ivan Matveev\",\"doc_preprocessor_res\":{\"angle\":0,\"model_settings\":{\"use_doc_orientation_classify\":true,\"use_doc_unwarping\":false}},\"page_preview\":{\"coordinate_space\":\"doc_preprocessed\",\"content_type\":\"image/png\",\"width\":1192,\"height\":1684},\"raw_result\":{}}]}"
}

GET

4. 単体 HTML を取得

/v1/jobs/{job_id}/result.html FAST と PRO のジョブから data-URI 画像を埋め込んだ text/html 再構成を返します。

cURL · リクエスト

curl -X GET "https://sotaocr.com/v1/jobs/job_123456789/result.html" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output result.html

JSON · レスポンス

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Disposition: inline; filename="job_123456789.html"

(data-URI 画像を埋め込んだ単体 HTML)

GET

5. DOCX 再構成を取得

/v1/jobs/{job_id}/result.docx FAST と PRO のジョブからページ画像と検索可能な OCR テキストを含む .docx 視覚再構成を返します。

cURL · リクエスト

curl -X GET "https://sotaocr.com/v1/jobs/job_123456789/result.docx" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output result.docx

JSON · レスポンス

HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="job_123456789.docx"

(バイナリ DOCX bytes)

GET

6. bbox オーバーレイ用ページ preview を取得

/v1/jobs/{job_id}/pages/{page_number}/preview 自動回転と必要に応じた unwarp の後の PNG ページ画像を返します。OCR bbox の背面に描画すべき正しい画像です。

cURL · リクエスト

curl -X GET https://sotaocr.com/v1/jobs/job_123456789/pages/1/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output page_0001_preview.png

JSON · レスポンス

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: inline; filename="page_0001_preview.png"

(OCR bbox と同じ座標系の PNG バイト列)

API エラー

多くのエラーレスポンスは {"error":{"code":"...","message":"..."}} を使います。insufficient_balance には entity_code、requested_units、available_units も含まれます。

400 不正なリクエスト: 不正な multipart、file の欠落、不正な page_ranges、または不正な PDF です。コード: bad_request。
401 認証失敗: Bearer トークンがないか無効です。コード: unauthorized。
403 禁止: API アクセスが必要、または残高不足です。コード: api_access_required または insufficient_balance。
404 見つかりません: 未知の job_id、または他アカウントのジョブへのアクセスです。コード: job_not_found。
415 未対応メディア: アップロードしたファイル形式は未対応です。コード: unsupported_media。
502 Upstream 利用不可: OCR upstream が利用できないか、ジョブ同期に失敗しました。コード: upstream_unavailable。

連携の準備はできましたか？

ダッシュボードで API キーを作成し、テスト用の無料ページを取得してください。

ダッシュボードを開く API アクセスを取得スキルをダウンロード