Img-to-JSON · Agent mode
Image to JSON with Agent mode
Endpoint
https://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), agent_data (typed inference), and log_id. 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. |
| space_id | Text (UUID) | No | Optional. Knowledge space the stored document is attached to. Must belong to the same account as the API key. It only takes effect when the schema has the context window enabled, which is when the document is stored. You can then query the whole space with POST /space-context/{space_id}. |
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."
},
"log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}| 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). If source verification is enabled on the schema, each property is { value, source }. |
| agent_data | object | Typed Agent Mode answers per agent_definition (booleans, numbers, strings). If source verification is enabled on the schema, each field is { value, source }. |
| log_id | string (UUID) | UUID of this call’s usage_logs row. Present on success and on most authenticated errors. |
Every response includes log_id (the UUID of the usage_logs row) when the log could be stored. It also appears on most errors after the request is authenticated. Use it to find the call in the logs panel.
If source verification is enabled on the schema, each extracted property (and each agent_data field in Agent mode) becomes { "value": ..., "source": "..." } instead of a bare value. source is required: it cites the evidence (page, paragraph, cell, quoted snippet, image region, or the second / second range in audio). If there is no evidence, source is exactly requires_human_revision. If source verification is off, the format is unchanged.
Example with source verification enabled:
{
"success": true,
"schema_utilizado": "Contratos",
"total_registros": 1,
"log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34",
"data": [
{
"persona contratada": {
"value": "Gael Anaya",
"source": "página 1, párrafo 1"
}
}
],
"agent_data": {
"salario": {
"value": 55000,
"source": "página 2, cláusula retributiva"
},
"es_parcial": {
"value": false,
"source": "requires_human_revision"
}
}
}6. Error codes
{
"error": "Descripción legible del problema.",
"detalle": "Información técnica adicional (solo presente en algunos casos).",
"log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}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.