name	nanonets-api
description	Guia para integrar con el servicio OCR de Nanonets via API. Usar cuando se necesite extraer datos de documentos, crear modelos OCR, subir archivos para prediccion, o entrenar modelos personalizados.

Integracion API de Nanonets

1) Vision General

Nanonets es un servicio de OCR e IA que permite crear modelos personalizados para extraer datos estructurados de imagenes y documentos. Soporta operaciones sincronas y asincronas.

2) Autenticacion

Clave API

La clave API se obtiene en: https://app.nanonets.com/#keys

Almacenar en .env:

# Archivo: .env
NANONETS_API_KEY=tu_clave_api_aqui

URL Base

https://app.nanonets.com

Metodo de autenticacion

Nanonets usa Basic Auth con la API key como usuario y password vacio:

source .env && curl -X GET "https://app.nanonets.com/api/v2/OCR/Model/" \
  -u "$NANONETS_API_KEY:"

3) Conceptos Clave

Concepto	Descripcion
Model	Modelo OCR entrenado para extraer campos especificos
model_id	Identificador unico del modelo (UUID)
Prediction	Resultado de extraer datos de un documento
Label	Campo configurado en el modelo (ej: "fecha", "total")
request_file_id	ID unico del archivo subido

4) Referencia API - Predicciones (OCR)

Prediccion sincrona desde archivo local

Optimo para archivos de 3 paginas o menos.

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/LabelFile/" \
  -u "$NANONETS_API_KEY:" \
  -F "file=@recibo.pdf"

Con metadata opcional:

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/LabelFile/" \
  -u "$NANONETS_API_KEY:" \
  -F "file=@recibo.pdf" \
  -F "request_metadata={\"conductor_id\": \"123\"}"

Parametros:

file (requerido): Archivo local
request_metadata (opcional): JSON con datos adicionales
pages_to_process (opcional): Paginas a procesar (ej: "1,2")

Prediccion sincrona desde URL

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/LabelUrls/" \
  -u "$NANONETS_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://ejemplo.com/recibo.pdf"]}'

Prediccion asincrona desde archivo

Recomendado para archivos de mas de 3 paginas.

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/LabelFile/?async=true" \
  -u "$NANONETS_API_KEY:" \
  -F "file=@documento_largo.pdf"

Prediccion asincrona desde URL

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/LabelUrls/?async=true" \
  -u "$NANONETS_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://ejemplo.com/documento.pdf"]}'

5) Referencia API - Obtener Resultados

Obtener todas las predicciones de un modelo

source .env && curl -X GET "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/getModelImages/?start_day_interval=30&current_batch_day=0" \
  -u "$NANONETS_API_KEY:"

Parametros:

start_day_interval: Dias hacia atras desde hoy
current_batch_day: Dia actual del batch (0 = hoy)

Obtener prediccion por File ID

source .env && curl -X GET "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/getFile/{request_file_id}/" \
  -u "$NANONETS_API_KEY:"

Obtener prediccion por Page ID

source .env && curl -X GET "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/ImageLevelInferences/{page_id}/" \
  -u "$NANONETS_API_KEY:"

6) Referencia API - Entrenamiento

Subir imagenes de entrenamiento por archivo

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/UploadFile/" \
  -u "$NANONETS_API_KEY:" \
  -F "file=@imagen_entrenamiento.jpg"

Subir imagenes de entrenamiento por URL

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/UploadUrls/" \
  -u "$NANONETS_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://ejemplo.com/imagen1.jpg", "https://ejemplo.com/imagen2.jpg"]}'

Entrenar modelo

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/Train/" \
  -u "$NANONETS_API_KEY:"

7) Referencia API - Gestion de Archivos

Aprobar archivo

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/ApproveFile/{request_file_id}/" \
  -u "$NANONETS_API_KEY:"

Eliminar archivo

source .env && curl -X DELETE "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/DeleteFile/{request_file_id}/" \
  -u "$NANONETS_API_KEY:"

Actualizar campos de un archivo

source .env && curl -X PATCH "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/UpdateFile/{request_file_id}/" \
  -u "$NANONETS_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {"label": "fecha", "ocr_text": "2025-12-23"},
      {"label": "total", "ocr_text": "45.99"}
    ]
  }'

Exportar archivo

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/ExportFile/{request_file_id}/" \
  -u "$NANONETS_API_KEY:"

8) Estructura de Respuesta

Respuesta de prediccion exitosa

