OCR API 連携:Python および Node のコード例
ここでの OCR API 連携とは、OCR エンジンの後に 1 つの HTTP 呼び出しを追加することを意味します。生テキストを送信し、クリーンなテキストを取得します。エンドポイントは OpenAI 互換なので、2 つの設定を変更するだけで、おそらくすでに持っている SDK が動作します。
更新日:

主要ポイント
- Base URL を https://api.llmocrapi.com/v1 に設定し、モデル ID に uncensored を使用し、キーを Bearer トークンとして送信してください。
- API はテキストのみを受け付けます。まず OCR エンジンを実行し、その出力をユーザーメッセージとして渡してください。
- JSON モードは機械可読な結果を返し、最大 8 個のワーカーによる小さなスレッドプールがバッチを高速に保ちます。
- 429 応答は失敗ではなく、待機してリトライするシグナルです。失敗したリクエストは課金されません。
パイプライン内での呼び出しの位置
典型的なドキュメントフローには 4 つのステップがあります。スキャナやスマートフォンのカメラが画像を生成し、OCR エンジンが画像を生テキストに変換し、クリーンアップステップがそのテキストを修復し、アプリケーションが結果を保存または検索します。ここで説明する API は 3 番目のステップです。画像を一切見ず、画像入力もありません。これは元のスキャンのプライバシーを気にする場合に機能であり、テキストのみがマシンから離れ、画像を処理する単一エンドポイントを期待していた場合は制限となります。
プロンプトはトレーニングには使用されません。ただし、タスクに必要なもののみを送信してください。クリーンアップがそれらに依存しない場合は、呼び出しの前にアカウント番号や名前を削除してください。
コードを書く前に、API キーを取得してください。新規ユーザーはサインアップ後にそのページでワンクリックで $0.50 の無料トライアルクレジットを取得でき、これは以下のすべての例を何度も実行するのに十分です。トライアルキーは同時 2 リクエスト、1 分あたり 60 リクエストを許可し、フルキーは 8 と 300 を許可します。
必要な設定
| 設定 | 内容 |
|---|---|
| ベース URL | https://api.llmocrapi.com/v1 |
| エンドポイント | POST /v1/chat/completions |
| モデル ID | uncensored |
| 認証ヘッダー | Authorization: Bearer YOUR_KEY |
| コンテキスト長 | 100,000 トークン(プロンプトと補完を含む) |
キーを環境変数に保存し、ソース管理にはコミットしないでください。例では LLMOCR_API_KEY を読み取ります。
開始する前に 2 つの実用的なメモがあります。フロントエンドコードにはキーを含めないでください。ブラウザに配信されたものはユーザーが読み取れるためです。API はサーバーまたはワーカーから呼び出してください。また、生の OCR テキストとクリーンなテキストをどこに保存するかを早期に決定してください。クリーンな出力は検索、インデックス作成、表示するためのファイルであり、修正が問われた場合に備えて生のテキストは証拠として残す必要があるためです。
curlによる最初のリクエスト
curl で始めて、SDK が隠す前のリクエストの構造を確認できます。以下のサンプルは、典型的な破損した OCR の断片です:改行でハイフンが分断されている、文字が数字と混同されている、余分なページ番号が含まれています。
curl https://api.llmocrapi.com/v1/chat/completions \
-H "Authorization: Bearer $LLMOCR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"temperature": 0,
"messages": [
{"role": "system", "content": "You repair raw OCR text. Fix broken words, rejoin hyphenated line breaks, remove page numbers. Return only the corrected text."},
{"role": "user", "content": "The inven-\ntory was com1leted on Tuesday.\n\n- 14 -\n\nA second ship-\nment arrived."}
]
}'
レスポンスは標準的なチャット completion の形式に従います。クリーンなテキストは choices[0].message.content にあり、usage は呼び出しのプロンプトおよび completion トークンを報告します。クリーンアップには temperature を 0 に設定してください。クリエイティブな変化ではなく、同じ入力で同じ出力を得る必要があります。
OpenAI SDKを使用したPython
pip install openai で SDK をインストールします。コンストラクタのみが標準的な OpenAI 設定と異なります。
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.llmocrapi.com/v1",
api_key=os.environ["LLMOCR_API_KEY"],
max_retries=4,
)
SYSTEM = (
"You repair raw OCR text. Fix broken words, rejoin hyphenated line breaks, "
"remove page numbers and running headers. Do not add or remove facts. "
"Return only the corrected text."
)
def clean(raw: str) -> str:
resp = client.chat.completions.create(
model="uncensored",
temperature=0,
messages=[
{"role": "system", "content": SYSTEM},
{"role": "user", "content": raw},
],
)
return resp.choices[0].message.content
print(clean("The inven-\ntory was com1leted on Tuesday."))
max_retries 引数は、バックオフ付きで接続エラーと 429 応答に対して SDK にリトライを指示し、軽度の使用にはループを自分で書く必要がありません。
Node.js の例
npm install openaiとESモジュールを使用する場合、同じ呼び出しは以下のようになります。
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.llmocrapi.com/v1",
apiKey: process.env.LLMOCR_API_KEY,
});
export async function clean(raw) {
const resp = await client.chat.completions.create({
model: "uncensored",
temperature: 0,
messages: [
{ role: "system", content: "Repair raw OCR text. Return only the corrected text." },
{ role: "user", content: raw },
],
});
return resp.choices[0].message.content;
}
console.log(await clean("A second ship-\nment arrived."));
OpenAI チャット形式に準拠するものは、ノーコードの自動化ツールや既存の内部ラッパーでも、同じ2つの設定を使用できます。ドキュメント にはサポートされているすべてのパラメータが記載されています。
JSON モードによる構造化出力
アーカイブには自由なテキストで問題ありませんが、データ抽出パイプラインにはフィールドが必要です。response_format で JSON モードを有効にし、プロンプトで必要な形状を記述してください。設定と指示の両方で JSON を要求すると、最も信頼性の高い結果が得られます。
import json
resp = client.chat.completions.create(
model="uncensored",
temperature=0,
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": (
"Clean the OCR text of a receipt and answer in JSON with keys "
"'vendor' (string), 'date' (YYYY-MM-DD or null), 'total' (number or null), "
"'cleaned_text' (string)."
)},
{"role": "user", "content": raw_receipt_text},
],
)
data = json.loads(resp.choices[0].message.content)
常に json.loads を try ブロックで囲み、生のテキストを保持してください。非常に長くまたは切り捨てられた応答でも無効な JSON を生成する可能性があるためです。解析に失敗した場合は、1 回リトライしてからページを手動レビュー用にキューに入れます。
バッチの並列処理
1回に1つのリクエストでは、数千ページには遅すぎます。フルキーは8つの同時リクエストを許容するため、6〜8つのワーカーのプールを使用すれば制限内に収まります。同じキーが他の用途でも使用される場合は、少し余裕を持たせてください。
from concurrent.futures import ThreadPoolExecutor
pages = [open(f"ocr/page_{i:04d}.txt").read() for i in range(1, 501)]
with ThreadPoolExecutor(max_workers=6) as pool:
cleaned = list(pool.map(clean, pages))
for i, text in enumerate(cleaned, start=1):
open(f"clean/page_{i:04d}.txt", "w").write(text)
制限を超えた場合、API は HTTP 429 を返します。エラーコード rate_limited は 1 分あたりのリクエストが多すぎること、concurrency は同時に多すぎることを示します。Retry-After: 5 ヘッダー付きの 429 は一時的な過負荷を意味し、5 秒待機してください。ストリーミングリクエストはストリームが終了するまで同時実行数の枠を保持するため、読み取りを停止したストリームは閉じてください。
長時間の実行中はX-Balance-USDレスポンスヘッダーを確認してください。残高が低くなったら、ジョブが途中で失敗するのを防ぐため、価格ページからチャージしてください。
長文書と出力の確認
実際の OCR 出力は、きれいな 1 ページであることはめったにありません。スキャンされた本は数千ページを生み出し、損傷は不均一です:きれいな章の次に、文字が壊れた汚れのあるページがあります。クリーンアップステップを予測可能に保つためのいくつかの習慣があります。
文字数ではなく構造で分割します。ページ区切りや段落の境界で切り取り、モデルがチャンクの開始時に文の半分を受け取らないようにします。文がページ境界をまたぐ場合は、前のページの最後の段落を読み取り専用コンテキストとして含め、モデルに現在のページのみを返すように指示します。これにより、リクエストごとに数少ない追加の入力トークンが必要になりますが、100 万トークンあたり $0.15 ではほぼ無視できる金額であり、2 つのページにまたがるハイフン付きの単語を修正します。
結果を受け入れる前に、低コストのチェックでそれぞれ検証してください。クリーンなテキストの長さをソースと比較してください:比率が1から遠すぎる場合は、モデルが内容を削除または捏造したことを意味します。数値を比較してください:両方のバージョンからすべての数字のシーケンスを抽出し、日付、金額、識別子は見逃すのが最もコストがかかるため、それらが異なるページをフラグ付けしてください。クリーンなテキストの横に生のOCRを保持し、人が常にエンジンが実際に何を見たかを再構築できるようにします。
最後に、最初のランをパイロットとして扱ってください。20 ページをクリーンにし、そのうち 10 ページを自分で読み、システムプロンプトを調整します。通常、指示に対する 2、3 回の編集ラウンドは、パラメータの変更よりも品質に大きな影響を与えます。
よくあるミス
- 非常に大きなページを一度にまとめて送信する。 ウィンドウは100,000トークンで、最大のリクエストボディは8 MBですが、ページサイズのチャンクの方が精度が高く、失敗したチャンクの再実行コストは低くなります。
- モデルに書き換えさせること。 プロンプトに事実を追加または削除しないよう指示がない場合、損傷した箇所を滑らかにする可能性があります。指示を明確にし、長さを比較してください:ソースよりもはるかに短いクリーンなページは要チェックです。
- 間違ったモデル名を使用すること。 唯一のモデル ID は
uncensoredです。GET /v1/modelsでモデルをリストできます。 - 埋め込みまたは画像入力を期待すること。 この API には存在しません。クリーンなテキストの検索には、別の埋め込みツールを使用してください。
- リクエスト ID をログに記録し忘れること。 各応答には
X-Request-Idヘッダーが含まれます。サポートが悪結果を追跡できるように、ページの隣に保存してください。
コンテンツルールはシンプルです:モデルは成人による合法的な利用に対して拒否なしで回答するようにチューニングされており、未成年者を含む性的コンテンツは常に禁止されています。特定のケースに関する質問は サポート へご連絡ください。
その他のガイド
質問と回答
特別な SDK が必要ですか?
いいえ。Base URL を https://api.llmocrapi.com/v1 に設定し、モデル ID に uncensored を使用し、Bearer キーを送信すれば、任意の OpenAI SDK または HTTP クライアントが動作します。
画像や PDF を直接送信できますか?
いいえ。API はテキストのみを受け付けます。まず OCR エンジンを実行し、その出力をメッセージコンテンツとして送信してください。
同時に何件のリクエストを実行できますか?
フルキーは同時8リクエスト、1分あたり300リクエストまで許可されます。トライアルキーは同時2リクエスト、1分あたり60リクエストまでです。
レート制限に達するとどうなりますか?
rate_limited または concurrency のコードで HTTP 429 が返されます。待機してリトライしてください。失敗したリクエストは課金されません。
キーはフォーム 1 つで手に入ります
アカウントを作成し、キーをコピーし、Base URLを変更します。これでセットアップは完了です。