> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pixcraft.es/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /validate

> Validate an image before processing.

# Validate Image

```
POST /api/v1/validate
```

Validates an image to check if it is suitable for pattern generation. Useful for pre-flight checks without consuming an API call on full generation.

## When to use validate vs generate

Use `/validate` to:

* Check image quality before showing the user a generation form
* Catch errors early (corrupted files, unsupported formats, low resolution)
* Get recommended settings based on image properties

## Request body

<ParamField body="image" type="string">
  Base64-encoded image data. Provide either `image` or `image_url`.
</ParamField>

<ParamField body="image_url" type="string">
  URL of the image to validate. Provide either `image` or `image_url`.
</ParamField>

## Example request

```bash theme={null}
curl -X POST https://www.pixcraft.es/api/v1/validate \
  -H "Authorization: Bearer px_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/photo.jpg"}'
```

## Response

```json theme={null}
{
  "valid": true,
  "image_info": {
    "width_px": 800,
    "height_px": 600,
    "format": "jpeg",
    "file_size_kb": 245
  },
  "warnings": [
    "Image has low resolution. Large patterns may lose detail."
  ],
  "recommended_settings": {
    "max_colors": 6,
    "min_unit_size_cm": 2.0
  }
}
```

### Response fields

| Field                  | Type    | Description                               |
| ---------------------- | ------- | ----------------------------------------- |
| `valid`                | boolean | Whether the image can be processed        |
| `image_info`           | object  | Image metadata (dimensions, format, size) |
| `warnings`             | array   | Non-blocking warnings about image quality |
| `recommended_settings` | object  | Suggested parameters for best results     |

### Interpreting warnings

| Warning                        | Meaning                                                               |
| ------------------------------ | --------------------------------------------------------------------- |
| "Image resolution is very low" | Image is under 50px in either dimension. Pattern will be very coarse. |
| "Image has low resolution"     | Image is under 200px. Large patterns may lack detail.                 |

## Common errors

| Code                     | Description                                         |
| ------------------------ | --------------------------------------------------- |
| `MISSING_REQUIRED_FIELD` | Neither `image` nor `image_url` was provided        |
| `INVALID_IMAGE`          | Image could not be decoded or format is unsupported |
| `IMAGE_TOO_LARGE`        | Image exceeds 10MB                                  |