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

string

required

Bearer token. Example: Bearer px_live_your_key

Request body

string

Base64-encoded image data. Provide either image or image_url, not both.

string

URL of the image to process. Provide either image or image_url, not both.

string

required

Target niche ID. Use GET /api/v1/niches to see available options.

number

required

Target width in centimeters (10–1000).

number

required

Target height in centimeters (10–1000).

number

Width of each unit in cm. Defaults to the niche’s default.

number

Height of each unit in cm. Defaults to the niche’s default.

number

Maximum number of colors in the palette. If set, the palette is trimmed to this count.

string

Color catalog to use. Currently: "default" or "custom" (uses your API key’s custom colors).

Example request

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
  }'

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();

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()

$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,
    ],
]);

Response

{
  "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

Primeros pasos

Referencia de la API

Guías de integración

Recursos

POST /generate

Generate Pattern

Authentication

Request body

Example request

Response

Response fields

Common errors

​Generate Pattern

​Authentication

​Request body

​Example request

​Response

​Response fields

​Common errors

Generate Pattern

Authentication

Request body

Example request

Response

Response fields

Common errors