{ "openapi": "3.1.0", "info": { "title": "PigmentaLab Developer API", "description": "Pre-press for DTF and textile printing: background removal, upscaling to print size at 300 dpi, color knockout, halftones and gang sheets, on PigmentaLab's own GPUs.\n\nAuthentication: the person's API key from https://pigmentalab.io/app/api as `Authorization: Bearer plb_live_...`. Never ask a person to paste a key into a chat.\n\nCredits: 1 credit = USD 0.01. Images over 25 megapixels cost x2 (not for gang sheets). A tool is charged only when it delivers.\n\nAI agents: the MCP server https://mcp.pigmentalab.io/mcp does the same with OAuth. Guide: https://pigmentalab.io/mcp", "version": "2026-08-30" }, "servers": [ { "url": "https://api.pigmentalab.io" } ], "paths": { "/v1/pricing": { "get": { "tags": [ "dev-v1" ], "summary": "Price list", "description": "Live price of every tool in credits (1 credit = USD 0.01). No key needed.", "operationId": "getPricing", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [] } }, "/v1/me": { "get": { "tags": [ "dev-v1" ], "summary": "Account and balance", "description": "The account that owns the key and its balance. Use it to test a key without spending credit.", "operationId": "getAccount", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/background/remove": { "post": { "tags": [ "dev-v1" ], "summary": "Remove the background", "description": "Transparent PNG, ready for a garment. 1 credit.", "operationId": "removeBackground", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_v1_bg_remove_v1_background_remove_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-credits": { "model": "flat", "credits": 1.0 } } }, "/v1/background/remove-auto": { "post": { "tags": [ "dev-v1" ], "summary": "Remove the background (engine chosen automatically)", "description": "Same result and price as /v1/background/remove. 1 credit.", "operationId": "removeBackgroundAuto", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_v1_bg_remove_auto_v1_background_remove_auto_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-credits": { "model": "flat", "credits": 1.0 } } }, "/v1/image/upscale": { "post": { "tags": [ "dev-v1" ], "summary": "Upscale for print", "description": "Enlarges the image to height_cm at 300 dpi. 1 credit.", "operationId": "upscaleImage", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_v1_upscale_v1_image_upscale_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-credits": { "model": "flat", "credits": 1.0 } } }, "/v1/nesting/sheet": { "post": { "tags": [ "dev-v1" ], "summary": "Gang sheet (nesting)", "description": "Lays several designs out on a roll. Asynchronous: returns a job_id; poll /v1/nesting/status and download /v1/nesting/result. Charged when it finishes, with the real metres. 5 credits plus 3 per linear metre.", "operationId": "createGangSheet", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_v1_nesting_sheet_v1_nesting_sheet_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-credits": { "model": "per_meter", "base_credits": 5.0, "per_meter_credits": 3.0 } } }, "/v1/nesting/status": { "get": { "tags": [ "dev-v1" ], "summary": "Gang sheet status", "operationId": "getGangSheetStatus", "parameters": [ { "name": "job_id", "in": "query", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Status of a /v1/nesting/sheet job." } }, "/v1/nesting/result": { "get": { "tags": [ "dev-v1" ], "summary": "Gang sheet result", "operationId": "getGangSheetResult", "parameters": [ { "name": "job_id", "in": "query", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "The finished gang sheet of a job." } }, "/v1/image/enhance": { "post": { "tags": [ "dev-v1" ], "summary": "Improve colors", "description": "Saturation, contrast, brightness and sharpness (1.0 = unchanged). 0.5 credits.", "operationId": "enhanceColors", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_v1_enhance_v1_image_enhance_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-credits": { "model": "flat", "credits": 0.5 } } }, "/v1/image/denoise": { "post": { "tags": [ "dev-v1" ], "summary": "Denoise", "description": "Removes noise and compression artifacts. 1 credit.", "operationId": "denoiseImage", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_v1_denoise_v1_image_denoise_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-credits": { "model": "flat", "credits": 1.0 } } }, "/v1/cutout/knockout": { "post": { "tags": [ "dev-v1" ], "summary": "Knock out a color", "description": "Makes black, white or a chosen color transparent (for dark or light garments). 0.5 credits.", "operationId": "knockoutColor", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_v1_knockout_v1_cutout_knockout_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-credits": { "model": "flat", "credits": 0.5 } } }, "/v1/halftone/artistic": { "post": { "tags": [ "dev-v1" ], "summary": "Artistic halftone", "description": "Halftone dots as an artistic effect. 0.5 credits.", "operationId": "halftoneArtistic", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_v1_halftone_artistic_v1_halftone_artistic_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-credits": { "model": "flat", "credits": 0.5 } } }, "/v1/halftone/fabric": { "post": { "tags": [ "dev-v1" ], "summary": "Garment-aware halftone", "description": "Halftone that takes the garment color into account (garment_hex). 0.5 credits.", "operationId": "halftoneFabric", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_v1_halftone_fabric_v1_halftone_fabric_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-credits": { "model": "flat", "credits": 0.5 } } }, "/v1/halftone/export": { "post": { "tags": [ "dev-v1" ], "summary": "Halftone export at 300 dpi", "description": "Halftone v2 rendered at 300 dpi over the original image. 1 credit.", "operationId": "halftoneExport", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_v1_halftone_export_v1_halftone_export_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-credits": { "model": "flat", "credits": 1.0 } } }, "/v1/halftone/zones/analyze": { "post": { "tags": [ "dev-v1" ], "summary": "Halftone by zones: analyze", "description": "Splits the image into zones and returns the label map and the zones as JSON. 0.5 credits.", "operationId": "halftoneZonesAnalyze", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_v1_zones_analyze_v1_halftone_zones_analyze_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-credits": { "model": "flat", "credits": 0.5 } } }, "/v1/halftone/zones/apply": { "post": { "tags": [ "dev-v1" ], "summary": "Halftone by zones: apply", "description": "Applies the halftone zone by zone with the decisions taken on /analyze. 1 credit.", "operationId": "halftoneZonesApply", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_v1_zones_apply_v1_halftone_zones_apply_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-credits": { "model": "flat", "credits": 1.0 } } }, "/v1/pro/logo": { "post": { "tags": [ "dev-v1" ], "summary": "Logo cleanup", "description": "For logos and flat artwork: sharp edges and clean colors. 1 credit.", "operationId": "cleanLogo", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_v1_pro_logo_v1_pro_logo_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-credits": { "model": "flat", "credits": 1.0 } } }, "/v1/pro/face": { "post": { "tags": [ "dev-v1" ], "summary": "Face restoration", "description": "Recovers blurry or damaged faces. 1 credit.", "operationId": "restoreFaces", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_v1_pro_face_v1_pro_face_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-credits": { "model": "flat", "credits": 1.0 } } } }, "components": { "schemas": { "Body_v1_bg_remove_auto_v1_background_remove_auto_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_v1_bg_remove_auto_v1_background_remove_auto_post" }, "Body_v1_bg_remove_v1_background_remove_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_v1_bg_remove_v1_background_remove_post" }, "Body_v1_denoise_v1_image_denoise_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_v1_denoise_v1_image_denoise_post" }, "Body_v1_enhance_v1_image_enhance_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" }, "saturation": { "type": "number", "title": "Saturation", "default": 1.0 }, "contrast": { "type": "number", "title": "Contrast", "default": 1.0 }, "brightness": { "type": "number", "title": "Brightness", "default": 1.0 }, "sharpness": { "type": "number", "title": "Sharpness", "default": 1.0 } }, "type": "object", "required": [ "file" ], "title": "Body_v1_enhance_v1_image_enhance_post" }, "Body_v1_halftone_artistic_v1_halftone_artistic_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" }, "threshold": { "type": "integer", "title": "Threshold", "default": 40 }, "dot_spacing": { "type": "integer", "title": "Dot Spacing", "default": 12 }, "max_radius": { "type": "integer", "title": "Max Radius", "default": 6 }, "forma": { "type": "string", "title": "Forma", "default": "circulo" }, "efecto": { "type": "string", "title": "Efecto", "default": "normal" }, "modo": { "type": "string", "title": "Modo", "default": "negro" } }, "type": "object", "required": [ "file" ], "title": "Body_v1_halftone_artistic_v1_halftone_artistic_post" }, "Body_v1_halftone_export_v1_halftone_export_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" }, "gridSize": { "type": "integer", "title": "Gridsize", "default": 8 }, "angle": { "type": "number", "title": "Angle", "default": 45 }, "halftoneType": { "type": "string", "title": "Halftonetype", "default": "INK_ON_DARK" }, "brightness": { "type": "number", "title": "Brightness", "default": 0 }, "contrast": { "type": "number", "title": "Contrast", "default": 0 }, "saturation": { "type": "number", "title": "Saturation", "default": 0 }, "removeBlack": { "type": "boolean", "title": "Removeblack", "default": false }, "blackThreshold": { "type": "integer", "title": "Blackthreshold", "default": 20 }, "removeWhite": { "type": "boolean", "title": "Removewhite", "default": false }, "whiteThreshold": { "type": "integer", "title": "Whitethreshold", "default": 20 }, "dotScale": { "type": "number", "title": "Dotscale", "default": 0.92 }, "toneFloor": { "type": "number", "title": "Tonefloor", "default": 0.025 }, "sampleBlur": { "type": "number", "title": "Sampleblur", "default": 0.35 } }, "type": "object", "required": [ "file" ], "title": "Body_v1_halftone_export_v1_halftone_export_post" }, "Body_v1_halftone_fabric_v1_halftone_fabric_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" }, "garment_hex": { "type": "string", "title": "Garment Hex", "default": "#000000" }, "threshold": { "type": "integer", "title": "Threshold", "default": 40 }, "dot_spacing": { "type": "integer", "title": "Dot Spacing", "default": 12 }, "max_radius": { "type": "integer", "title": "Max Radius", "default": 6 }, "forma": { "type": "string", "title": "Forma", "default": "circulo" }, "efecto": { "type": "string", "title": "Efecto", "default": "normal" } }, "type": "object", "required": [ "file" ], "title": "Body_v1_halftone_fabric_v1_halftone_fabric_post" }, "Body_v1_knockout_v1_cutout_knockout_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" }, "remove_mode": { "type": "string", "title": "Remove Mode", "default": "black" }, "target_hex": { "type": "string", "title": "Target Hex", "default": "" }, "tolerance": { "type": "integer", "title": "Tolerance", "default": 30 }, "threshold": { "type": "integer", "title": "Threshold", "default": 60 }, "gamma": { "type": "number", "title": "Gamma", "default": 1.8 }, "blur": { "type": "number", "title": "Blur", "default": 1.0 }, "progressive": { "type": "boolean", "title": "Progressive", "default": false }, "niveles": { "type": "integer", "title": "Niveles", "default": 0 }, "medida": { "type": "string", "title": "Medida", "default": "luz" } }, "type": "object", "required": [ "file" ], "title": "Body_v1_knockout_v1_cutout_knockout_post" }, "Body_v1_nesting_sheet_v1_nesting_sheet_post": { "properties": { "files": { "anyOf": [ { "items": { "type": "string", "format": "binary" }, "type": "array" }, { "type": "null" } ], "title": "Files" }, "cantidades": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Cantidades" }, "cantidades_json": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cantidades Json" }, "cm_w": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Cm W" }, "cm_h": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Cm H" }, "cm_w_json": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cm W Json" }, "cm_h_json": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cm H Json" }, "roll_width_cm": { "type": "number", "title": "Roll Width Cm", "default": 58.0 }, "margin_mm": { "type": "number", "title": "Margin Mm", "default": 5.0 } }, "type": "object", "title": "Body_v1_nesting_sheet_v1_nesting_sheet_post" }, "Body_v1_pro_face_v1_pro_face_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" }, "weight": { "type": "number", "title": "Weight", "default": 0.5 }, "upscale": { "type": "number", "title": "Upscale", "default": 2.0 }, "only_center_face": { "type": "boolean", "title": "Only Center Face", "default": false }, "has_aligned": { "type": "boolean", "title": "Has Aligned", "default": false }, "alto_cm": { "type": "number", "title": "Alto Cm", "default": 0.0 } }, "type": "object", "required": [ "file" ], "title": "Body_v1_pro_face_v1_pro_face_post" }, "Body_v1_pro_logo_v1_pro_logo_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" }, "logo_sharpness": { "type": "number", "title": "Logo Sharpness", "default": 1.0 }, "logo_contrast": { "type": "number", "title": "Logo Contrast", "default": 1.0 }, "logo_saturation": { "type": "number", "title": "Logo Saturation", "default": 1.0 }, "alto_cm": { "type": "number", "title": "Alto Cm", "default": 0.0 } }, "type": "object", "required": [ "file" ], "title": "Body_v1_pro_logo_v1_pro_logo_post" }, "Body_v1_upscale_v1_image_upscale_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" }, "height_cm": { "type": "number", "title": "Height Cm", "default": 28.0 }, "sharpness": { "type": "number", "title": "Sharpness", "default": 1.0 }, "contrast_boost": { "type": "number", "title": "Contrast Boost", "default": 1.0 }, "color_boost": { "type": "number", "title": "Color Boost", "default": 1.0 }, "auto_denoise": { "type": "boolean", "title": "Auto Denoise", "default": true } }, "type": "object", "required": [ "file" ], "title": "Body_v1_upscale_v1_image_upscale_post" }, "Body_v1_zones_analyze_v1_halftone_zones_analyze_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" }, "maxZonas": { "type": "integer", "title": "Maxzonas", "default": 12 }, "criterio": { "type": "string", "title": "Criterio", "default": "color" } }, "type": "object", "required": [ "file" ], "title": "Body_v1_zones_analyze_v1_halftone_zones_analyze_post" }, "Body_v1_zones_apply_v1_halftone_zones_apply_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" }, "labelMap": { "type": "string", "title": "Labelmap" }, "decisiones": { "type": "string", "title": "Decisiones", "default": "{}" }, "zoneParams": { "type": "string", "title": "Zoneparams", "default": "{}" }, "gridSize": { "type": "integer", "title": "Gridsize", "default": 8 }, "angle": { "type": "number", "title": "Angle", "default": 45 }, "halftoneType": { "type": "string", "title": "Halftonetype", "default": "INK_ON_DARK" }, "brightness": { "type": "number", "title": "Brightness", "default": 0 }, "contrast": { "type": "number", "title": "Contrast", "default": 0 }, "saturation": { "type": "number", "title": "Saturation", "default": 0 }, "removeBlack": { "type": "boolean", "title": "Removeblack", "default": false }, "blackThreshold": { "type": "integer", "title": "Blackthreshold", "default": 20 }, "removeWhite": { "type": "boolean", "title": "Removewhite", "default": false }, "whiteThreshold": { "type": "integer", "title": "Whitethreshold", "default": 20 }, "dotScale": { "type": "number", "title": "Dotscale", "default": 0.92 }, "toneFloor": { "type": "number", "title": "Tonefloor", "default": 0.025 }, "sampleBlur": { "type": "number", "title": "Sampleblur", "default": 0.35 }, "pattern": { "type": "string", "title": "Pattern", "default": "dots" }, "densityRefPx": { "type": "integer", "title": "Densityrefpx", "default": 0 }, "minDotMm": { "type": "number", "title": "Mindotmm", "default": 0.0 }, "printWidthCm": { "type": "number", "title": "Printwidthcm", "default": 0.0 }, "fabricHex": { "type": "string", "title": "Fabrichex", "default": "" }, "compensarColor": { "type": "boolean", "title": "Compensarcolor", "default": false }, "compensarFuerza": { "type": "number", "title": "Compensarfuerza", "default": 1.0 }, "targetLpi": { "type": "number", "title": "Targetlpi", "default": 0.0 }, "tramaNegativa": { "type": "boolean", "title": "Tramanegativa", "default": false }, "sinFundir": { "type": "boolean", "title": "Sinfundir", "default": false }, "toneCeiling": { "type": "number", "title": "Toneceiling", "default": 1.0 } }, "type": "object", "required": [ "file", "labelMap" ], "title": "Body_v1_zones_apply_v1_halftone_zones_apply_post" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "The person's PigmentaLab API key (plb_live_...), from https://pigmentalab.io/app/api" } } }, "externalDocs": { "url": "https://pigmentalab.io/mcp", "description": "Guide for agents and developers" }, "security": [ { "apiKey": [] } ] }