Imagen a texto

POST /api/v1/image-to-text

Solicitud

Envía exactamente una imagen con POST en el campo multipart image. Sustituye YOUR_API_KEY y document.png; deja que cURL configure el límite de multipart. Solo se permite el parámetro opcional format, sin otros campos ni ajustes del modelo. Consulta la autenticación Bearer y protección de claves.

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'

Este JSON es ilustrativo: el texto y los tokens usados dependen de la imagen. Consulta las reglas de idempotencia antes de reintentar.

Respuesta correcta (uso de ejemplo)

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

Formatos de salida

Solo se acepta un parámetro opcional: format=json|text|docx. Los parámetros desconocidos, repetidos o inválidos devuelven 400 antes del reconocimiento. json (predeterminado) incluye Markdown en text, con posibles tablas HTML y LaTeX. text convierte únicamente text a texto plano, conservando usage y billing. docx devuelve el adjunto Word result.docx.

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 usa Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document y Content-Disposition: attachment. Usa el archivo solo si cURL termina correctamente y coincide el Content-Type. X-Request-Id, X-OCR-Charged-USD y X-OCR-Price-Version corresponden al reconocimiento original. Se mantienen Cache-Control: no-store e Idempotency-Replayed cuando procede.

Durante 24 horas puedes cambiar de formato con la misma cuenta, bytes de imagen, MIME e Idempotency-Key sin otro cargo de reconocimiento. Tras vencer el plazo puede iniciarse una operación nueva con cargo. Convertir texto antiguo no recupera la estructura perdida.

export_failed (503) indica reconocimiento correcto y ya cobrado, pero conversión fallida; recognition_succeeded es true en el error JSON. Reintenta antes del vencimiento con la imagen y clave originales o pide format=json. No se reembolsa ni se repite el reconocimiento. Word conserva texto y tablas editables, sin reproducir el diseño exacto; las fórmulas permanecen como texto LaTeX.

Cada operación o endpoint nuevo necesita otro Idempotency-Key; compartirlo entre texto y tablas devuelve 409 idempotency_conflict. Cambiar el formato de la misma operación conserva la clave y la imagen originales. Consulta idempotencia y reintentos y precios.