Img-to-JSON · Agent mode
Image to JSON with Agent mode
Endpoint
https://www.claix.dev/agent/img-jsonAgent mode active
This endpoint runs structured extraction from the main schema first, then a reasoning phase with agent_definition. The response includes data[] (extraction) and agent_data (typed inference). The schema must have is_agent_mode enabled.
This endpoint accepts an image file and returns a single JSON object with the data extracted from the visible content, following exactly the structure you define via a schema. Analysis is performed by a multimodal AI model with native image understanding — ideal for photos of invoices, receipts, forms, labels, or documents scanned with a phone.
It is intended for server-to-serverintegrations (backends, scripts, n8n/Zapier/Make). It must not be called from an end user's browser because it requires a secret API key.
Like PDF-to-JSON, the full image is treated as a single data source and the response contains exactly one record in data.
1. Authentication
Every request must include your API key. It is a personal server credential and should be handled with the same care as a database password.
Option A — Dedicated header (recommended):
x-api-key: <YOUR_API_KEY>
Option B — Standard Authorization header:
Authorization: Bearer <YOUR_API_KEY>
Either one is sufficient. If you send both, x-api-key takes priority.
Before processing the image, the system validates that:
- The API key exists and is active.
- The associated account is active (not suspended).
If validation fails, the request is rejected with 401 without processing the file.
2. Request format
Method: POST · Content-Type: multipart/form-data (required)
| Field | Type | Required | Description |
|---|---|---|---|
| file | Binary file | Yes | The image to analyze. Must be the file itself, not a path or URL. |
| schema_id | Text (UUID) | Yes | Schema previously created in your account, of type Img → JSON. |
Field names must be exactly file and schema_id. Aliases such as image, imagen, or upload are not supported.
The schema_id must correspond to a schema of type Img → JSON. If you send one of PDF → JSON or another type, you will receive 400.
File requirements:
- Supported formats: .jpeg, .jpg, .png, .webp, .heic, and .heif (validated by MIME type, extension, and binary signature).
- Cannot be empty (0 bytes).
- Maximum size: 15 MB (413 error if exceeded).
- The image must be readable: blurry, out-of-focus, or poorly lit photos are rejected with 422 before returning data.
3. How to build the request
- Have your API key and the correct schema_id ready.
- Build a POST request to the endpoint URL.
- Add the authentication header.
- Send
multipart/form-datawithfile(image) andschema_id. - Check the HTTP status code: only 200 indicates success.
4. Request examples
See the panel on the right for examples in cURL, JavaScript, Node.js, Python, PHP, and n8n.
5. Successful response format
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."
}
}| Field | Type | Description |
|---|---|---|
| success | boolean | Always true when HTTP is 200. |
| schema_utilizado | string | Name of the schema used for extraction. |
| total_registros | number | Number of records in data. |
| data | array | Objects extracted from the main schema (same as extraction mode). |
| agent_data | object | Typed Agent Mode answers per agent_definition (booleans, numbers, strings). |
6. Error codes
{
"error": "Descripción legible del problema.",
"detalle": "Información técnica adicional (solo presente en algunos casos)."
}400 — Missing file or schema_id, invalid multipart, unsupported format, empty file, corrupt file, inconsistent binary signature, or schema of the wrong type.
401 — Authentication failed.
404 — schema_id does not exist or does not belong to your account.
413 — Image exceeds 15 MB.
422 — Illegible image (blurry, out of focus, poorly lit) or no extractable data according to the schema.
502 — AI service failure (transient).
405 — Method other than POST. · 500 — Internal error.
7. Code summary
| Code | Category | Retry? |
|---|---|---|
| 200 | Success | — |
| 400 | Client error (malformed image or data) | No — fix the request first |
| 401 | Authentication error | No — fix credentials first |
| 404 | Resource not found | No — fix schema_id first |
| 405 | Incorrect HTTP method | No — fix the method first |
| 413 | Image too large | No — reduce file size first |
| 422 | Illegible image or no extractable data | No — review image/schema first |
| 500 | Internal server error | Yes, with caution |
| 502 | AI service failure | Yes, recommended with backoff |
8. Best practices
- Validate the HTTP status code before reading data[0].
- Check the image size on your client before sending it.
- Remember: data always has exactly one element (one image = one object).
- Retry automatically only on 500 and 502, never on 400, 401, 404, 413, or 422.
- If you receive 422 due to quality, ask the user for a new capture with better focus and lighting before resubmitting.
- Clear descriptions on schema properties improve accuracy on non-standard layouts.
- Do not include your API key in frontend code or public repositories.