Web Analytics Made Easy - Statcounter
Skip to content

API de conversi贸n

Endpoints para subir y convertir documentos.

Subir y convertir un solo documento

POST /api/convert
Content-Type: multipart/form-data

Par谩metros

Nombre Tipo Obligatorio Descripci贸n
file Archivo S铆 Documento a convertir
settings Cadena JSON No Sobrescritura de la configuraci贸n de conversi贸n

Ejemplo de solicitud

curl -X POST http://localhost:5001/api/convert \
  -F "file=@document.pdf" \
  -F 'settings={"ocr":{"enabled":true,"language":"en"}}'

Respuesta (202 Accepted)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "document.pdf",
  "input_format": "pdf",
  "status": "processing",
  "message": "Conversi贸n iniciada"
}

Conversi贸n por lotes de varios documentos

POST /api/convert/batch
Content-Type: multipart/form-data

Par谩metros

Nombre Tipo Obligatorio Descripci贸n
files Archivo[] S铆 Documentos a convertir (repita el campo files en cada parte). Las subidas de carpetas desde la interfaz usan la misma forma: una parte multipart por archivo tras expandir el directorio en el navegador.
settings Cadena JSON No Sobrescritura de la configuraci贸n de conversi贸n

Tipos admitidos: Cada nombre de archivo debe tener una extensi贸n permitida por el servidor (v茅ase ALLOWED_EXTENSIONS en el despliegue). Las partes no admitidas no se convierten; aparecen en la respuesta con "status": "rejected". Si todas las partes no son compatibles (o no generan ninguna conversi贸n), la API devuelve 400 con un mensaje error y la lista jobs por archivo.

Tama帽o de la solicitud: Todo el cuerpo multipart debe estar dentro de MAX_CONTENT_LENGTH (por defecto 100 MB para toda la solicitud), no por archivo. Las carpetas grandes pueden dividirse en varias solicitudes por lotes.

Ejemplo de solicitud

curl -X POST http://localhost:5001/api/convert/batch \
  -F "files=@doc1.pdf" \
  -F "files=@doc2.pdf" \
  -F "files=@image.png"

Respuesta (202 Accepted)

{
  "jobs": [
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440001",
      "filename": "doc1.pdf",
      "input_format": "pdf",
      "status": "processing"
    },
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440002",
      "filename": "doc2.pdf",
      "input_format": "pdf",
      "status": "processing"
    },
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440003",
      "filename": "image.png",
      "input_format": "image",
      "status": "processing"
    }
  ],
  "total": 3,
  "message": "Se iniciaron 3 conversiones"
}

Respuesta (400 Bad Request)

Se devuelve cuando no se inicia ning煤n trabajo de conversi贸n (por ejemplo, si todos los archivos tienen una extensi贸n no permitida):

{
  "error": "No hay archivos compatibles para convertir",
  "jobs": [
    {
      "filename": "readme.exe",
      "status": "rejected",
      "error": "Tipo de archivo no permitido"
    }
  ],
  "total": 1
}

Convertir documento desde URL

POST /api/convert/url
Content-Type: application/json

Par谩metros

Nombre Tipo Obligatorio Descripci贸n
url string S铆 URL del documento a convertir
settings object No Sobrescritura de la configuraci贸n de conversi贸n

Ejemplo de solicitud

curl -X POST http://localhost:5001/api/convert/url \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/document.pdf",
    "settings": {"ocr": {"enabled": true}}
  }'

Respuesta (202 Accepted)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "document.pdf",
  "source_url": "https://example.com/document.pdf",
  "input_format": "pdf",
  "status": "processing",
  "message": "Conversi贸n iniciada"
}

Conversi贸n por lotes desde URLs

POST /api/convert/url/batch
Content-Type: application/json

Par谩metros

Nombre Tipo Obligatorio Descripci贸n
urls string[] S铆 Lista de URLs a convertir
settings object No Sobrescritura de la configuraci贸n de conversi贸n

Ejemplo de solicitud

curl -X POST http://localhost:5001/api/convert/url/batch \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/doc1.pdf",
      "https://example.com/doc2.docx",
      "https://example.com/page.html"
    ]
  }'

Respuesta (202 Accepted)

