API publica

Documentacion API

Integra SotaOCR en tus agentes de AI y pipelines con LLM. La API es asincrona: subes un documento, consultas el estado del job y luego obtienes el resultado final o, si hace falta, la vista previa de pagina en el mismo espacio de coordenadas que las OCR bbox.

URL base

Todos los endpoints publicos de OCR se sirven desde este host.

https://sotaocr.com

Autenticacion

Todas las solicitudes de la API requieren un token Bearer. Puedes crear una API key en tu panel.

Encabezado

Authorization: Bearer YOUR_API_KEY

Rutas disponibles

El servicio OCR expone rutas 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 y /v1/jobs/{job_id}/pages/{page_number}/preview. Lee model_profiles con GET /api/v1/info antes de enviar model_profile. Las reconstrucciones HTML y DOCX por ahora solo estan disponibles para jobs del modelo FAST.

Preprocesamiento OCR

Antes del OCR principal, el servicio detecta automaticamente la orientacion de la pagina, la rota y aplica document unwarping solo cuando hace falta. El angulo detectado se devuelve en doc_preprocessor_res.angle y el endpoint preview entrega la imagen exacta cuya coordinate space coincide con las OCR bbox.

Polling y disponibilidad

Consulta la API como maximo una vez por segundo. Hasta que termine el OCR, GET /v1/jobs/{job_id}/result devuelve 202 Accepted con el codigo result_not_ready.

Pro OCR

Cuando el modelo Pro esta habilitado, envie model_profile=pro en /v1/extract para usar OCR de mayor calidad. Pro OCR cuesta 2 scan pages por cada pagina procesada del documento.

cURL · Solicitud 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 · Respuesta

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

Comprobar balance de paginas

/v1/balance Devuelve el balance actual de scan pages de la cuenta autenticada. Use remaining_pages o total_affordable_pages para decidir cuantas paginas aun se pueden procesar.

cURL · Solicitud

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

JSON · Respuesta

{
  "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. Subir documento

/v1/extract Sube un PDF o una imagen para OCR. En exito devuelve 202 Accepted con metadatos del job como account_id, upstream_job_id, created_at y updated_at.

file: Archivo del documento (PDF, PNG, JPG).
page_ranges: (Opcional) Cadena JSON con un arreglo de rangos de paginas. Ejemplo: '[{"start":1,"end":3}]'
model_profile: Perfil opcional del modelo OCR. Omita el campo para usar el valor predeterminado del servicio, o envie uno de los valores devueltos en model_profiles por GET /api/v1/info.

cURL · Solicitud

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 · Respuesta

{
  "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. Consultar estado

/v1/jobs/{job_id} Devuelve 200 OK con el estado actual y tambien account_id, upstream_job_id, page_count, pages_completed, created_at y updated_at.

cURL · Solicitud

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

JSON · Respuesta

{
  "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. Obtener resultado

/v1/jobs/{job_id}/result?format=markdown Devuelve 200 OK con el contenido extraido cuando el job esta completed. Para format=json, cada pagina puede incluir doc_preprocessor_res con angle y page_preview con metadata del espacio de coordenadas de las bbox. format=html devuelve HTML reconstruido dentro del envelope JSON y por ahora solo es FAST; para un archivo HTML standalone con imagenes embebidas usa /result.html. Antes de terminar responde 202 Accepted con el codigo result_not_ready.

format: (Opcional) Formato de respuesta: json, markdown, text o html. Por defecto json. html por ahora solo es FAST.

cURL · Solicitud

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

JSON · Respuesta

{
  "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. Obtener HTML standalone

/v1/jobs/{job_id}/result.html Devuelve una reconstruccion text/html con imagenes data-URI embebidas para jobs FAST y PRO.

cURL · Solicitud

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

JSON · Respuesta

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

(HTML standalone con imagenes data-URI embebidas)

GET

5. Obtener reconstruccion DOCX

/v1/jobs/{job_id}/result.docx Devuelve un .docx binario con reconstruccion visual, imagenes de pagina embebidas y texto OCR buscable para jobs FAST y PRO.

cURL · Solicitud

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

JSON · Respuesta

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

(bytes DOCX binarios)

GET

6. Obtener preview de pagina para bbox overlays

/v1/jobs/{job_id}/pages/{page_number}/preview Devuelve la imagen PNG de la pagina tras la rotacion automatica y el unwarp opcional. Esta es la misma imagen sobre la que debes renderizar las OCR bbox.

cURL · Solicitud

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 · Respuesta

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

(bytes PNG binarios en el mismo espacio de coordenadas que las bbox OCR)

Errores API

La mayoria de los errores usan {"error":{"code":"...","message":"..."}}. insufficient_balance tambien incluye entity_code, requested_units y available_units.

400 Solicitud incorrecta: Multipart invalido, falta file, page_ranges invalido o PDF invalido. Codigo: bad_request.
401 No autorizado: Falta el token Bearer o es invalido. Codigo: unauthorized.
403 Prohibido: Se requiere acceso API o falta saldo. Codigos: api_access_required o insufficient_balance.
404 No encontrado: job_id desconocido o acceso a un job de otra cuenta. Codigo: job_not_found.
415 Medio no soportado: Tipo de archivo subido no soportado. Codigo: unsupported_media.
502 Upstream no disponible: El upstream OCR no esta disponible o fallo la sincronizacion del job. Codigo: upstream_unavailable.

Listo para integrar?

Crea una API key en el panel y obten paginas gratuitas para pruebas.

Abrir panel Obtener acceso API Descargar skill