Image to Text

POST /api/v1/image-to-text

Request

Send one image in the image multipart field with POST; replace YOUR_API_KEY and document.png in the example. Let cURL set the multipart boundary. Only an optional format query parameter is supported—no extra fields or model settings. Follow the Bearer authentication and key-safety instructions before making requests.

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'

This JSON response is illustrative: recognized text and token use depend on the image. For a retry, follow the shared idempotency rules.

Success response (example usage)

{
  "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"
  }
}

Output formats

Only one optional query parameter is accepted: format=json|text|docx. Unknown parameters, duplicate format values and unsupported formats return 400 before recognition.

• json (default): the JSON text field contains Markdown, which may include HTML tables and LaTeX; usage and billing remain in the response
• text: the same JSON envelope with only text converted to plain text
• docx: a binary Word attachment (result.docx), with Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document and Content-Disposition: attachment

Plain-text example:

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'

Word example (use the file only when cURL succeeds and the response Content-Type is Word):

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

Converted responses preserve X-Request-Id, Cache-Control: no-store and Idempotency-Replayed when applicable. X-OCR-Charged-USD and X-OCR-Price-Version describe the original recognition charge.

Within 24 hours, switch formats using the same account, original image bytes, MIME and Idempotency-Key without another recognition charge. Old plain-text receipts can also be converted; format conversion cannot reconstruct structure already missing from an old result. After expiry a retry may start a new paid recognition.

export_failed (503) means recognition succeeded and was charged, but conversion failed. The JSON error includes recognition_succeeded: true. Retry with the original image and key while the result is valid, or request format=json. Conversion failure does not refund or repeat recognition. This differs from a confirmed recognition failure; do not treat a failed download as a free new operation.

Word preserves editable text and tables, not exact page layout. Formulas remain LaTeX text. Review the recognized content and table structure before use.

A new operation or different endpoint requires a new Idempotency-Key; sharing a key between Image to Text and Image to Table returns 409 idempotency_conflict. Switching formats of the same operation keeps the original key and image. See idempotency and retries and pricing for shared rules.