Skip to main content

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.

​
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

​
Authorization
string
required
Bearer token. Example: Bearer px_live_your_key

​
Request body

​
image
string
Base64-encoded image data. Provide either image or image_url, not both.
​
image_url
string
URL of the image to process. Provide either image or image_url, not both.
​
niche
string
required
Target niche ID. Use GET /api/v1/niches to see available options.
​
width_cm
number
required
Target width in centimeters (10–1000).
​
height_cm
number
required
Target height in centimeters (10–1000).
​
unit_width_cm
number
Width of each unit in cm. Defaults to the niche’s default.
​
unit_height_cm
number
Height of each unit in cm. Defaults to the niche’s default.
​
max_colors
number
Maximum number of colors in the palette. If set, the palette is trimmed to this count.
​
color_catalog
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();

​
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

FieldTypeDescription
successbooleanAlways true on success
nichestringThe niche used for generation
dimensions.colsnumberNumber of columns in the grid
dimensions.rowsnumberNumber of rows in the grid
dimensions.total_unitsnumberTotal units (cols × rows)
materialsarrayColors used with quantities and percentages
assembly_guidearrayStep-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_summaryarray | absentColor-grouped position summary (only for crossstitch and embroidery niches)
difficultystringAutomatically calculated difficulty: easy, medium, or hard. Based on volume (total units), color diversity, and fragmentation (color changes per row). Weights vary per niche.
usageobjectCurrent API usage after this call

​
Common errors

CodeDescription
MISSING_REQUIRED_FIELDniche, width_cm, or height_cm is missing
INVALID_NICHENiche does not exist or is not on your plan
INVALID_IMAGEImage could not be decoded
IMAGE_TOO_LARGEImage exceeds 10MB
INVALID_DIMENSIONSWidth or height outside 10–1000 cm
PROCESSING_ERRORInternal error during generation