모델 및 크레딧

client.models는 Nodaro 인스턴스가 제공하는 AI 모델 카탈로그를 반환하고, client.credits는 내 크레딧 잔액과 모든 모델의 가격을 반환합니다. client.billing은 판매 중인 요금제와 내 구독을 반환합니다. 이들을 함께 사용해 사용자가 고를 수 있는 모델과 실행마다 드는 비용을 보여 주세요. 이 메서드들은 크레딧 REST API와 같은 엔드포인트를 호출합니다. 가격과 잔액은 Nodaro Cloud에만 있으며, 셀프 호스팅한 Community Edition과 Business 에디션 설치에는 크레딧 시스템이 없습니다. 크레딧을 참고하세요.

메서드

client.models

models.list(opts?)

모델 카탈로그를 종류(이미지, 동영상, 오디오)와 제작사별로 묶어 반환합니다(GET /v1/models). 각 모델에는 기능, Nodaro Cloud에서의 크레딧 가격, 짧은 프롬프트 팁이 있습니다. 이 엔드포인트는 공개되어 있으며, 서버는 응답을 5분 동안 캐시합니다. MCP list_models 도구도 같은 데이터를 반환합니다.

list(opts?: {
  kind?: "image" | "video" | "audio"
  mode?: string
  family?: string
  featuredOnly?: boolean
}): Promise<ModelsListResult>

const catalog = await client.models.list({ kind: "video", mode: "i2v" })

for (const section of catalog.sections) {
  for (const family of section.families) {
    for (const model of family.models) {
      console.log(family.family, model.id, model.durations, model.pricing?.[0]?.credits)
    }
  }
}

결과에는 종류마다 하나씩 있으며 각각 모델의 families를 담은 sections, 자주 쓰는 용도별 모델 ID 목록인 recommendations, 그리고 totalModels가 있습니다. 각 모델에는 다음 필드가 있습니다.

오래된 서버는 maker와 logoUrl을 생략합니다.

for (const section of catalog.sections)
  for (const family of section.families)
    for (const m of family.models)
      console.log(m.id, m.maker?.name ?? family.family, m.logoUrl ?? "(no mark)")

같은 카탈로그가 모델 페이지에도 있습니다. 어떤 모델을 쓸지에 대한 조언은 모델 선택을 읽어 보세요.

client.credits

credits.balance()

내 크레딧 잔액과 등급을 반환합니다(GET /v1/user/credits). 로그인한 사용자가 없으면 UnauthorizedError를 발생시킵니다.

balance(): Promise<UserBalance>

const balance = await client.credits.balance()
console.log(`${balance.total} credits (${balance.effectiveTier})`)

무엇을 표시할지 정할 때는 tier보다 effectiveTier를 우선하세요.

credits.modelCosts(ids)

모델과 그 베리언트의 크레딧 가격을 한 번의 호출로 조회합니다(POST /v1/credits/model-costs). 앞에서부터 최대 50개의 식별자를 확인합니다.

modelCosts(ids: string[]): Promise<{
  data: Record<string, number>
  missing: string[]
  errors: string[]
}>

const { data, missing } = await client.credits.modelCosts([
  "nano-banana-pro",
  "nano-banana-pro:4K",
  "seedance-2-fast:8s:720p",
])
console.log(data["nano-banana-pro:4K"])
if (missing.length) console.warn("No price for:", missing)

• data는 가격이 있는 각 식별자를 크레딧 가격에 대응시킵니다.
• missing은 가격이 없는 식별자를 나열합니다. 이런 식별자에는 대시를 표시하세요.
• errors는 조회에 실패한 식별자를 나열합니다. 나머지 가격은 그대로 전달됩니다.

각 모델의 식별자는 models.list()의 pricing 필드와 각 모델 페이지에 있습니다. 품질, 해상도, 길이 같은 설정이 가격을 바꾸므로, 실행에 쓸 베리언트를 지정하세요. 실행 시점의 가격은 실행이 시작될 때 다시 확인되므로, 이 호출은 미리 보기입니다.

음성 모델은 텍스트 길이에 따라 가격이 정해집니다. 시작된 100자 블록마다의 식별자는 <model>:per-100-chars입니다. 예: elevenlabs-v4:per-100-chars. 음성을 길이로 가격 매기지 않는 설치에서는 이 식별자가 missing에 들어가므로, 응답으로 서버가 어떤 규칙으로 청구하는지도 알 수 있습니다.

요청은 전체로 가격을 계산한 뒤 한 번만 반올림합니다. 따라서 시작된 블록이 N개인 요청의 정확한 가격은 식별자 <model>:per-100-chars:<N>u이며, N은 8부터 모델의 요청당 상한까지입니다. N에 블록 가격을 곱한 값은 이보다 클 수 있습니다. 단위별로 청구되는 모든 실행은 같은 형태의 id로 가격을 확인합니다. <row>:<N>u는 그 행의 N단위 정확한 가격입니다. 예: apply-edl:4u, trim-video:5u, ltx-2.3-pro-retake:per-second:2.5u, elevenlabs-dubbing:3u. 보이스 체인저 Pro 변환 전체는 voice-changer-pro:<slot>,<slot>,…이며, @nodaro/shared의 voiceChangerProQuoteCreditId(slots)로 만듭니다. 단위별로 가격이 매겨지는 실행의 정확한 가격을 참고하세요.

credits.transactions(options?)

내 크레딧 거래 내역 한 페이지를 최신순으로 반환합니다(GET /v1/credits/transactions). Cloud 에디션 전용이며, 셀프 호스팅 설치는 404로 응답합니다.

