画像からテキスト

POST /api/v1/image-to-text

リクエスト

POST で multipart の image に画像を1枚だけ指定し、YOUR_API_KEY と document.png を置き換えます。multipart の境界は cURL に設定させてください。任意の format 以外のクエリや追加フォーム項目・モデル設定は使用できません。認証とキーの保護は認証ガイドをご覧ください。

curl --silent --show-error --include --max-time 150 \
  'https://freeaiocr.com/api/v1/image-to-text' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: example-request-0001' \
  -F 'image=@document.png'

以下の JSON は例です。認識テキストと token 数は画像によって変わります。再試行のルールは冪等性で確認できます。

成功応答（使用量の例）

{
  "request_id": "b2c8ec98-2a36-4f87-99d2-3d7839b92518",
  "text": "# Document title\n\nRecognized paragraph.\n\n| Item | Count |\n| --- | --- |\n| Books | 12 |",
  "usage": {
    "input_tokens": 2000,
    "output_tokens": 4000
  },
  "billing": {
    "currency": "USD",
    "price_version": "2026-10-26-v1",
    "base_usd": "0.002000000",
    "input_overage_usd": "0.000000000",
    "output_overage_usd": "0.002400000",
    "total_usd": "0.004400000"
  }
}

出力形式

任意のクエリは format=json|text|docx の1つだけです。未知のパラメーター、重複や無効な値は認識前に400となります。json（既定）の text は Markdown で、HTML 表や LaTeX を含む場合があります。text は同じ JSON 内の text をプレーンテキストに変換します。docx は result.docx の Word 添付ファイルです。

curl --silent --show-error --include --max-time 150 \
  'https://freeaiocr.com/api/v1/image-to-text?format=text' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: example-request-0001' \
  -F 'image=@document.png'

curl --silent --show-error --fail --max-time 150 \
  'https://freeaiocr.com/api/v1/image-to-text?format=docx' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: example-request-0001' \
  -F 'image=@document.png' \
  --dump-header - --output result.docx

Word は Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document と Content-Disposition: attachment を返します。cURL が成功し、この Content-Type を確認できた場合のみファイルを使用してください。変換応答の X-Request-Id、X-OCR-Charged-USD、X-OCR-Price-Version は元の認識に対応します。Cache-Control: no-store と該当する Idempotency-Replayed も維持されます。

24 時間以内は同じアカウント、画像バイト、MIME、Idempotency-Key で形式を変更しても再課金されません。期限後は新たな有料認識になる場合があります。旧プレーンテキストの変換では失われた構造は復元されません。

export_failed（503）は認識が成功・課金済みで、変換のみ失敗した状態です。JSON の recognition_succeeded は true です。有効期限内に元の画像とキーで再試行するか format=json を指定してください。返金や再認識は行いません。Word は編集可能な文字と表を保持しますが、元のレイアウトは再現しません。数式は LaTeX テキストとして残ります。

新しい操作や別のエンドポイントには別の Idempotency-Key を使います。文字 API と表 API で同じキーを使うと 409 idempotency_conflict です。同一操作の形式変更ではキーと画像を再利用します。冪等性と料金もご覧ください。