# 모델, 크레딧, 프리셋

> AI 어시스턴트에서 Nodaro 모델의 기능과 크레딧 가격을 나열하고, 잔액과 지출을 읽고, 노드 프리셋을 찾고 저장하고 적용하세요.

Source: https://nodaro.ai/ko/docs/mcp/tools/models-and-credits

**모델, 크레딧, 프리셋 도구**는 어시스턴트가 생성에 맞는 모델을 고르고 비용을 제대로 치르도록 돕습니다. `list_models`는 모든 모델을 기능과 가격과 함께 반환하고, `check_balance`와 `credit_transactions`는 Nodaro Cloud에서 내 크레딧을 보여 주며, 프리셋 도구는 노드의 미리 만들어진 구성을 찾고, 저장하고, 적용합니다.

## `list_models`
이 Nodaro 인스턴스에서 사용할 수 있는 모델을 종류와 제작사별로 묶어, 모델마다 기능 사양과 함께 반환합니다. 사용자가 모델을 고르지 않았다면 생성 도구보다 먼저 호출하세요.

**권한:** 없음, 항상 표시됩니다. **크레딧:** 무료.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `kind` | string | `image`, `video`, `audio` 중 하나입니다. |
| `mode` | string | 기능 하나로, 예를 들어 `t2i`(텍스트를 이미지로), `i2i`, `edit`, `upscale`, `remove-bg`, `i2v`(이미지를 동영상으로), `t2v`, `v2v`, `extend`, `motion-transfer`, `lip-sync`, `video-upscale`, `tts`, `music`, `sfx`, `stt`, `voice-design`, `voice-changer`, `voice-changer-pro`, `isolation`, `dubbing`, `forced-alignment`, `video-analysis`, `video-audit`입니다. |
| `family` | string | 제작사 하나로, 예를 들어 `Google`, `OpenAI`, `Bytedance`입니다. |
| `featuredOnly` | boolean | Nodaro 팀이 고른 등급별 최고 모델만 반환합니다. |

**반환값:** 모델마다 그 모델을 만든 회사인 `maker`(`{ id, name }`)와 화면 비율, 해상도, 품질, 길이, 기능이 담기며, 크레딧이 있는 에디션에서는 각 베리언트의 가격도 담깁니다. `recommendations` 목록은 이미지 속 텍스트, 가장 저렴한 사실적 이미지처럼 흔한 용도에 가장 좋은 모델을 알려 줍니다. Seedance 2.0처럼 모델 전용 프롬프트 조언이 있는 모델에는 `promptTips`도 있습니다. 동영상을 생성하기 전에 적용할 짧은 규칙입니다. 제작사 로고(`logoUrl`)는 이 응답에 없습니다. 모델 선택기를 그리는 앱을 위한 것이며, `GET /v1/models`가 반환합니다.

