# 이미지

> Nodaro 이미지 도구로 AI 어시스턴트에서 이미지를 생성, 변환, 편집, 마스킹, 합성, 설명하는 방법과 매개변수, 기본값, 크레딧을 정리했습니다.

Source: https://nodaro.ai/ko/docs/mcp/tools/image

**이미지 도구**를 사용하면 어시스턴트가 Nodaro에서 이미지를 만들고 바꿀 수 있습니다. 프롬프트로 생성하고, 기존 이미지를 변환하거나 편집하고, 마스크를 따고, 여러 이미지나 레이어를 합성하고, 이미지에 담긴 내용을 설명합니다. 각 도구는 작업을 시작해 그 ID를 반환하며, 결과는 내 라이브러리에 저장됩니다. 모든 이미지 도구에는 `workflows:execute` 권한이 필요합니다.

| 도구 | 하는 일 | 크레딧 |
| --- | --- | --- |
| [`generate_image`](#generate_image) | 레퍼런스와 선택 사항인 인페인팅을 지원하는 텍스트 이미지 생성 | 모델의 가격 |
| [`modify_image`](#modify_image) | 기존 이미지를 편집, 스타일 변경, 변환 | 모델의 가격 |
| [`image_to_image`](#image_to_image) | 마스크와 여러 레퍼런스를 지원하는, 프롬프트로 안내하는 이미지 변환 | 모델의 가격 |
| [`edit_image`](#edit_image) | 업스케일, 배경 제거, 부분 편집 | 연산의 가격 |
| [`generate_mask`](#generate_mask) | 설명한 대상의 흑백 마스크 | 55크레딧 |
| [`image_collage`](#image_collage) | 이미지 2~30개를 큰 이미지 하나로 결합 | 2K는 22크레딧, 4K는 44크레딧 |
| [`image_overlay`](#image_overlay) | AI 없이 이미지 위에 배치하는 로고, 텍스트, QR 코드, 도형 | 11크레딧, 추가 크기마다 더 듦 |
| [`suggest_overlay_placement`](#suggest_overlay_placement) | 로고나 텍스트를 이미지의 어디에 놓을지 제안 | 이미지 설명 1회 |
| [`image_to_text`](#image_to_text) | 이미지에 대한 설명이나 답변 | 기본 모델로 4크레딧 |
| [`save_image_defaults`](#save_image_defaults) | 내 기본 이미지 모델과 설정 | 무료 |
| [`list_palettes`](#list_palettes), [`save_palette`](#save_palette) | `generate_image`를 조정하는 내 컬러 팔레트 | 무료 |
| [`list_moodboards`](#list_moodboards), [`save_moodboard`](#save_moodboard) | `generate_image`를 조정하는 내 무드보드 | 무료 |

## `generate_image`
Nodaro의 이미지 모델 중 하나로 텍스트 프롬프트에서 이미지를 만듭니다. “…의 이미지를 만들어 줘” 같은 요청에 쓰이는 도구이며, [**이미지 생성**](https://nodaro.ai/docs/nodes/image/generate-image) 노드와 같은 방식으로 작동합니다.

**권한:** `workflows:execute`. **크레딧:** 선택한 해상도나 품질에서의 모델 가격입니다.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `prompt` | string | 이미지의 설명으로, 최대 4,000자입니다. 프리셋이 제공하지 않으면 필수입니다. |
| `model` | string | 모델 id입니다. 기본값은 `gpt-image-2`입니다. 알 수 없는 id는 기본값으로 대체됩니다. [`list_models`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_models)를 참조하세요. |
| `aspect_ratio` | string | 예: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`. 기본값은 `16:9`입니다. `16x9` 같은 형식도 받으며, 모델이 지원하지 않는 비율은 지원하는 비율로 대체됩니다. `auto`는 모든 모델에서 사진의 형태를 유지합니다. 사진은 설정되어 있으면 `base_image_url`, 아니면 첫 번째 레퍼런스 이미지입니다. 자체 `auto` 설정이 있는 모델은 그 값을 받고, 다른 모델은 그 사진에 가장 가까운 지원 비율을 사용합니다. 사진이 없으면 `auto`는 모델에 자체 `auto`가 있으면 그것을, 없으면 모델이 `16:9`를 지원할 때 `16:9`를, 그것도 아니면 모델 목록의 첫 비율을 사용합니다. |
| `resolution` | string | 지원하는 모델에서 `1K`, `2K`, `4K` 중 하나입니다. 지원하는 값 중 가장 가까운 값이 쓰입니다. |
| `quality` | string | 품질 설정이 있는 모델에서 `medium` 또는 `high`입니다. |
| `negative_prompt` | string | 피할 내용으로, 최대 2,000자입니다. |
| `reference_image_urls` | array | 인물, 캐릭터, 제품, 스타일을 유지하기 위한 레퍼런스 이미지 최대 14개로, URL이나 Nodaro id로 넣습니다. 응답에서 몇 개가 첨부되었는지 확인할 수 있습니다. |
| `count` | integer | 모델당 이미지 1~4장입니다. 이미지마다 별도의 작업입니다. |
| `models` | array | `model` 대신 쓰는 이미지 모델 ID 2~4개입니다. 같은 요청이 각 모델에서 실행됩니다. |
| `presetId` | string | [`list_node_presets`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_node_presets)의 프리셋으로, 편집기가 적용하는 방식 그대로 적용됩니다. 직접 전달한 필드가 프리셋보다 우선합니다. [프리셋 적용](#apply-a-preset)을 참고하세요. |
| `variables` | object | 기본값이 없는 프리셋 자리 표시자의 값입니다. 예: `{ "BRAND": "Acme" }`. |
| `palette_id` | string | [`list_palettes`](#list_palettes)의 팔레트입니다. 팔레트의 색이 프롬프트에 이름으로 들어갑니다. |
| `moodboard_id` | string | [`list_moodboards`](#list_moodboards)의 무드보드입니다. 무드보드의 설명이 프롬프트에 더해지고, 이미지는 스타일 레퍼런스로 모델에 전달됩니다. |
| `structured` | object | 프롬프트에 더해지는 구조화된 세부 정보입니다. `person`(나이, 성별, 표정, 눈, 머리, 직업), `styling`(미적 스타일, 색감, 조명, 분위기), `setting`(공기감, 배경, 시대), `camera`(형식, 프레이밍, 움직임), `lens`(조리개, 초점 거리), `mood`입니다. |
| `described_references` | array | 사진은 없지만 이름으로 부를 수 있는 대상을 위한 `{ name, description }` 항목 최대 10개입니다. 각 항목은 프롬프트의 한 줄이 되므로, 프롬프트에 쓴 이름이 설명된 대상으로 모델에 전달됩니다. |
| `connected_references`, `reference_order` | array | 고급 옵션입니다. 편집기 자체 형식으로 라벨과 순서를 붙인 레퍼런스로, 최대 14개입니다. |
| `base_image_url`, `mask_url` | string | 인페인팅용으로, 편집할 이미지와 마스크입니다. 흰색 부분은 바뀌고 검은색 부분은 유지됩니다. 마스크 영역을 다시 생성해 이미지 위에 다시 배치합니다. |
| `strength` | number | 인페인팅용으로, 0(미세하게)~1(완전히 다시 그림)이며, 지원하는 모델에서 씁니다. |
| `guidance_scale` | number | 0~20이며, 지원하는 모델에서 씁니다. |

**반환값:** 작업 ID입니다. MCP Apps를 지원하는 클라이언트에서는 이미지가 준비되면 카드에 표시됩니다.

### 한 번의 호출로 여러 이미지
- **`count`**는 같은 요청으로 이미지를 최대 4장 만듭니다. 이미지마다 별도의 작업입니다.
- **`models`**는 같은 요청을 모델 2~4개에서 실행합니다. 둘 다 쓰면 `count`는 모델당 개수이므로, 한 번의 호출로 최대 8장을 만듭니다.
- **응답**은 모든 작업 ID를 모델별로 묶어 배치 ID와 함께 나열합니다. 카드와 `jobId`는 첫 번째 작업을 따릅니다.
- **모델마다 자체 설정을 받습니다.** 화면 비율, 해상도 같은 옵션은 단일 호출과 마찬가지로 각 모델에 맞춰집니다.
- **배치는 전체로 청구됩니다.** Nodaro는 배치 전체에 대해 잔액을 확인하고, 모든 작업을 만들거나 하나도 만들지 않습니다. 오류 응답은 아무것도 청구되지 않았다는 뜻입니다.
- **거부.** 1~4를 벗어난 `count`, 4개를 넘는 모델, `model`과 `models`를 함께 쓴 경우, 이미지 모델이 아닌 모델이 들어 있는 목록은 거부됩니다. 오류가 문제를 알려 줍니다. `models`의 모델 ID는 대소문자와 관계없이 일치합니다.

### 프리셋 적용
`presetId`는 기본 프리셋이나 저장한 프리셋을 편집기가 적용하는 방식 그대로 적용합니다.

- 프리셋의 프롬프트와 프롬프트 앞뒤 텍스트가 사용됩니다. 내 `prompt`는 그 텍스트로 감싸집니다.
- `{name || default}` 형식으로 쓴 자리 표시자는 기본값으로 채워집니다.
- 프리셋의 스타일과 네거티브 프롬프트는 모델이 받는 방식으로 전달됩니다.
- 프리셋이 정하지 않은 설정은 편집기의 기본값을 받습니다. 저장한 이미지 기본값은 프리셋 호출에 적용되지 않습니다.

`{BRAND}`처럼 기본값이 없는 자리 표시자는 `variables`에 값이 있어야 합니다. 값이 없으면 도구가 빠진 값을 알려 줍니다. `count`를 쓰면 도구는 프리셋 요청으로 그 수만큼 이미지를 만듭니다. `models`를 쓰면 모델마다 프리셋을 한 번씩 적용합니다. 아직은 `presetId`를 `palette_id`나 `moodboard_id`와 함께 쓸 수 없으며, 호출이 거부됩니다.

### 팔레트와 무드보드
`palette_id`는 팔레트의 모든 색을 일상적인 이름과 16진수 코드로 프롬프트에 넣습니다. `moodboard_id`는 무드보드의 설명을 프롬프트에 더하고, 이미지를 내 레퍼런스 뒤에 모델의 한도까지 스타일 레퍼런스로 보냅니다. 일부 이미지가 들어가지 못하면 응답에 그렇게 나옵니다. 팔레트와 무드보드는 아래 도구로 만들고 찾으세요.

## `modify_image`
프롬프트로 기존 이미지를 편집, 스타일 변경, 변환합니다. 색 바꾸기, 배경 교체, 스타일 적용, 프레임 확장이나 일부 다시 그리기를 할 수 있습니다. [**이미지 수정**](https://nodaro.ai/docs/nodes/image/modify-image) 노드와 같은 방식으로 작동합니다.

**권한:** `workflows:execute`. **크레딧:** 모델의 가격입니다.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `prompt` | string | **필수.** 원하는 변경으로, 최대 8,000자입니다. |
| `image_url` 또는 `image_asset_id` | string | **필수, 둘 중 하나.** 공개 `https` URL, 또는 결과가 이미지인 Nodaro 작업의 id입니다. |
| `model` | string | 기본값은 `gpt-image-2-5-flare-i2i`입니다. 여러 번 편집해도 얼굴이나 캐릭터를 같게 유지하거나 이미지에 텍스트를 넣으려면 `nano-banana-pro`를, 텍스트가 많은 편집에는 `gpt-image-2-i2i`를 쓰세요. 알 수 없는 id는 기본값으로 대체됩니다. |
| `aspect_ratio` | string | 출력의 모양입니다. `auto`는 모든 모델에서 사진의 형태를 유지합니다. 자체 `auto` 설정이 있는 모델은 그 값을 받고, 다른 모델은 원본 이미지에 가장 가까운 지원 비율을 사용합니다. 그 밖의 지원하지 않는 값은 대체됩니다. |
| `resolution` | string | 지원하는 값 중 가장 가까운 값이 쓰입니다. |
| `quality` | string | 이 설정이 있는 모델에서 `medium`, `high`, `basic` 중 하나입니다. |
| `negative_prompt` | string | 피할 내용으로, 최대 2,000자입니다. |
| `structured` | object | `generate_image`와 같은 구조화된 세부 정보입니다. |

**반환값:** 작업 ID입니다.

## `image_to_image`
프롬프트로 이미지를 변환하며, 마스크를 쓰거나 여러 레퍼런스를 이미지 하나에 합치는 옵션이 있습니다.

**권한:** `workflows:execute`. **크레딧:** 모델의 가격입니다.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `prompt` | string | **필수.** 변환 내용으로, 최대 2,000자입니다. |
| `image_url` 또는 `image_asset_id` | string | 소스 이미지입니다. |
| `model` | string | 기본값은 `gpt-image-2-5-flare-i2i`입니다. 그 밖에 `nano-banana`, `nano-banana-2`, 사실적인 편집용 `flux-kontext`, 창의적인 다시 그리기용 `gpt-image-i2i`, `flux-i2i`, `ideogram-remix`가 있습니다. 알 수 없는 id는 기본값으로 대체됩니다. |
| `reference_image_urls` | array | 여러 레퍼런스를 받는 모델에서 쓰는 추가 레퍼런스 이미지 최대 13개로, URL이나 Nodaro id로 넣습니다. |
| `mask_url` | string | 인페인팅 마스크입니다. 흰색 부분은 바뀌고 검은색 부분은 유지됩니다. |
| `strength` | number | 0(미세하게)~1(완전히 다시 그림)입니다. |
| `aspect_ratio` | string | 출력의 모양입니다. |
| `resolution` | string | `1K`, `2K`, `4K` 중 하나입니다. |
| `quality` | string | `medium`, `high`, `basic` 중 하나입니다. |
| `seed` | integer | 지원하는 모델에서 쓰는 고정 시드입니다. |
| `negative_prompt` | string | 피할 내용으로, 최대 5,000자입니다. |

**반환값:** 작업 ID입니다.

## `edit_image`
이미지를 업스케일하거나, 배경을 제거하거나, 부분 편집을 적용합니다. 연산은 `model`로 고르세요.

**권한:** `workflows:execute`. **크레딧:** 아래 표에 나온 연산의 가격입니다.

| `model` | 연산 | 필요한 것 |
| --- | --- | --- |
| `recraft-upscale`(기본값) | 선명한 업스케일 | 이미지 |
| `topaz-image-upscale` | 1배, 2배, 4배 업스케일 | 이미지와 `upscale_factor` |
| `recraft-remove-bg` | 배경을 제거하고 투명도가 있는 PNG를 반환 | 이미지 |
| `nano-banana-edit` | 마스크 안이나 프레임 밖을 프롬프트로 편집 | 이미지, `prompt`, 선택 사항인 `mask_url` |
| `grok-upscale` | 이전 Grok 생성 결과의 창의적인 업스케일 | `task_id` |
| `grok-2-segment` | 이전 Grok Imagine 2 이미지의 이름 붙은 영역 지도, 무료 | `task_id` |
| `grok-2-edit` | 이전 Grok Imagine 2 이미지를 프롬프트로 편집하며, 일부 영역만 편집할 수도 있음 | `task_id`, `prompt`, 선택 사항인 `mask_indexes` |

| Model | Maker | Modes | Credits | Details |
| --- | --- | --- | --- | --- |
| [Recraft Crisp Upscale](https://nodaro.ai/docs/models/image/recraft-crisp-upscale) | Recraft | Image upscaling | 3 | Light-weight image upscale (Recraft Crisp). |
| [Topaz Image Upscale](https://nodaro.ai/docs/models/image/topaz-image-upscale) | Topaz | Image upscaling | 28부터 | High-quality image upscale at 1x (enhance only), 2x or 4x. Best for production-ready output. |
| [Recraft Remove BG](https://nodaro.ai/docs/models/image/recraft-remove-bg) | Recraft | Background removal | 4 | Remove image background. Cheap utility. |
| [Nano Banana Edit](https://nodaro.ai/docs/models/image/nano-banana-edit) | Google | Image editing | 11 | Image-to-image edits via Google's Nano Banana family. Good general-purpose editor. |
| [Grok Upscale](https://nodaro.ai/docs/models/image/grok-upscale) | xAI | Image upscaling | 28 | Upscale a previously-generated Grok image. Requires the prior task id. |
| [Grok Imagine 2 Segment Map](https://nodaro.ai/docs/models/image/grok-imagine-2-segment-map) | xAI | Image editing | 0 | FREE semantic segment map of a prior grok-2 generation — named region masks whose indexes feed grok-2-edit's region targeting. |
| [Grok Imagine 2 Edit](https://nodaro.ai/docs/models/image/grok-imagine-2-edit) | xAI | Image editing | 11 | Prompt-edit a prior grok-2 generation by task id. Optional mask indexes (from grok-2-segment) restrict the edit to named regions. |

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `model` | string | 위 표의 연산입니다. 기본값은 `recraft-upscale`입니다. |
| `image_url` 또는 `image_asset_id` | string | 세 가지 Grok 연산을 제외한 모든 연산의 소스 이미지입니다. |
| `prompt` | string | `nano-banana-edit`과 `grok-2-edit`에 필수입니다. 최대 2,000자입니다. |
| `mask_url` | string | `nano-banana-edit`용으로, 흰색 부분이 바뀝니다. |
| `upscale_factor` | string | `topaz-image-upscale`용으로, `1`, `2`, `4` 중 하나입니다. 기본값은 `2`입니다. |
| `target_resolution` | string | `topaz-image-upscale`의 업스케일 배율을 정하는 이전 방식입니다. `2K`는 `2`, `4K`와 `8K`는 둘 다 `4`입니다. 대신 `upscale_factor`를 쓰세요. |
| `task_id` | string | Grok 연산용으로, 이전 Grok 생성의 작업 id입니다. `get_job`이 생성 출력에서 `providerTaskId`로 반환합니다. |
| `mask_indexes` | array | `grok-2-edit`용으로, `grok-2-segment` 실행에서 받은, 바꿀 영역의 `index` 값입니다. |
| `negative_prompt`, `seed`, `style` | | 선택 사항이며, 이를 쓰는 연산에서 씁니다. |

Grok Imagine 2 이미지의 일부 영역만 편집하려면 두 단계로 작업하세요. 먼저 이미지의 `task_id`로 `grok-2-segment`를 실행하고, 작업의 `segments`에서 이름 붙은 영역을 읽으세요. 그다음 같은 `task_id`, 프롬프트, 바꿀 영역의 `mask_indexes`로 `grok-2-edit`을 실행하세요. 영역 지도는 무료입니다.

**반환값:** 작업 ID입니다.

## `generate_mask`
“the person”(인물)이나 “sky and clouds”(하늘과 구름)처럼 설명한 대상의 흑백 마스크를 만듭니다. 흰색이 선택된 영역입니다. 마스크는 `image_to_image`, `edit_image`, 또는 `generate_image`의 인페인팅 필드에 쓰세요. [**마스크 생성**](https://nodaro.ai/docs/nodes/image/generate-mask) 노드와 같은 방식으로 작동합니다.

**권한:** `workflows:execute`. **크레딧:** 55크레딧입니다.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `prompt` | string | **필수.** 선택할 대상으로, 최대 500자입니다. |
| `image_url` 또는 `image_asset_id` | string | 소스 이미지입니다. |
| `threshold` | number | 감지 신뢰도로, 0~1입니다. 기본값은 `0.3`입니다. |

**반환값:** 작업 ID입니다. 결과는 PNG 마스크입니다.

## `image_collage`
이미지 2~30개를 큰 이미지 하나에 넣습니다. 어떤 이미지도 잘리지 않습니다. `smart` 레이아웃은 각 이미지를 원래 모양대로 행에 배치하고, `grid` 레이아웃은 같은 크기의 칸을 쓰며 빈 공간을 배경색으로 채웁니다. [**이미지 콜라주**](https://nodaro.ai/docs/nodes/image/image-collage) 노드와 같은 방식으로 작동하며, 스토리보드와 콘택트 시트에 알맞습니다.

**권한:** `workflows:execute`. **크레딧:** `2K`는 22크레딧, `4K`는 44크레딧입니다.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `images` | array | **필수.** 항목 2~30개로, 각각 `{ url }` 또는 `{ asset_id }`입니다. 항목에 smart 레이아웃의 상대 크기인 `size`(`0` 자동, `1` 크게, `2` 중간, `3` 작게)와, 최대 80자의 캡션인 `label`을 더할 수 있습니다. |
| `layout` | string | `smart`(기본값) 또는 `grid`입니다. |
| `resolution` | string | 긴 변의 길이로, `2K` 또는 `4K`(기본값, 3,840픽셀)입니다. |
| `aspect_ratio` | string | `16:9`나 `9:16` 같은 임의의 `W:H`입니다. 기본값은 `4:3`입니다. `grid`에서는 정확히 맞추고, `smart`에서는 목표값이며 높이는 행에 따라 정해집니다. |
| `gap` | integer | 이미지 사이와 주위의 간격으로, 0~200픽셀입니다. 기본값은 `24`입니다. |
| `background_color` | string | `#RRGGBB` 색상입니다. 기본값은 `#ffffff`입니다. |
| `numbered` | boolean | `images`의 순서대로 각 이미지 모서리에 1, 2, 3 같은 번호를 찍습니다. |
| `badge_position` | string | 번호와 라벨을 넣을 모서리로, `top-left`(기본값) 또는 `top-right`입니다. |

**반환값:** 작업 ID입니다.

## `image_overlay`
기본 이미지 위에 레이어 1~12개를 픽셀 단위로 정확하게 배치합니다. 로고, 잘라 낸 이미지, 텍스트, QR 코드, 도형입니다. AI 모델이 실행되지 않으므로 결과는 매번 같습니다. [**이미지 오버레이**](https://nodaro.ai/docs/nodes/image/image-overlay) 노드와 같은 방식으로 작동하며, 모든 옵션은 그 노드 페이지에 설명되어 있습니다.

**권한:** `workflows:execute`. **크레딧:** 11크레딧이며, [**이미지 오버레이**](https://nodaro.ai/docs/nodes/image/image-overlay#credits) 노드와 마찬가지로 `variants`의 추가 플랫폼 크기마다 조금 더 듭니다.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `image_url` 또는 `image_asset_id` | string | 기본 이미지입니다. |
| `layers` | array | **필수.** 레이어 1~12개입니다. 아래 레이어 필드를 참조하세요. 레이어에 `z_index`를 설정하지 않으면 배열 순서가 쌓는 순서입니다. |
| `canvas` | object | 출력 크기로, 16~8,192픽셀의 `width`와 `height`, 그리고 `background_color`입니다. 기본 이미지는 `base_fit`인 `contain` 또는 `cover`로 그 안에 배치됩니다. 생략하면 기본 이미지의 크기를 유지합니다. |
| `variants` | array | 한 번에 렌더링할 추가 플랫폼 크기입니다. `youtube-thumbnail`, `youtube-banner`, `linkedin-company`, `linkedin-personal`, `x-header`, `facebook-cover`, `instagram-post`, `instagram-portrait`, `instagram-story`, `open-graph`, `presentation`, `a4-print`. |
| `qr_text` | string | `qr.fromInput`이 `true`인 모든 QR 레이어를 채웁니다. |
| `mask_mode` | string | 작업이 `maskUrl`로 함께 반환하는 마스크로, 흰색 부분은 바뀔 수 있습니다. `around`(기본값, AI 마무리를 위한 레이어 주위의 테두리), `layers`, `outside`, `none` 중 하나입니다. |
| `mask_spread` | integer | `around` 테두리의 너비로, 1~400픽셀입니다. 기본값은 `48`입니다. |
| `output_format` | string | `png`(기본값, 투명도 유지), `jpg`, `webp` 중 하나입니다. |

주요 레이어 필드는 다음과 같습니다.

| 레이어 필드 | 설명 |
| --- | --- |
| `kind` | `image`(기본값, `url` 또는 `asset_id` 필요), `text`, `qr`, `shape` 중 하나입니다. |
| `anchor` | `top-left`부터 `bottom-right`까지 9개 위치 중 하나입니다. 기본값은 `center`입니다. |
| `x`, `y` | 기준점으로부터의 오프셋으로, 기본 이미지 너비와 높이에 대한 퍼센트입니다. 오른쪽이나 아래쪽 기준점에서 음수 값을 주면 레이어가 안쪽으로 이동합니다. |
| `width`, `height` | 기본 이미지 너비와 높이에 대한 퍼센트입니다. 기본 너비는 25%입니다. 높이를 설정하지 않으면 레이어의 모양에 따라 정해집니다. |
| `opacity`, `rotation`, `blend` | 0~1의 불투명도, 도 단위의 회전, 그리고 `over`, `multiply`, `screen` 중 하나인 블렌드입니다. |
| `fit`, `shadow`, `rounded_corners`, `z_index` | 레이어가 상자를 채우는 방식(`contain`, `cover`, `stretch`), 그림자, 둥근 모서리, 쌓는 순서입니다. |
| `effects` | 이미지 레이어 전용으로, 원형 마스크, 페더, 외곽선, 글로입니다. |
| `text` | 텍스트 레이어용입니다. `text`, `fontId`(`inter`, `montserrat`, `space-grotesk`, `playfair-display`, `oswald`, `bebas-neue`, `anton`, `pacifico`, `rubik`, `heebo` 중 하나이며, `rubik`과 `heebo`는 히브리어용), 기본 이미지 높이에 대한 퍼센트인 `fontSize`, `fontWeight`, `color`, `align`, `letterSpacing`, `lineHeight`, `uppercase`, 외곽선, 배경 상자입니다. |
| `qr` | QR 레이어용입니다. 인코딩할 `text` 또는 `fromInput: true`, 그리고 색상과 여백입니다. |
| `shape` | 도형 레이어용입니다. `rect`, `rounded`, `pill`, `circle`, `ribbon`, `triangle`, `diamond`, `hexagon`, `star`, `burst`, `arrow` 중 하나이며, 색상과 외곽선을 지정합니다. |

오른쪽 아래 모서리의 워터마크는 `anchor: "bottom-right"`, `x: -4`, `y: -6`, `width: 12`입니다. SVG 로고는 목표 크기에서 선명하게 렌더링됩니다.

**반환값:** 작업 ID입니다. 결과에는 이미지, `maskUrl`, 이미지의 `width`와 `height`, 그리고 `{ id, label, width, height, url }` 목록인 `variants`가 담깁니다.

## `suggest_overlay_placement`
레이어 하나를 기본 이미지의 어디에 놓을지 비전 모델에 묻습니다. 모델은 이미지를 보고 레이어가 얼굴, 주 피사체, 복잡한 질감을 가리지 않게 합니다. 아무것도 합성하지 않으므로, 답을 `image_overlay`에 전달하세요.

**권한:** `workflows:execute`. **크레딧:** 이미지 설명 1회로, `image_to_text`의 가격입니다.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `image_url` 또는 `image_asset_id` | string | 기본 이미지입니다. |
| `intent` | string | 로고, 헤드라인, 가격 배지, QR 코드처럼 레이어가 무엇인지로, 최대 300자입니다. 기본값은 로고입니다. |
| `layer_aspect` | number | 레이어의 너비를 높이로 나눈 값으로, 0.05~20입니다. 기본값은 `1`로, 정사각형입니다. |
| `safe_area` | object | 항상 보이는 영역으로, 캔버스에 대한 비율인 `x`, `y`, `w`, `h`입니다. 레이어는 그 안에 머뭅니다. |

**반환값:** `image_overlay`와 같은 퍼센트 단위의 `anchor`, `x`, `y`, `width`, 그리고 한 문장짜리 `reason`입니다.

## `image_to_text`
비전 모델로 이미지를 설명하거나 이미지에 관한 질문에 답합니다. 캡션, 대체 텍스트, 장면 분석, 또는 “list all the text in the image”(이미지의 텍스트를 모두 나열해 줘) 같은 구체적인 질문에 쓰세요. [**이미지 설명**](https://nodaro.ai/docs/nodes/image/describe-image) 노드와 같은 방식으로 작동합니다.

**권한:** `workflows:execute`. **크레딧:** 기본 모델로 4크레딧이며, 가격은 모델 등급을 따릅니다.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `image_url` 또는 `image_asset_id` | string | 설명할 이미지입니다. |
| `detail_level` | string | `brief`, `detailed`(기본값), `comprehensive` 중 하나입니다. |
| `custom_prompt` | string | 일반적인 설명 대신 묻는 구체적인 질문으로, 최대 2,000자입니다. |
| `llmModel` | string | 비전 모델로, 도구가 나열하는 LLM id 중 하나입니다. |
| `reasoning_effort` | string | `none`부터 `max`까지입니다. `xhigh`와 `max`는 한 등급 높게 청구됩니다. Claude 모델에서는 어떤 강도든 모델 제작사의 자체 서비스에서 실행되며 한 등급 높게 청구됩니다. |
| `advanced_mode`, `temperature`, `max_tokens` | | Gemini와 Claude 모델용이며, [프롬프트 도구](https://nodaro.ai/docs/mcp/tools/prompts-and-text#enhance_prompt)와 같습니다. 한 등급 높게 청구됩니다. |

**반환값:** 작업 ID입니다. 텍스트는 작업 출력에 있으며, 카드에 **Copy**(복사) 버튼과 함께 표시됩니다.

## `save_image_defaults`
선호하는 이미지 설정을 저장해, 이후 `generate_image` 호출에서 따로 지정하지 않으면 그 설정을 씁니다. 전달한 필드만 바뀝니다. MCP Apps를 지원하는 클라이언트에서는 이미지 카드의 **Save as default**(기본값으로 저장) 칩이 이 도구를 호출합니다.

**권한:** `workflows:execute`. **크레딧:** 무료.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `model` | string 또는 null | 내 기본 모델입니다. `null`이면 지우고 카탈로그 기본값으로 돌아갑니다. |
| `aspect_ratio` | string 또는 null | 내 기본 화면 비율입니다. |
| `resolution` | string 또는 null | 내 기본 해상도입니다. |
| `quality` | string 또는 null | 내 기본 품질입니다. |

**반환값:** 확인 메시지입니다.

## `list_palettes`
내 컬러 팔레트를 최신순으로 나열합니다. 이름, 일상적인 이름과 16진수 코드로 표시한 각 색, 메모, ID가 담깁니다. ID를 `generate_image`에 `palette_id`로 넘기세요.

**권한:** `assets:read`. **크레딧:** 무료.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `cursor` | string | 이전 페이지의 커서입니다. |

**반환값:** 팔레트 한 페이지로, `GET /v1/palettes`와 같은 목록입니다.

## `save_palette`
팔레트를 만들거나 수정합니다. 만들려면 `name`과 `colors`를 넘기세요. 팔레트를 수정하려면 `id`와 바뀌는 필드만 넘기세요.

**권한:** `assets:write`. **크레딧:** 무료.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `id` | string | 수정할 팔레트입니다. 팔레트를 만들 때는 생략하세요. |
| `name` | string | 1~80자입니다. 만들 때 필수입니다. |
| `colors` | array | `#RRGGBB` 형식의 색 2~12개입니다. 만들 때 필수입니다. 색은 대문자로 저장됩니다. |
| `description` | string | 메모로, 최대 500자입니다. |

**반환값:** ID가 포함된 팔레트입니다. 이 도구로는 팔레트를 삭제할 수 없습니다. 앱, CLI 또는 API에서 삭제하세요.

## `list_moodboards`
내 무드보드를 최신순으로 나열합니다. 이름, 이미지 수, 설명, ID가 담깁니다. `id`를 넘기면 각 이미지의 링크와 캡션을 포함한 무드보드 하나를 반환합니다. ID를 `generate_image`에 `moodboard_id`로 넘기세요.

**권한:** `assets:read`. **크레딧:** 무료.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `id` | string | 이 무드보드 전체를 읽습니다. |
| `cursor` | string | 이전 페이지의 커서입니다. |

**반환값:** 무드보드 한 페이지 또는 무드보드 하나로, `GET /v1/moodboards`와 `GET /v1/moodboards/:id`가 반환하는 것과 같습니다.

## `save_moodboard`
무드보드를 만들거나 수정합니다. 만들려면 `name`과 `images`를 넘기세요. 무드보드를 수정하려면 `id`와 바뀌는 필드만 넘기세요.

**권한:** `assets:write`. **크레딧:** 무료.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `id` | string | 수정할 무드보드입니다. 무드보드를 만들 때는 생략하세요. |
| `name` | string | 1~80자입니다. 만들 때 필수입니다. |
| `description` | string | 최대 1,000자입니다. 실행할 때 이 내용이 프롬프트에 들어갑니다. |
| `images` | array | `{ url, caption }` 항목 1~12개입니다. 각 `url`은 이미지 링크이거나 내 Nodaro 이미지의 ID입니다. 캡션은 선택 사항이며 최대 200자입니다. 만들 때 필수입니다. 수정할 때 `images`는 모든 이미지를 교체합니다. |

**반환값:** ID가 포함된 무드보드입니다. 이미지는 링크로 보관되며 복사되지 않습니다. 이 도구로는 무드보드를 삭제할 수 없습니다.

## 자주 묻는 질문

### generate_image는 기본으로 어떤 모델을 쓰나요?

GPT Image 2입니다. 바꾸려면 list_models의 다른 id를 model에 넣으세요. 예를 들어 읽기 쉬운 텍스트에는 nano-banana-pro, 빠른 반복 작업에는 gpt-image-2-5-flare를 씁니다. 알 수 없는 id는 오류 없이 기본값으로 대체됩니다.

### 여러 이미지에서 같은 인물을 유지하려면 어떻게 하나요?

reference_image_urls에 그 인물의 이미지를 URL이나 Nodaro id로 최대 14개 넣으세요. 응답에서 몇 개가 첨부되었는지 확인할 수 있습니다. 저장한 캐릭터라면 get_character가 반환하는 승인된 포트레이트를 넣으세요.

### MCP로 배경을 제거하거나 이미지를 업스케일하려면 어떻게 하나요?

edit_image를 사용하세요. 투명한 PNG를 만들려면 model을 recraft-remove-bg로, 업스케일하려면 recraft-upscale이나 topaz-image-upscale로 설정하세요. 어느 것도 프롬프트가 필요 없습니다.

### 어시스턴트가 AI 없이 이미지에 로고나 텍스트를 넣을 수 있나요?

네. image_overlay는 모델 없이 기본 이미지 위에 이미지, 텍스트, QR 코드, 도형을 픽셀 단위로 정확하게 배치하며, 11크레딧이 듭니다. 먼저 suggest_overlay_placement로 로고를 놓을 위치를 제안받을 수 있습니다.

### MCP로 이미지를 생성하는 데 크레딧이 얼마나 드나요?

편집기와 같습니다. 가격은 모델과 그 해상도나 품질에 따라 다르며, list_models와 각 모델 페이지에 정확한 크레딧이 나와 있습니다.