---
title: "Create a subject cutout (inline)"
method: POST
path: "/v1/cutouts"
tags: ["Cutouts"]
---

# Create a subject cutout (inline)

`POST /v1/cutouts`

## Request

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

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

| Field | Type | Description |
|---|---|---|
| `file` | binary (multipart only) | Raw image upload |
| `generation_id` | string (JSON only) | Use an existing generation |
| `asset_id` | string (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.

## Request body

- object
  - `project_id` string, required: Project to associate the resulting generation with.
  - `generation_id` string: ID of an existing generation to use as the source. Mutually exclusive with `asset_id`.
  - `asset_id` string: ID of an existing asset to use as the source. Mutually exclusive with `generation_id`.

## Response `200`

Cutout created and ready.

- object: Cutout result for a generation. URLs are signed and time-limited (~6-hour signing window) — re-fetch this resource to get fresh ones.
  - `generation_id` string: 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_url` string, uri, nullable: Signed URL for the transparent-background WebP subject cutout. Omitted if compositing produced no foreground.
  - `matte_url` string, uri, nullable: Signed URL for the grayscale alpha matte (PNG). White = subject, black = background.
  - `bg_plate_url` string, uri, nullable: Signed URL for the subject-removed background plate (PNG).
  - `task_id` string: ID of the Task row tracking this operation. The task is already `complete` when this response is returned.

## Other responses

- `400`: Zero or multiple sources provided, or missing project_id
- `401`: Missing or invalid token
- `402`: Insufficient credits or token cap exceeded
- `404`: generation_id or asset_id not found
- `429`: Rate limit exceeded
- `503`: Cutout feature is not available at this time

---

[API](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api.md) · [All operations](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api/revisions/7f7d4a72b17c?raw)