모든 모델은 [모델 카탈로그](https://nodaro.ai/docs/models)에도 페이지가 있으며, 같은 가격과 더 자세한 내용이 실려 있습니다.

## `check_balance`
내 크레딧 잔액을 구독 크레딧과 충전 크레딧으로 나누고 합계와 함께 반환합니다. 일일 사용 한도, 월간 지급량, 내 등급, 결제 기간이 끝나는 날짜도 반환합니다.

**권한:** `credits:read`. **크레딧:** 무료. **Nodaro Cloud 전용.**

이 도구에는 매개변수가 없습니다.

**반환값:** 잔액과 요금제 정보입니다.

- **먼저 사용되는 크레딧.** 구독 크레딧이 먼저 사용됩니다. 연간 요금제에서도 매달 요금제의 월간 지급량으로 초기화되며, 쓰지 않은 크레딧은 이월되지 않습니다. 충전 크레딧은 구매 후 12개월 동안 유효합니다.
- **종량제.** `effectiveTier`가 `payg`이면 구독은 없지만 크레딧을 구매했다는 뜻입니다. 모든 모델을 쓸 수 있고, 워터마크와 일일 한도가 없습니다.
- **공유 결제 계정.** 결제 계정 하나가 모든 사람의 비용을 내는 배포 환경에서는, 연결된 클라이언트가 그 계정의 잔액을 읽을 수 없습니다. 이때 도구는 `payer_balance_jwt_only`로 응답합니다.

## `credit_transactions`
내 크레딧 내역 두 가지, 구매 내역과 사용 내역을 모두 나열합니다.

**권한:** `credits:read`. **크레딧:** 무료. **Nodaro Cloud 전용.**

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `limit` | integer | 1~100입니다. |
| `cursor` | string | 구매 내역 이전 페이지의 커서입니다. |
| `usage_cursor` | string | 사용 내역 이전 페이지의 커서입니다. |

**반환값:** 목록 두 개입니다.

- `data`: 구독, 충전, 환불 같은 최근 구매 내역입니다. 각 행에는 `type`, `amount_usd`, `credits_granted`, `tier`, `created_at`, 그리고 영수증이 있을 때 그 링크인 `receipt_url`이 있습니다. `next_cursor`로 페이지를 넘깁니다.
- `usage`: 최근 사용 내역이며, 내 크레딧으로 결제한 실행마다 행이 하나씩 있습니다. REST API가 `GET /v1/credits/transactions`로 나열하는 것과 같은 행이며, 필드도 같습니다. 한 페이지에는 최대 50행이 들어가며, `usage.next_cursor`를 `usage_cursor`에 넘겨 페이지를 넘깁니다.

사용 내역 행에서:

- `credits_charged`는 실행에 든 비용입니다. 크레딧이 아직 예약된 동안에는 `null`, 환불되면 `0`입니다. 지출을 계산하려면 이 필드를 합산하세요.
- `credits_reserved`(`credits_used`와 같음)는 실행이 시작될 때 예약된 크레딧입니다. 측정된 길이나 다시 렌더링 상한 때문에 예약액보다 적게 정산된 실행도 여기에는 예약액 전체가 표시됩니다.
- `action`, `provider`, `status`(`reserved`, `committed` 또는 `refunded`), `metadata`, `payer`, `workspaceId`는 REST API와 같습니다. [크레딧](https://nodaro.ai/docs/developers/api/credits#transaction-history)을 참고하세요.

## `list_node_presets`
노드 타입의 프리셋을 나열합니다. **캐릭터 보드**나 **시네마틱 인물 사진** 같은 기본 프리셋과 내가 저장한 프리셋이 담깁니다. 프리셋은 모델, 프롬프트, 설정을 담은, 이름이 붙은 노드 구성입니다. 프리셋 하나의 전체 구성은 `get_node_preset`으로 읽으세요.

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

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `nodeType` | string | 노드 타입으로, 예를 들어 `generate-image`입니다. 기본 프리셋을 포함하려면 필수입니다. |
| `source` | string | 기본 프리셋과 저장한 프리셋 모두는 `all`(기본값), 기본 프리셋만은 `factory`, 내 프리셋만은 `custom`입니다. `nodeType`이 없으면 도구는 내 프리셋과 힌트를 반환합니다. |

**반환값:** 각 프리셋의 이름, ID, 설명, 그룹입니다. 해당하는 경우 항목에 다음 필드도 들어 있습니다.

- `needsImage: true`와 `minReferences`: 프리셋이 그 수만큼 연결된 사진으로 동작합니다. 예: **레퍼런스 시트**, **인물 사진 변신**, 또는 `{image:N}`을 쓰는 템플릿. 그 수만큼 레퍼런스 이미지를 넣어 실행하세요.
- `favorite: true`: 내 즐겨찾기 프리셋입니다.
- `previewUrl`: 예시 이미지입니다. 앱 안의 어시스턴트는 이 값을 받지 않습니다.

## `get_node_preset`
프리셋 하나의 전체 구성을 반환합니다. 모델, 프롬프트, 화면 비율, 해상도, 품질, 네거티브 프롬프트, 그리고 프롬프트 앞뒤에 붙이는 텍스트가 담깁니다. 필드를 생성 도구에 복사하거나 ID를 `presetId`로 넘겨 프리셋을 그대로 적용할 때 사용하세요.

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

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `nodeType` | string | **필수.** 노드 타입으로, 예를 들어 `generate-image`입니다. |
| `presetId` | string | **필수.** `generate-image/location-board` 같은 기본 프리셋 ID 또는 내 프리셋의 ID입니다. |

**반환값:** `minReferences`, `needsImage`, `favorite`, `previewUrl`(프리셋에 이미지가 없으면 `null`)을 포함한 프리셋의 구성입니다. ID와 일치하는 프리셋이 없으면 오류를 반환합니다.

## `save_node_preset`
내 노드 프리셋을 저장합니다. 프리셋을 만들려면 `nodeType`, `name`, 그리고 `get_node_preset`이 반환하는 것과 같은 노드 구성인 `data`를 넘기세요. 프리셋을 수정하려면 `presetId`와 바뀌는 것만 넘기세요.

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

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `presetId` | string | 수정할 내 프리셋입니다. 프리셋을 만들 때는 생략하세요. |
| `nodeType` | string | 만들 때 필수입니다. 예: `generate-image`. |
| `name` | string | 만들 때 필수이며, 최대 120자입니다. 이름은 노드 타입 안에서 고유해야 하며, 그렇지 않으면 `name_taken`으로 응답합니다. |
| `description` | string | 선택 사항이며, 최대 500자입니다. |
| `data` | object | 노드 구성으로, 최대 64KB입니다. 만들 때 필수입니다. |
| `previewUrl` | string 또는 null | 예시 이미지입니다. 업로드나 완성된 결과처럼 이미 Nodaro에 저장된 이미지여야 합니다. `null`은 이미지를 제거합니다. |
| `expectedUpdatedAt` | string | 내가 읽은 프리셋의 `updatedAt`입니다. 그 뒤로 프리셋이 바뀌었으면 수정이 `conflict`로 거부됩니다. |

**반환값:** 저장된 프리셋의 ID, 이름, `needsImage`, `minReferences`, `previewUrl`, `updatedAt`입니다. 같은 작업은 `POST /v1/node-presets`와 `PATCH /v1/node-presets/:id`로도 할 수 있습니다.

## `delete_node_preset`
내 프리셋 하나를 삭제합니다. 기본 프리셋은 삭제할 수 없습니다. 내 것이 아닌 프리셋은 `not_found`로 응답합니다.

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

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `presetId` | string | **필수.** 내 프리셋 중 하나입니다. |
| `expectedUpdatedAt` | string | 내가 읽은 프리셋의 `updatedAt`입니다. 그 뒤로 프리셋이 바뀌었으면 삭제가 거부됩니다. |

## `favorite_node_preset`
프리셋을 즐겨찾기에 추가하거나, `favorite: false`로 제거합니다. `generate-image/character-board` 같은 기본 프리셋이나 내 프리셋 모두 가능합니다. 즐겨찾기는 편집기의 프리셋 목록에서 맨 앞에 옵니다. 도구를 두 번 실행해도 한 번 실행한 것과 결과가 같습니다.

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

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `nodeType` | string | **필수.** 노드 타입으로, 예를 들어 `generate-image`입니다. |
| `presetId` | string | **필수.** `list_node_presets`에서 받은 프리셋 ID입니다. |
| `favorite` | boolean | 기본값은 `true`입니다. `false`는 프리셋을 즐겨찾기에서 제거합니다. |

프리셋 폴더, 프리셋 순서, 일괄 가져오기를 관리하는 도구는 없습니다. 이는 편집기의 목록을 정리하는 기능이며, REST API, SDK, CLI에서 제공합니다.

## 생성에 프리셋 적용
`generate_image`, `generate_video`, `generate_music`, `generate_speech`, `text_to_audio`는 `presetId`를 받습니다. Nodaro가 서버에서 프리셋의 구성을 적용하며, 직접 넘긴 필드는 모두 프리셋보다 우선합니다. 프리셋에 프롬프트가 들어 있으면 `prompt`를 생략해도 됩니다. 프리셋의 프롬프트 앞뒤 텍스트가 내 프롬프트를 감쌉니다. `generate_image`에서는 프리셋이 편집기가 적용하는 방식 그대로 적용되며, 기본값이 없는 자리 표시자에는 `variables`에 값이 있어야 합니다. [프리셋 적용](https://nodaro.ai/docs/mcp/tools/image#apply-a-preset)을 참고하세요.

`generate_speech`에서는 프리셋이 속도, 안정성, 스타일 같은 전달 방식을 조정하며, `text`는 여전히 필수입니다. 프리셋에 대한 자세한 내용은 [프리셋](https://nodaro.ai/docs/concepts/presets)을 읽어 보세요.

## 자주 묻는 질문

### 어시스턴트는 알맞은 모델을 어떻게 고르나요?

image와 t2i처럼 종류와 모드로 필터링해 list_models를 호출합니다. 응답에는 모든 모델의 화면 비율, 해상도, 길이, 기능, 가격과 함께, 이미지 속 텍스트에 가장 좋은 모델 같은 추천이 담깁니다.

### 어시스턴트가 내 크레딧이 얼마나 있는지 볼 수 있나요?

네. Nodaro Cloud에서 크레딧 권한을 허용했다면 가능합니다. check_balance는 구독 크레딧과 충전 크레딧, 내 등급, 일일 한도를 반환합니다.

### credit_transactions에서 생성마다 든 비용을 볼 수 있나요?

네. 구매 내역 외에 사용 내역도 반환하며, 내 크레딧으로 결제한 실행마다 행이 하나씩 있습니다. 지출을 계산하려면 이 행들의 credits_charged를 합산하세요. credits_reserved는 예약액이라 더 클 수 있습니다.

### MCP로 노드 프리셋을 사용하려면 어떻게 하나요?

list_node_presets로 ID를 찾은 다음, presetId를 generate_image, generate_video, generate_music, generate_speech, text_to_audio에 넘기세요. 직접 넘긴 필드가 프리셋보다 우선합니다.

### 어시스턴트가 나 대신 노드 프리셋을 저장할 수 있나요?

네. save_node_preset은 노드 구성으로 내 프리셋을 만들거나 수정하고, delete_node_preset은 프리셋을 삭제하며, favorite_node_preset은 프리셋을 즐겨찾기에 추가합니다. 세 도구 모두 assets:write 권한이 필요합니다.