{
  "jobs": [
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440001",
      "url": "https://example.com/doc1.pdf",
      "filename": "doc1.pdf",
      "input_format": "pdf",
      "status": "processing"
    },
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440002",
      "url": "https://example.com/doc2.docx",
      "filename": "doc2.docx",
      "input_format": "docx",
      "status": "processing"
    },
    {
      "url": "https://example.com/invalid",
      "status": "rejected",
      "error": "Tipo de archivo no permitido"
    }
  ],
  "total": 3,
  "message": "Se iniciaron 2 conversiones"
}

Obtener el estado de la conversi贸n

GET /api/convert/{job_id}/status

Respuesta (en proceso)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "progress": 45,
  "message": "Analizando documento con OCR (easyocr, en)..."
}

Respuesta (completada)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "progress": 100,
  "message": "Conversi贸n completada correctamente",
  "confidence": 0.92,
  "formats_available": ["markdown", "html", "json", "text", "doctags"],
  "images_count": 3,
  "tables_count": 2,
  "chunks_count": 0,
  "preview": "# T铆tulo del documento\n\nPrimer p谩rrafo..."
}

Respuesta (error)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "progress": 0,
  "message": "Error en la conversi贸n: formato PDF no v谩lido",
  "error": "Formato PDF no v谩lido"
}

Obtener el resultado de la conversi贸n

GET /api/convert/{job_id}/result

Respuesta

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "confidence": 0.92,
  "formats_available": ["markdown", "html", "json", "text", "doctags", "document_tokens"],
  "result": {
    "markdown_preview": "# T铆tulo del documento\n\nVista previa del contenido...",
    "formats_available": ["markdown", "html", "json", "text", "doctags"],
    "page_count": 5,
    "images_count": 3,
    "tables_count": 2,
    "chunks_count": 0,
    "warnings": []
  },
  "images_count": 3,
  "tables_count": 2,
  "chunks_count": 0,
  "completed_at": "2024-01-15T10:30:00Z"
}

Obtener im谩genes extra铆das

GET /api/convert/{job_id}/images

Respuesta

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "images": [
    {
      "id": 1,
      "filename": "image_1.png",
      "path": "/outputs/job_id/images/image_1.png",
      "caption": "Figura 1: diagrama de arquitectura",
      "label": "figure"
    },
    {
      "id": 2,
      "filename": "image_2.png",
      "path": "/outputs/job_id/images/image_2.png",
      "caption": "",
      "label": "picture"
    }
  ],
  "count": 2
}

Descargar imagen extra铆da

GET /api/convert/{job_id}/images/{image_id}

Respuesta: Archivo de imagen binario (PNG)

Obtener tablas extra铆das

GET /api/convert/{job_id}/tables

Respuesta

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "tables": [
    {
      "id": 1,
      "label": "table",
      "caption": "Tabla 1: datos de ventas",
      "rows": [
        ["Producto", "T1", "T2", "T3", "T4"],
        ["Art铆culo A", "100", "150", "200", "175"]
      ],
      "csv_path": "/outputs/job_id/tables/table_1.csv",
      "image_path": "/outputs/job_id/tables/table_1.png"
    }
  ],
  "count": 1
}

Descargar tabla en CSV

GET /api/convert/{job_id}/tables/{table_id}/csv

Respuesta: Archivo CSV

Descargar tabla como imagen

GET /api/convert/{job_id}/tables/{table_id}/image

Respuesta: Archivo de imagen binario (PNG)

Obtener fragmentos del documento

GET /api/convert/{job_id}/chunks

Respuesta

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "chunks": [
    {
      "id": 1,
      "text": "Primer fragmento de texto del documento.",
      "meta": {
        "headings": ["Introducci贸n"],
        "page": 1
      }
    },
    {
      "id": 2,
      "text": "Segundo fragmento contin煤a el contenido.",
      "meta": {
        "headings": ["Introducci贸n", "Antecedentes"],
        "page": 1
      }
    }
  ],
  "count": 2
}

Exportar documento

GET /api/export/{job_id}/{format}

Formatos admitidos

  • markdown
  • html
  • json
  • text
  • doctags
  • document_tokens
  • chunks

Respuesta: Descarga de archivo con el tipo MIME adecuado

Eliminar trabajo

DELETE /api/convert/{job_id}

Respuesta

{
  "message": "Trabajo 550e8400-e29b-41d4-a716-446655440000 eliminado",
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}