모델, 크레딧, 프리셋

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

list_models

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

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

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

모든 모델은 모델 카탈로그에도 페이지가 있으며, 같은 가격과 더 자세한 내용이 실려 있습니다.

check_balance

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

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

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

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

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

credit_transactions

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

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

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

• 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와 같습니다. 크레딧을 참고하세요.

list_node_presets

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

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

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

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

get_node_preset

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

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

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

save_node_preset

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

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

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

delete_node_preset

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

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

favorite_node_preset

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

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

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

생성에 프리셋 적용

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

generate_speech에서는 프리셋이 속도, 안정성, 스타일 같은 전달 방식을 조정하며, text는 여전히 필수입니다. 프리셋에 대한 자세한 내용은 프리셋을 읽어 보세요.