Img-to-JSON · Modo agente
Imagen a JSON con Modo agente
Endpoint
https://www.claix.dev/agent/img-jsonModo agente activo
Este endpoint ejecuta primero la extracción estructurada del schema principal y después una fase de razonamiento con agent_definition. La respuesta incluye data[] (extracción) y agent_data (inferencia tipada). El schema debe tener is_agent_mode activado.
Este endpoint recibe una imagen y devuelve un único objeto JSON con los datos extraídos del contenido visible, siguiendo exactamente la estructura que definas mediante un schema. El análisis lo realiza un modelo multimodal de IA con comprensión nativa de imágenes — ideal para fotos de facturas, tickets, formularios, etiquetas o documentos escaneados con el móvil.
Está pensado para integraciones server-to-server (backends, scripts, n8n/Zapier/Make). No debe llamarse desde el navegador de un usuario final porque requiere una API key secreta.
Igual que en PDF-to-JSON, la imagen completa se trata como una única fuente de datos y la respuesta contiene exactamente un registro en data.
1. Autenticación
Toda petición debe incluir tu API key. Es una credencial de servidor personal y debe tratarse con el mismo cuidado que una contraseña de base de datos.
Opción A — Header dedicado (recomendado):
x-api-key: <TU_API_KEY>
Opción B — Header estándar Authorization:
Authorization: Bearer <TU_API_KEY>
Con uno de los dos es suficiente. Si envías ambos, x-api-key tiene prioridad.
Antes de procesar la imagen, el sistema valida que:
- La API key exista y esté activa.
- La cuenta asociada esté activa (no suspendida).
Si falla, se rechaza con 401 sin procesar el archivo.
2. Formato de la petición
Método: POST · Content-Type: multipart/form-data (obligatorio)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| file | Archivo binario | Sí | La imagen a analizar. Debe ser el archivo en sí, no una ruta ni URL. |
| schema_id | Texto (UUID) | Sí | Schema previamente creado en tu cuenta, del tipo Img → JSON. |
Los nombres de campo deben ser exactamente file y schema_id. No se admiten alias como image, imagen o upload.
El schema_id debe corresponder a un schema de tipo Img → JSON. Si envías uno de PDF → JSON u otro tipo, recibirás 400.
Requisitos del archivo:
- Formatos admitidos: .jpeg, .jpg, .png, .webp, .heic y .heif (validados por MIME, extensión y firma binaria).
- No puede estar vacío (0 bytes).
- Tamaño máximo: 15 MB (error 413 si se supera).
- La imagen debe ser legible: fotos borrosas, desenfocadas o mal iluminadas se rechazan con 422 antes de devolver datos.
3. Cómo construir la llamada
- Ten a mano tu API key y el schema_id del tipo correcto.
- Construye un POST a la URL del endpoint.
- Añade el header de autenticación.
- Envía
multipart/form-dataconfile(imagen) yschema_id. - Comprueba el código HTTP: solo 200 indica éxito.
4. Ejemplos de llamada
Consulta el panel de la derecha para ver ejemplos en cURL, JavaScript, Node.js, Python, PHP y n8n.
5. Formato de la respuesta exitosa
200 OK · Content-Type: application/json
{
"success": true,
"schema_utilizado": "KYC Documento",
"total_registros": 1,
"data": [
{
"nombre": "Ana García López",
"numero_documento": "12345678Z",
"fecha_caducidad": "2031-06-15"
}
],
"agent_data": {
"documento_valido": true,
"caducidad_superada": false,
"resumen_documento": "DNI legible, vigente y apto para verificación KYC."
}
}| Campo | Tipo | Descripción |
|---|---|---|
| success | boolean | Siempre true cuando el HTTP es 200. |
| schema_utilizado | string | Nombre del schema aplicado en la extracción. |
| total_registros | number | Número de registros en data. |
| data | array | Objetos extraídos según el schema principal (igual que en extracción). |
| agent_data | object | Respuestas tipadas del Modo Agente según agent_definition (booleanos, números, strings). |
6. Códigos de error
{
"error": "Descripción legible del problema.",
"detalle": "Información técnica adicional (solo presente en algunos casos)."
}400 — Falta file o schema_id, multipart inválido, formato no soportado, archivo vacío, corrupto, firma binaria incoherente o schema de tipo incorrecto.
401 — Autenticación fallida.
404 — schema_id inexistente o no pertenece a tu cuenta.
413 — Imagen supera 15 MB.
422 — Imagen ilegible (borrosa, desenfocada, mal iluminada) o sin datos extraíbles según el schema.
502 — Fallo del servicio de IA (transitorio).
405 — Método distinto de POST. · 500 — Error interno.
7. Resumen de códigos
| Código | Categoría | ¿Reintentar? |
|---|---|---|
| 200 | Éxito | — |
| 400 | Error del cliente (imagen o datos mal formados) | No, corrige la petición primero |
| 401 | Error de autenticación | No, corrige las credenciales primero |
| 404 | Recurso no encontrado | No, corrige el schema_id primero |
| 405 | Método HTTP incorrecto | No, corrige el método primero |
| 413 | Imagen demasiado grande | No, reduce el tamaño del archivo primero |
| 422 | Imagen ilegible o sin datos extraíbles | No, revisa la imagen/schema primero |
| 500 | Error interno del servidor | Sí, con precaución |
| 502 | Fallo del servicio de IA | Sí, recomendado con backoff |
8. Buenas prácticas
- Valida el código HTTP antes de leer data[0].
- Comprueba el tamaño de la imagen en tu cliente antes de enviarla.
- Recuerda: data siempre tiene exactamente un elemento (una imagen = un objeto).
- Reintenta automáticamente solo en 500 y 502, nunca en 400, 401, 404, 413 o 422.
- Si recibes 422 por calidad, pide al usuario una nueva captura con mejor enfoque e iluminación antes de reenviar.
- Descripciones claras en las propiedades del schema mejoran la precisión en layouts poco estandarizados.
- No incluyas tu API key en frontend ni repositorios públicos.