---
title: "AI-edit an existing generation"
method: POST
path: "/v1/restyle"
tags: ["Editing"]
---

# AI-edit an existing generation

`POST /v1/restyle`

## Request

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

Edits an existing generation and saves the result as a **new** generation (the source is never modified). One synchronous model call; costs credits like a fresh generation (`generate_*` by output resolution).

### Modes

| Mode | How |
|---|---|
| Plain-text edit | `instructions` only — "make the sky stormy" |
| Product placement | `action: "bring"` + `reference_id` — the reference's product is placed into the scene at true real-world scale, relit to match, worn/held/placed naturally |
| Swap/add specific items | `action: "bring"` + `reference_id` + `items` (names from `GET /v1/detections`) |
| Recolor items | `action: "recolor"` + `reference_id` + optional `items` |
| Remove items | `action: "remove"` + `items` (no reference needed). `{ "name": "person" }` removes every person; `{ "id": 2 }` (a detection id from `GET /v1/detections` on the base) removes only that one, located by its box |
| Add subjects to scene | `action: "add"` + `reference_id` + optional `blend_level` 0-100 |
| Merge two images | `action: "merge"` + `reference_id` + `merge_bias` (0 = reference dominates, 100 = base dominates) + `merge_scope` scene\|items |
| Art-style transfer | `action: "style"` + `reference_id` + `style_intensity` 0-100 |

`reference_id` accepts an **asset or generation** you own.

The base photo is `generation_id` **or** `asset_id` (an image uploaded with `POST /v1/assets`), never both. An asset base is only read: the result is a new generation with `parent_id: null` that records the asset as its source, and the upload is never changed or copied.

## Request body

- object
  - `generation_id` string: The base photo to edit: a generation. Pass this or `asset_id`.
  - `asset_id` string: The base photo to edit: an uploaded asset (upload, product, background or reference). Mutually exclusive with `generation_id`.
  - `project_id` string, required: Project for the resulting generation.
  - `action` 'bring' | 'recolor' | 'remove' | 'add' | 'merge' | 'style'
  - `reference_id` string: Asset or generation providing the product/colors/style/content.
  - `entity_ids` string[]: Saved characters, props or places (ids from `GET /v1/entities`) whose baked reference sheet to attach. Writing `@slug` in the prompt does the same — a look is `@parent/look` or its own slug — and the prompt is rewritten so the model knows which picture is whom. Sheets go after your own references, within the model's reference limit; the response's `entities` says which went in and which were dropped. Unknown `@words` are left as typed. To leave something out, write `-@slug` (that prop comes off every items sheet the request sends, and the words are removed from the prompt) or pass `-<id>` here; `@slug/alone` or `<id>/alone` sends the entity without its items sheet. The response's `entities.excluded` lists what was left out.
  - `items` object[]: Each item needs a `name` or an `id`.
    - `id` integer: remove only: a detection id of the BASE photo (GET /v1/detections). Removes just that instance, located by its box; other items with the same name stay.
    - `name` string: Item name (see GET /v1/detections). Acts on every instance with that name.
    - `description` string
    - `color` string
    - `style_mode` 'keep' | 'adapt': keep = reference's look; adapt = re-render in the base's own style.
  - `scan_id` string: With item `id`s: the `scan_id` they were read from (GET /v1/detections). Default: the base's newest scan.
  - `instructions` string: Free-text edit instructions.
  - `blend_level` number: add: integration depth. Default 50.
  - `merge_bias` number: merge: 0 reference dominates, 100 base dominates. Default 50.
  - `merge_scope` 'scene' | 'items': merge only. Default scene.
  - `style_intensity` number: style: 0 subtle tint, 100 full reimagine. Default 75.
  - `aspect_ratio` '1:1' | '4:5' | '3:4' | '9:16' | '16:9' | '3:2' | '2:3': Default: the source's.
  - `resolution` '1K' | '2K' | '4K': Default: the source's. Drives credit cost.

## Response `200`

Edit complete; the new generation with a signed image URL.

## Other responses

- `400`: Missing/invalid fields, or nothing to do
- `401`: Missing or invalid token
- `402`: Insufficient credits or token cap exceeded
- `404`: Generation, asset, project, reference, or scan not found
- `429`: Rate limit exceeded
- `503`: Pricing not configured

---

[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/b454211e598e?raw)