---
title: "Get a cutout's status and signed URLs"
method: GET
path: "/v1/cutouts/{generation_id}"
tags: ["Cutouts"]
---

# Get a cutout's status and signed URLs

`GET /v1/cutouts/{generation_id}`

## Request

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

Returns the current cutout state for a generation and fresh signed URLs for all output files. URLs are time-limited (~1 hour) — re-fetch this endpoint when they expire rather than caching them long-term. If the cutout is still processing, `status` will be `pending` and the URL fields will be absent.

## Response `200`

Cutout state and signed URLs.

- Cutout: 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).

## Other responses

- `401`: Missing or invalid token
- `404`: Generation not found or no cutout exists for it
- `429`: Rate limit exceeded

---

[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)