{
  "message": "Success",
  "result": [
    {
      "message": "Success",
      "input": "recibo.pdf",
      "prediction": [
        {
          "id": "abc123",
          "label": "fecha",
          "xmin": 100,
          "ymin": 200,
          "xmax": 250,
          "ymax": 230,
          "score": 0.95,
          "ocr_text": "23/12/2025",
          "type": "field",
          "status": "correctly_predicted",
          "page_no": 0,
          "label_id": "label_001"
        },
        {
          "id": "def456",
          "label": "total",
          "xmin": 300,
          "ymin": 400,
          "xmax": 400,
          "ymax": 430,
          "score": 0.92,
          "ocr_text": "45.99",
          "type": "field",
          "status": "correctly_predicted",
          "page_no": 0,
          "label_id": "label_002"
        },
        {
          "label": "lineas_detalle",
          "type": "table",
          "score": 0.89,
          "xmin": 50,
          "xmax": 500,
          "ymin": 500,
          "ymax": 700,
          "cells": [
            {
              "row": 1,
              "col": 1,
              "label": "descripcion",
              "text": "Gasoil",
              "score": 0.91
            },
            {
              "row": 1,
              "col": 2,
              "label": "cantidad",
              "text": "50L",
              "score": 0.88
            }
          ]
        }
      ],
      "page": 0,
      "request_file_id": "file_789",
      "processing_type": ""
    }
  ],
  "signed_urls": {
    "original": "https://...",
    "original_with_long_expiry": "https://..."
  }
}

Campos de respuesta clave

Campo	Descripcion
label	Nombre del campo configurado
ocr_text	Texto extraido
score	Confianza (0-1)
xmin/ymin/xmax/ymax	Coordenadas del bounding box
type	"field" o "table"
page_no	Numero de pagina (0 = primera)
request_file_id	ID unico del archivo
cells	Array de celdas (solo para tablas)

9) Sync vs Async

Tipo	Uso recomendado	Comportamiento
Sync	Archivos <= 3 paginas	Respuesta inmediata con resultados
Async	Archivos > 3 paginas	Respuesta con ID, procesa en ~5 min

Para async, usar el endpoint de "Get Prediction by File ID" para obtener resultados.

10) Manejo de Errores

Codigos de respuesta

Codigo	Significado	Accion
200	Exito	-
400	Archivo faltante o formato invalido	Verificar archivo
401	API key invalida	Verificar NANONETS_API_KEY
402	Limite de llamadas gratuitas agotado	Upgrade plan
404	Modelo no existe	Verificar model_id
429	Rate limit excedido	Esperar y reintentar

Manejo de 429 (Rate Limit)

# Implementar exponential backoff
for i in 1 2 4 8 16; do
  response=$(curl -s -w "%{http_code}" ...)
  if [ "${response: -3}" != "429" ]; then
    break
  fi
  sleep $i
done

11) Obtener Model ID

El model_id se encuentra en la URL del dashboard de Nanonets:

https://app.nanonets.com/#/ocr/model/{MODEL_ID}/...

O via la lista de modelos (requiere acceso al dashboard).

12) Ejemplo: Flujo completo

# 1. Cargar credenciales
source .env

# 2. Subir archivo para prediccion
curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/$MODEL_ID/LabelFile/" \
  -u "$NANONETS_API_KEY:" \
  -F "file=@recibo_gasoil.pdf" \
  -F 'request_metadata={"matricula": "1234-ABC"}'

# Respuesta incluye prediction con campos extraidos

# 3. Si es async, obtener resultados despues
curl -X GET "https://app.nanonets.com/api/v2/OCR/Model/$MODEL_ID/getFile/$REQUEST_FILE_ID/" \
  -u "$NANONETS_API_KEY:"

# 4. Aprobar archivo despues de revision
curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/$MODEL_ID/ApproveFile/$REQUEST_FILE_ID/" \
  -u "$NANONETS_API_KEY:"

13) Comparacion con Parsio

Aspecto	Nanonets	Parsio
Autenticacion	Basic Auth (API key:)	Header X-API-Key
Concepto principal	Model (modelo OCR)	Mailbox (email parser)
Recepcion docs	Solo API/UI	Email + API + UI
Entrenamiento	Via API	Via UI principalmente
Webhooks	Configurables via UI	API para CRUD
Sync/Async	Ambos soportados	Procesamiento automatico

nanonets-api

Install Skill

SKILL.md