Cutouts

Create a subject cutout (inline)

Generates a production-grade transparent cutout of an image's subject, plus a grayscale matte and a subject-removed background plate. Processes one image per call, synchronously.

Source — exactly one required

FieldTypeDescription
filebinary (multipart only)Raw image upload
generation_idstring (JSON only)Use an existing generation
asset_idstring (JSON only)Use an existing asset

Pass the source as multipart/form-data (with a file field) or as JSON (with generation_id or asset_id). Supplying zero sources or more than one returns 400 validation_error.

Outputs

  • cutout_url — transparent-background WebP of the subject. Omitted if compositing produced no foreground.
  • matte_url — grayscale alpha matte PNG (white = subject, black = background).
  • bg_plate_url — subject-removed background plate PNG.

All URLs are signed and expire in ~1 hour. Re-fetch GET /v1/cutouts/{generation_id} for fresh URLs.

Cost

Charged per call (operation key alpha_extract_*). See GET /v1/pricing for the current credit amount.

post/v1/cutouts

Request

  • Base URL: https://nanostudiopro.com/api
  • URL: https://nanostudiopro.com/api/v1/cutouts
  • Auth: HTTP bearer

Request body

project_idstring required

Project to associate the resulting generation with.

generation_idstring

ID of an existing generation to use as the source. Mutually exclusive with asset_id.

asset_idstring

ID of an existing asset to use as the source. Mutually exclusive with generation_id.

Response

Cutout created and ready.

generation_idstring

ID of the generation this cutout belongs to.

status'pending' | 'ready' | 'failed'

ready once all outputs are stored; pending while processing; failed on unrecoverable error.

cutout_urlstring uri nullable

Signed URL for the transparent-background WebP subject cutout. Omitted if compositing produced no foreground.

matte_urlstring uri nullable

Signed URL for the grayscale alpha matte (PNG). White = subject, black = background.

bg_plate_urlstring uri nullable

Signed URL for the subject-removed background plate (PNG).

task_idstring

ID of the Task row tracking this operation. The task is already complete when this response is returned.

Changes

No recorded changes to this operation across all 2 revisions of this API.