Image → Markdown
Imagen a Markdown
Endpoint
https://claix.dev/api/img-markdownTranscribe el texto visible de la imagen a Markdown. Mismos formatos, firma binaria, límite de 15 MB y control de calidad que Imagen → JSON. La llamada al modelo y BYOK es la misma; la salida es Markdown, no un schema.
No hay schema_id. El Markdown siempre se devuelve. Con save=true se inserta en la base conectada, según las reglas activas de Markdown, y la respuesta incluye row_id. Si omites save, o envías save=false, solo se devuelve el Markdown.
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.
1. Autenticación
Toda petición debe incluir tu API key. Es una credencial de servidor personal, distinta de cualquier token de sesión, 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 el archivo, 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
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| file | Archivo binario | Sí | .jpeg, .jpg, .png, .webp, .heic y .heif. Máximo 15 MB. |
| save | Booleano | No | true inserta el Markdown en la base conectada y devuelve row_id. Si no viene, o es false, solo se devuelve el Markdown. space_id, window_time y window_context se rechazan. |
Método: POST · Content-Type: multipart/form-data
Modelo: Sí. Si la imagen no es legible, la respuesta es 422.
No hay schema_id. Los nombres de campo tienen que coincidir exactamente con la tabla.
3. Cómo construir la llamada
- Ten a mano tu API key. No necesitas schema_id.
- Construye un POST a la URL del endpoint.
- Añade el header de autenticación.
- Envía
multipart/form-dataconfile. - Para guardar la fila, envía también
save=true. Hacen falta reglas activas de Markdown.save=falseno inserta. - 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. Puedes cambiar el lenguaje con el selector y copiar el código. «save=true» añade ese campo.
5. Formato de la respuesta exitosa
200 OK · Content-Type: application/json
Sin save:
{
"success": true,
"markdown": "# Contrato de suministro\n\nImporte: 12.400 €",
"log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}Con save=true, el mismo cuerpo incluye además row_id:
{
"success": true,
"markdown": "# Contrato de suministro\n\nImporte: 12.400 €",
"row_id": "9b1e4c80-2a7d-4e11-8f33-0c6d5a4b2e18",
"log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}| Campo | Tipo | Descripción |
|---|---|---|
| success | boolean | Siempre true cuando el HTTP es 200. |
| markdown | string | El documento convertido. |
| row_id | string, opcional | Solo aparece si save es true. Id de la fila insertada en la base conectada. |
| log_id | string (UUID) | Identifica la llamada en el panel de logs. También aparece en la mayoría de errores una vez autenticada la petición. |
6. Códigos de error
{
"error": "Descripción legible del problema.",
"code": "no_rules",
"detalle": "Información técnica adicional (solo presente en algunos casos).",
"log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}400 — Falta file, el multipart es incorrecto, el formato o la firma binaria no coinciden, save no es true ni false, o llegan space_id, window_time o window_context.
401 — Autenticación fallida: key ausente, inexistente, desactivada o cuenta suspendida.
409 — La fila choca con una clave única. El cuerpo incluye code unique_conflict.
413 — La imagen supera 15 MB.
422 — La imagen no es legible, o no hay texto que transcribir. Con save=true, este estado también indica que el insert se rechazó antes de escribir: no hay reglas activas de Markdown, no hay base conectada, o la tabla o columna de la regla no coincide. El cuerpo incluye error y code.
502 — Fallo del servicio de IA, o el insert fue rechazado. Si falla el insert, el cuerpo incluye error y code, y la fila no se guarda.
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 markdown.
- row_id solo se devuelve si save es true. space_id, window_time y window_context se rechazan.
- Comprueba el tamaño y la nitidez de la imagen antes de enviarla.
- Reintenta automáticamente solo en 500 y 502, nunca en 4xx salvo cambios en la petición.
- No incluyas tu API key en frontend ni repositorios públicos.