GET
/v1/schemas/fal/image/pixelcut/product-photo
Accept:
| field | recorded source |
|---|---|
| schema | Source linked above.Source tracec303e2488d32bc6b44d6e9494c2695e7c348116802ace9db7dd19b8275620820{
"fetchedAt": 1785560543,
"extractorVersion": "1",
"verifiedAt": null
} |
Request body
8 properties · 1 required · 10 $defs| property | type | description | constraints |
|---|---|---|---|
| image_url* | string | URL of the product image to be processed. | |
| shadow | Shadow | Shadow: choose a type ('Generative'/'Drop'; unset = no shadow) and set its params. | |
| watermark | Watermark | A logo/watermark image overlaid on top of the output. | nullable |
| sync_mode | boolean | When true, return the result as a data URL instead of uploading to storage. | default: true |
| image_size | ImageSize | enum | Output canvas size. A preset (square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9) or a custom {width, height}. Defaults to square_hd (1024x1024). | nullable · default: "square_hd" |
| background | Background | Output background: solid color (default white), transparent, or an image. | |
| output_format | enum | The format of the resultant image (PNG or JPEG). When not set, matches the input format. JPEG cannot be combined with a transparent background. | png | jpeg · nullable |
| margin | Margin | Canvas margins around the product: `all` for every side plus optional per-side overrides. Defaults to 20% on all sides. |
Types
10 $defsBackgroundobject
Output background: a solid color, transparent, or a background image.
| mode | enum | 'Color' fills with `color` (white by default); 'Transparent' leaves it transparent (always PNG); 'Image' composites onto `image_url`. | Transparent | Color | Image · default: "Color" |
| image_fit | enum | How the background image fills the canvas: 'Cover' fills and crops, 'Contain' fits and letterboxes onto `color`, 'Stretch' distorts to fit. | Cover | Contain | Stretch · default: "Cover" |
| image_url | string | Background image URL. Required when mode is 'Image'. | nullable |
| color | RGBColor | Solid background color (R/G/B, 0–255). Applies when mode is 'Color'. Defaults to white. |
DropShadowobject
Params for the deterministic drop shadow (used when shadow.type = 'drop'), mirroring the web editor's drop shadow (offset + blur + color + opacity).
| horizontal | number | Horizontal shadow offset strength (-100 to 100). Positive moves the shadow right, negative moves it left. 100 is the maximum offset, 10% of the canvas width. | -100 ≤ n ≤ 100 · default: 50 |
| opacity | number | Shadow opacity (0–1). | 0 ≤ n ≤ 1 · default: 0.25 |
| blur | number | Shadow blur strength (0 to 100). 0 is a hard-edged shadow; 100 is the softest, a radius of 5% of the smaller canvas dimension. | 0 ≤ n ≤ 100 · default: 24 |
| vertical | number | Vertical shadow offset strength (-100 to 100). Positive moves the shadow down, negative moves it up. 100 is the maximum offset, 10% of the canvas height. | -100 ≤ n ≤ 100 · default: 8 |
| color | RGBColor | Shadow color (R/G/B). Defaults to black. |
GenerativeShadowobject
Params for the generative AI shadow (used when shadow.type = 'generative').
| light_source | ShadowLightSource | Virtual light used to synthesize the shadow. When omitted, the light direction is estimated from the image. | nullable |
| opacity | number | Final composited shadow opacity (0–1). | 0 ≤ n ≤ 1 · default: 0.2 |
ImageSizeobject
| height | integer | The height of the generated image. | 0 < n ≤ 14142 · default: 512 |
| width | integer | The width of the generated image. | 0 < n ≤ 14142 · default: 512 |
Marginobject
Canvas margin around the product. `all` applies to every side; a per-side value overrides `all` for that side. Each value is '%' (0–49%) of the canvas, or 'px' (>=0px).
| top | string | Top-side override of `all`. '%' (0–49%) or 'px' (>=0px). | nullable |
| right | string | Right-side override of `all`. '%' (0–49%) or 'px' (>=0px). | nullable |
| bottom | string | Bottom-side override of `all`. '%' (0–49%) or 'px' (>=0px). | nullable |
| all | string | Margin applied to all sides. '%' (0–49%) of the canvas dimension, or 'px' (>=0px). | default: "20%" |
| left | string | Left-side override of `all`. '%' (0–49%) or 'px' (>=0px). | nullable |
RGBColorobject
RGB color. `RGBColor` is the FAL naming convention that renders the color-picker swatch. The per-field default (e.g. white for the background) is carried on each field below; note the playground swatch initializes to black regardless (a FAL UI quirk — it ignor…
| g* | integer | 0 ≤ n ≤ 255 | |
| r* | integer | 0 ≤ n ≤ 255 | |
| b* | integer | 0 ≤ n ≤ 255 |
Shadowobject
Shadow control: leave `type` unset for no shadow, or select 'generative' (AI) or 'drop' (deterministic); set its params in the matching nested object.
| generative | GenerativeShadow | Generative AI-shadow params (used when type is 'Generative'). | |
| drop | DropShadow | Drop-shadow params (used when type is 'Drop'). | |
| type | enum | Shadow style: 'Generative' (generative AI shadow) or 'Drop' (deterministic drop shadow). Leave unset for no shadow. | Generative | Drop · nullable |
ShadowLightSourceobject
| size | number | Apparent emitter size/softness. Higher = softer penumbra. Leave unset to auto-estimate the light from the image. | 0 ≤ n ≤ 1 · nullable |
| position | ShadowLightSourcePosition |
ShadowLightSourcePositionobject
| x | number | Horizontal light position, normalized to image center (-1 to 1). Leave unset to auto-estimate the light from the image. | -1 ≤ n ≤ 1 · nullable |
| y | number | Vertical light position, normalized to image center (-1 to 1). Leave unset to auto-estimate the light from the image. | -1 ≤ n ≤ 1 · nullable |
| z | number | Height above subject (0 to 2). Leave unset to auto-estimate the light from the image. | 0 ≤ n ≤ 2 · nullable |
Watermarkobject
A logo/watermark image overlaid on top of the output.
| position | enum | Where to place the watermark. | top_left | top_right | bottom_left | bottom_right | center · default: "bottom_right" |
| opacity | number | Watermark opacity (0–1). | 0 ≤ n ≤ 1 · default: 1 |
| image_url | string | Logo/watermark image URL. If empty, no watermark is added. | nullable |
| scale | number | Watermark width as a fraction of the canvas width. | 0.01 ≤ n ≤ 1 · default: 0.1 |
| margin | string | Inset from the edge. '%' (0–49%) of the canvas, or 'px'. | default: "3%" |
| remove_background | boolean | Remove the watermark image's own background (via background removal) before overlaying it. | default: false |
Validate a payload
before you spend tokensshell
$ curl -X POST https://modelschemas.com/v1/validate \
-d '{"provider":"fal","endpointId":"pixelcut/product-photo","payload":{…}}'
→ {"valid": false, "errors": [{"path": "#", "keyword": "required", …}]}