transactions(options?: { limit?: number; cursor?: string }): Promise<CreditTransactionsPage>

페이지는 { data: CreditTransaction[], nextCursor }입니다. 더 읽을 행이 없으면 nextCursor는 null입니다.

어떤 금액을 읽을지. 실행은 먼저 크레딧을 홀드한 뒤 정산됩니다. 홀드의 전부 또는 일부가 청구되고, 나머지는 잔액으로 돌아옵니다. 지출을 알려면 credits_charged를 더하세요. 크레딧을 참고하세요.

let cursor: string | undefined
let spent = 0
do {
  const page = await client.credits.transactions({ limit: 50, cursor })
  for (const t of page.data) spent += t.credits_charged ?? 0
  cursor = page.nextCursor ?? undefined
} while (cursor)
console.log(`${spent} credits charged`)

credits.claimWelcomeOffer(input?)

환영 혜택에 대한 사용자의 “예”를 한 번에 기록합니다(POST /v1/credits/welcome-offer/claim). 마케팅 이메일 수신 동의를 기록한 다음, 그 동의와 함께 가입 무료 지급을 요청합니다. 결정은 여전히 악용 검사가 내리므로 grant를 읽으세요. 지급이 이미 결정된 계정은 동의만 기록됩니다. Nodaro Cloud 전용이며, 셀프 호스팅 인스턴스는 404로 응답합니다.

claimWelcomeOffer(input?: WelcomeOfferClaimInput): Promise<WelcomeOfferClaimResult>

이 메서드에는 supabaseAuth()로 로그인한 브라우저 세션이 필요합니다. 동의는 사람의 선택이기 때문입니다. API 토큰이나 OAuth 앱 토큰은 403을 받습니다. 배포 환경에서 혜택이 꺼져 있는 동안에는 호출이 409 welcome_offer_disabled로 응답하므로, balance().welcomeOffer가 있을 때만 혜택을 보여 주세요.

WelcomeOfferClaimInput은 collectSignupKeys()가 반환한 SignupKeys에 sourceApp을 더한 것입니다. sourceApp은 소문자, 숫자, 대시로 된 최대 40자의 내 앱 슬러그입니다. 형식이 잘못된 슬러그는 거부되지 않고 없는 것으로 저장됩니다.

WelcomeOfferState에는 필드가 세 개 있습니다. popupSeen(일회성 팝업이 표시됨), consentPending(계정에 크레딧이 있지만 아직 이메일 수신 동의가 남아 있음), credits(요청 시 지급되는 크레딧)입니다. 혜택에는 고정된 숫자 대신 credits 값을 보여 주세요. 이 값은 서버를 따릅니다.

credits.markWelcomeOfferSeen()

일회성 환영 팝업이 표시되었음을 기록하므로(POST /v1/credits/welcome-offer/seen), 모든 앱에서 welcomeOffer.popupSeen이 true가 됩니다. 다시 호출해도 아무것도 바뀌지 않습니다. 호출이 실패해도 팝업이 한 번 더 표시될 수 있을 뿐이므로 오류는 무시해도 됩니다. 규칙은 claimWelcomeOffer()와 같습니다.

markWelcomeOfferSeen(): Promise<{ ok: true }>

import { collectSignupKeys } from "@nodaro/sdk/signup-signals"

const { welcomeOffer } = await client.credits.balance()
if (welcomeOffer && !welcomeOffer.popupSeen) {
  showPopup({ credits: welcomeOffer.credits }) // the server's figure, never a constant
  void client.credits.markWelcomeOfferSeen().catch(() => {})
}

// On "Yes":
const keys = await collectSignupKeys()
const { grant, credits } = await client.credits.claimWelcomeOffer({ ...keys, sourceApp: "my-app" })
if (grant === "granted") showToast(`Your ${credits} free credits are ready`)

client.billing

client.billing은 판매 중인 요금제와 가격, 호출자의 구독, 배포 환경의 결제 방식을 읽습니다. 구매, 요금제 변경, 결제 설정은 Nodaro 앱에서 합니다. 그 경로는 API 토큰과 앱 토큰을 거부하므로 SDK에는 해당 메서드가 없습니다. 대신 사용자를 앱의 요금제 페이지로 안내하세요.

// A pricing screen: works signed out.
const { data: plans, topUps } = await client.billing.plans()

// Mark the plan the signed-in account is on.
const { effectiveTier } = await client.billing.subscription()
const current = plans.find((p) => p.id === effectiveTier) // undefined: pay-as-you-go, or a tier not on sale

BillingPlan에는 다음 필드가 있습니다.

topUps는 크레딧 팩으로, { id, credits, price }이며 작은 것부터 나옵니다. 지금 가격을 알릴 수 없으면 price는 null입니다. topUpRange({ min, max, currency })는 앱에서 팩과 같은 비율로 크레딧으로 충전할 수 있는 정수 금액의 범위입니다. 요금제 없이 크레딧을 구매하는 방법은 구독 없는 API를 참고하세요.

모델과 가격 표시

모델마다 옆에 가격을 보여 주는, 노드 하나용 모델 선택기를 만드세요.

const { data: node } = await client.nodes.get("generate-video")
const { data: prices } = await client.credits.modelCosts(node.providers ?? [])

const options = (node.providers ?? []).map((id) => ({
  id,
  price: prices[id] ?? null, // null: no price on this instance
}))

노드의 기본 모델을 쓰려면 실행에서 provider를 생략하세요. 사용자가 모델을 고르면, 그 ID를 provider로 client.nodes.runAndWait()에 보내세요.