> ## 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 /generate

> Convert an image into a physical pattern.

# Generate Pattern

```
POST /api/v1/generate
```

The core endpoint. Takes an image and target dimensions, and returns a complete pattern with materials list and assembly instructions.

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token. Example: `Bearer px_live_your_key`
</ParamField>

## Request body

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

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

<ParamField body="niche" type="string" required>
  Target niche ID. Use `GET /api/v1/niches` to see available options.
</ParamField>

<ParamField body="width_cm" type="number" required>
  Target width in centimeters (10–1000).
</ParamField>

<ParamField body="height_cm" type="number" required>
  Target height in centimeters (10–1000).
</ParamField>

<ParamField body="unit_width_cm" type="number">
  Width of each unit in cm. Defaults to the niche's default.
</ParamField>

<ParamField body="unit_height_cm" type="number">
  Height of each unit in cm. Defaults to the niche's default.
</ParamField>

<ParamField body="max_colors" type="number">
  Maximum number of colors in the palette. If set, the palette is trimmed to this count.
</ParamField>

<ParamField body="color_catalog" type="string">
  Color catalog to use. Currently: `"default"` or `"custom"` (uses your API key's custom colors).
</ParamField>

## Example request

```bash theme={null}
curl -X POST https://www.pixcraft.es/api/v1/generate \
  -H "Authorization: Bearer px_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/sunset.jpg",
    "niche": "curtains",
    "width_cm": 200,
    "height_cm": 250,
    "unit_width_cm": 1.5,
    "unit_height_cm": 2.0,
    "max_colors": 8
  }'
```

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://www.pixcraft.es/api/v1/generate', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer px_live_your_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      image_url: 'https://example.com/sunset.jpg',
      niche: 'curtains',
      width_cm: 200,
      height_cm: 250,
      max_colors: 8,
    }),
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://www.pixcraft.es/api/v1/generate',
      headers={'Authorization': 'Bearer px_live_your_key'},
      json={
          'image_url': 'https://example.com/sunset.jpg',
          'niche': 'curtains',
          'width_cm': 200,
          'height_cm': 250,
          'max_colors': 8,
      }
  )

  data = response.json()
  ```

  ```php PHP theme={null}
  $response = $client->post('https://www.pixcraft.es/api/v1/generate', [
      'headers' => ['Authorization' => 'Bearer px_live_your_key'],
      'json' => [
          'image_url' => 'https://example.com/sunset.jpg',
          'niche' => 'curtains',
          'width_cm' => 200,
          'height_cm' => 250,
          'max_colors' => 8,
      ],
  ]);
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "success": true,
  "niche": "curtains",
  "dimensions": {
    "width_cm": 200,
    "height_cm": 250,
    "cols": 133,
    "rows": 125,
    "total_units": 16625
  },
  "materials": [
    {
      "color_id": "blanco",
      "color_name": "Blanco",
      "hex": "#FFFFFF",
      "quantity": 10804,
      "percentage": 81.2
    },
    {
      "color_id": "azul",
      "color_name": "Azul",
      "hex": "#1E90FF",
      "quantity": 3200,
      "percentage": 19.2
    }
  ],
  "assembly_guide": [
    {
      "row": 1,
      "instructions": [
        { "color_id": "blanco", "count": 80 },
        { "color_id": "azul", "count": 53 }
      ]
    }
  ],
  "preview_url": null,
  "usage": {
    "calls_used": 244,
    "calls_remaining": 4756
  }
}
```

### Response fields

| Field                    | Type            | Description                                                                                                                                                                                                                        |
| ------------------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `success`                | boolean         | Always `true` on success                                                                                                                                                                                                           |
| `niche`                  | string          | The niche used for generation                                                                                                                                                                                                      |
| `dimensions.cols`        | number          | Number of columns in the grid                                                                                                                                                                                                      |
| `dimensions.rows`        | number          | Number of rows in the grid                                                                                                                                                                                                         |
| `dimensions.total_units` | number          | Total units (cols × rows)                                                                                                                                                                                                          |
| `materials`              | array           | Colors used with quantities and percentages                                                                                                                                                                                        |
| `assembly_guide`         | array           | Step-by-step assembly instructions. Direction depends on niche: `row-by-row` (top→bottom), `column-by-column` (left→right, for curtains), or `bottom-to-top` (for LEGO/rugs). Check `assemblyDirection` in `/api/v1/capabilities`. |
| `color_summary`          | array \| absent | Color-grouped position summary (only for crossstitch and embroidery niches)                                                                                                                                                        |
| `difficulty`             | string          | Automatically calculated difficulty: `easy`, `medium`, or `hard`. Based on volume (total units), color diversity, and fragmentation (color changes per row). Weights vary per niche.                                               |
| `usage`                  | object          | Current API usage after this call                                                                                                                                                                                                  |

## Common errors

| Code                     | Description                                    |
| ------------------------ | ---------------------------------------------- |
| `MISSING_REQUIRED_FIELD` | `niche`, `width_cm`, or `height_cm` is missing |
| `INVALID_NICHE`          | Niche does not exist or is not on your plan    |
| `INVALID_IMAGE`          | Image could not be decoded                     |
| `IMAGE_TOO_LARGE`        | Image exceeds 10MB                             |
| `INVALID_DIMENSIONS`     | Width or height outside 10–1000 cm             |
| `PROCESSING_ERROR`       | Internal error during generation               |