크레딧

크레딧은 Nodaro Cloud에서 결제에 쓰는 단위이며, API는 항상 금액이 아닌 크레딧으로 보고합니다. 크레딧 엔드포인트는 잔액과 크레딧 내역을 반환하고, 실행 전에 모델과 실행 가격을 알려 주며, 클라이언트가 연결된 배포 환경이 사용량에 따라 과금하는지 알려 줍니다.

크레딧 엔드포인트는 Nodaro Cloud에만 있습니다. Community Edition과 Business 에디션에는 크레딧 시스템이 없으므로 이 라우트가 404를 반환합니다. 단, GET /v1/billing/surface는 예외로 모든 에디션에서 응답합니다.

엔드포인트

공개 라우트에는 토큰이 필요하지 않습니다. 나머지 라우트는 다른 모든 라우트와 같은 토큰을 받습니다. 개인 API 토큰, OAuth 토큰, 세션 JWT 중 하나를 보내세요.

잔액 읽기

curl -s https://app.nodaro.ai/v1/credits/balance \
  -H "Authorization: Bearer $NODARO_API_KEY"

{ "total": 1250, "subscription": 1000, "topup": 250, "tier": "pro", "effectiveTier": "pro" }

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

total은 subscription과 topup을 더한 값입니다. tier는 저장된 구독 등급으로, free나 pro 등이 있습니다. effectiveTier는 Nodaro가 실제로 적용하는 등급입니다. payg는 구독은 없지만 크레딧을 구매한 상태로, 모든 모델이 열리고 워터마크와 일일 한도가 없습니다.

SDK의 client.credits.balance()가 읽는 GET /v1/user/credits는 더 많은 정보를 반환합니다.

크레딧을 쓸 때는 구독 크레딧이 먼저 차감됩니다. 구독 크레딧은 연간 요금제에서도 매달 요금제의 월간 할당량으로 초기화되며, 쓰지 않은 구독 크레딧은 이월되지 않습니다. 충전 크레딧은 구매일로부터 12개월 동안 유효합니다.

배포 환경에서 환영 혜택을 진행하는 동안에는 GET /v1/user/credits에 welcomeOffer: { popupSeen, consentPending, credits }도 담깁니다. credits는 혜택을 받으면 지급되는 크레딧 수이므로, 고정된 숫자 대신 이 값을 보여 주세요. 진행 중인 혜택이 없으면 이 키는 없습니다. 혜택은 Nodaro 웹 앱에서 받습니다. 두 라우트인 POST /v1/credits/welcome-offer/claim과 POST /v1/credits/welcome-offer/seen은 로그인한 브라우저 세션만 받으며, API 토큰이나 OAuth 앱 토큰에는 403 forbidden으로 응답합니다.

크레딧 차감 방식

• 작업이 시작될 때 예약됩니다. 생성은 실행 전에 가격만큼 크레딧을 예약합니다. 잔액이 부족하면 호출이 402 insufficient_credits를 반환하며, required와 대부분의 계정에서는 balance가 함께 옵니다. 워크플로 실행에서는 각 노드가 시작될 때 가격을 예약하며, 잔액이 부족한 노드는 실패합니다.
• 결과를 전달하면 차감됩니다. 예약이 차감으로 바뀝니다.
• 전달하지 못하면 환불됩니다. 모델의 안전 필터나 배포 환경의 정책으로 차단된 생성은 항상 환불되며, 취소된 작업도 환불됩니다.
• 실제로 실행된 값으로 가격이 매겨집니다. 서버가 선택한 모델에 맞게 설정을 수정하면, 예약도 수정된 값을 따릅니다. 매개변수 수정을 참조하세요.

작업의 credit_status와 거래의 status는 같은 단계를 거칩니다. reserved 다음에 committed 또는 refunded가 됩니다. 따라서 작업 자체에서 크레딧이 돌아왔는지 알 수 있습니다. 작업의 크레딧을 참조하세요.

거래 내역

GET /v1/credits/transactions는 내 크레딧 내역을 최신순으로 반환합니다.

curl -s "https://app.nodaro.ai/v1/credits/transactions?limit=2" \
  -H "Authorization: Bearer $NODARO_API_KEY"

{
  "data": [
    {
      "id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
      "created_at": "2026-09-26T14:03:11.284Z",
      "credits_charged": 50,
      "credits_reserved": 50,
      "credits_used": 50,
      "action": "generate-image",
      "provider": "nano-banana-pro",
      "status": "committed",
      "metadata": { "model": "nano-banana-pro", "from_sub": 50, "from_topup": 0 },
      "payer": "user",
      "workspaceId": null
    }
  ],
  "nextCursor": "2026-09-26T14:03:11.284Z"
}

어느 금액을 읽어야 하나요? 실행은 먼저 크레딧을 예약합니다. 그다음 실행이 정산됩니다. 예약액의 전부 또는 일부가 청구되고, 나머지는 잔액으로 돌아갑니다. 일부 실행은 예약액보다 적게 정산되는 경우가 많습니다. 예를 들어 다시 렌더링할 가능성까지 감안한 예약, 실행 후에 측정되는 길이, 사용량에 따라 과금되는 실행이 그렇습니다. 따라서 예약액은 실제로 낸 금액이 아닙니다. 예를 들어 888크레딧을 예약하고 444크레딧이 청구된 실행은 credits_charged: 444, credits_reserved: 888, credits_used: 888, status: "committed"로 표시됩니다. 나머지 444크레딧은 잔액으로 돌아갑니다.

status는 예약의 진행 상태입니다. reserved(크레딧이 예약되었고 아직 확정되지 않음), committed(실행이 결과를 전달해 청구됨, 청구액은 credits_charged) 또는 refunded(예를 들어 안전 차단 후 예약이 해제됨)입니다. 작업 페이로드에는 같은 진행 상태가 credit_status로, 정산된 금액이 credits_charged로 표시됩니다. 따라서 작업 비용을 알기 위해 거래 내역을 볼 필요가 없습니다. 작업의 크레딧을 참조하세요.

metadata에는 해당하는 경우에만 다음 키가 들어갑니다. model, from_sub와 from_topup(어느 잔액에서 결제했는지), is_app_run, allowance_delta, web_free_mode, status, loop_trim_refunded, surround_refine_refunded입니다.

더 이상 행이 없으면 nextCursor는 null입니다.

실행 전에 가격 확인

모델 가격, 노드 가격, estimatedCredits는 실행에 실제로 청구되는 가격이며, 에디터의 실행 버튼에 표시되는 숫자와 같습니다. 동영상 자르기, 동영상 루프, 동영상 합치기의 노드 creditCost는 5초 단위 한 번의 가격이며, 실행 비용은 그 단위가 몇 번인지에 따라 정해집니다. estimatedCredits에서 동영상 효과음 노드는 8초 가격으로 계산됩니다. 클립 길이는 실행이 시작될 때에야 측정되기 때문입니다. 실행에서는 측정된 길이의 가격이 청구됩니다.

모델 가격은 설정에 따라 달라질 수 있으므로, 변형 id에 설정이 들어갑니다. 예: nano-banana-pro:4K, gpt-image-2:2K.

curl -s -X POST https://app.nodaro.ai/v1/credits/model-costs \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"models": ["nano-banana-pro", "nano-banana-pro:4K", "gpt-image-2:2K"]}'

{
  "data": { "nano-banana-pro": 50, "nano-banana-pro:4K": 66, "gpt-image-2:2K": 42 },
  "missing": [],
  "errors": []
}

const { data, missing } = await client.credits.modelCosts(['nano-banana-pro', 'nano-banana-pro:4K'])
console.log(data['nano-banana-pro:4K'])
if (missing.length) console.warn('No price for:', missing)

단위별로 가격이 매겨지는 실행의 정확한 가격

일부 실행은 단위별로 가격이 매겨지며, 실행은 전체로 가격을 계산한 뒤 한 번만 반올림합니다. 따라서 단위 가격에 단위 수를 곱한 값이 실행 비용보다 클 수 있습니다. 이런 실행의 견적을 내려면 해당 행의 N단위 정확한 가격인 식별자 <row>:<N>u를 요청하세요. POST /v1/credits/model-costs와 GET /v1/credits/model-cost 모두 이 식별자에 답합니다.

단위별로 청구되지 않는 행이나, 그 행의 어떤 실행도 가질 수 없는 단위 수는 missing에 들어갑니다. 음성을 길이로 가격을 매기지 않는 설치에서는 모든 <model>:per-100-chars:<N>u id도 missing에 들어갑니다. 그런 설치에서는 모델의 고정 가격 행으로 견적을 내세요.

보이스 체인저 Pro 변환 전체에는 고유한 식별자가 있습니다. voice-changer-pro:<slot>,<slot>,…이며, 음색을 바꾸는 보이스마다 슬롯이 하나씩 들어갑니다. 슬롯은 음성 대 음성 보이스이면 스템 길이에 따라 sts-<seconds>입니다. 다시 읽기 보이스는 v3에서 respeak-<characters>, v4에서 respeak-v4-<characters>, v4로 번역을 말할 때 respeak-v4t-<characters>입니다. 번역에는 녹취록의 글자 수를 보내세요. 다시 렌더링되는 대사에 대한 여유분은 서버가 더합니다. 측정값을 모르면 그냥 종류만 쓰세요. 예: voice-changer-pro:sts-26.76,respeak-v4-1200,respeak-v4t-800. 두 엔드포인트 모두 변환이 예약하는 크레딧으로 답합니다. 변환은 합계를 한 번 반올림해 청구하므로, 보이스별 가격을 더해도 그 값이 되지 않습니다. 슬롯이 8개를 넘거나, 스템이 1시간보다 길거나, 슬롯 형식이 잘못되면 missing에 들어갑니다. @nodaro/shared 패키지의 voiceChangerProQuoteCreditId(slots)로 이 식별자를 만들 수 있으며, 다시 읽기 슬롯은 선택 항목인 engine("v3" 또는 "v4")과 translated 플래그를 받습니다.

가격이 없는 id는 missing에, 조회에 실패한 id는 errors에 들어가므로, 잘못된 id 하나 때문에 요청 전체가 실패하지는 않습니다. 이런 id에는 0이 아니라 대시를 표시하세요. 위 가격은 예시입니다. 실시간 응답을 읽거나, 모델에서 각 모델 페이지를 확인하세요.

CLI에는 크레딧 명령이 없지만, nodaro models list로 각 모델의 크레딧 등급을 볼 수 있습니다.

Seedance 레퍼런스 동영상 견적

레퍼런스 동영상이 있는 Seedance 2 실행은 레퍼런스 클립의 초와 출력 초를 더해 청구되므로, 가격은 클립의 실제 길이에 따라 달라집니다. 레퍼런스 동영상이 연결된 동영상 생성과, 원본 클립이 레퍼런스 동영상 1이 되는 동영상으로 동영상 만들기의 Seedance 2.5 Edit 선택지가 여기에 해당합니다. POST /v1/credits/seedance-ref-estimate는 클립을 측정해 실행의 예약과 똑같이 가격을 계산합니다. 작업을 만들지 않고 아무것도 예약하지 않습니다. 토큰이 필요하며, 분당 60회 요청을 허용합니다.

{ "provider": "seedance-2-5", "resolution": "720p", "duration": 8, "referenceVideoUrls": ["https://example.com/clip.mp4"] }

응답은 { "data": { "credits", "min", "exact" } }입니다. 모든 클립을 지정하면 credits는 실행이 예약하는 값과 정확히 같고, min도 같습니다. 측정할 수 없는 클립은 실행에서처럼 모델이 받는 가장 긴 클립으로 계산합니다. unknownReferenceVideos가 있으면 exact는 false입니다. credits는 알 수 없는 각 클립을 모델이 받는 가장 긴 클립으로, min은 가장 짧은 클립으로 계산합니다. 실행이 거부할 클립은 여기서도 실행과 같은 400 video_too_long으로 거부됩니다. 편집기도 연결된 클립이 아직 만들어지지 않은 동안 노드에 같은 범위를 표시합니다.

요금제와 가격

GET /v1/billing/plans는 판매 중인 요금제와 크레딧 팩을 각각의 가격과 함께 나열합니다. 공개 라우트입니다. 토큰이 필요 없고 읽지도 않으므로, 가격 페이지는 누군가 로그인하기 전에도 이 라우트를 호출할 수 있습니다. 모든 호출자가 같은 응답을 받으며, Cache-Control: public, max-age=300과 함께 전송됩니다. Nodaro Cloud에서만 응답합니다. SDK에서는 client.billing.plans(), CLI에서는 nodaro billing plans이며, 로그인이 필요 없습니다.

{
  "data": [
    { "id": "free", "name": "Free", "prices": null,
      "signupCredits": <credits>, "parallelism": <n>, "storageBytes": <bytes> },
    { "id": "basic", "name": "Basic",
      "prices": {
        "monthly": { "amount": <amount>, "currency": "USD",
                     "credits": { "amount": <credits>, "per": "month" } },
        "yearly":  { "amount": <amount>, "currency": "USD", "perMonth": <amount>,
                     "credits": { "amount": <credits>, "per": "month" } }
      },
      "signupCredits": null, "parallelism": <n>, "storageBytes": <bytes> }
  ],
  "topUps": [
    { "id": "topup-10", "credits": <credits>, "price": { "amount": <amount>, "currency": "USD" } }
  ],
  "topUpRange": { "min": <amount>, "max": <amount>, "currency": "USD" }
}

구매는 앱에서 이루어집니다. 요금제를 판매하려면 사용자를 Nodaro 앱의 요금제 페이지로 보내세요.

내 요금제

GET /v1/billing/subscription은 로그인한 세션, 워크플로 제한이 없는 개인 API 토큰, 앱의 OAuth 토큰에 응답합니다. 워크플로가 제한된 토큰은 403 forbidden을 받습니다. 응답은 { data, effectiveTier }입니다.

• data는 계정의 최신 구독이며, 구독한 적이 없으면 null입니다. tier, status(active, trialing, past_due, paused, canceled, incomplete, expired), current_period_start, current_period_end, cancel_at_period_end, cancel_at, canceled_at이 담깁니다.
• effectiveTier는 계정의 기능이 따르는 등급입니다. 대개 GET /v1/billing/plans의 요금제 id입니다. 구독 없이 크레딧을 구매한 계정이라면 "payg"일 수도 있고, "enterprise"처럼 판매하지 않는 등급일 수도 있습니다.

현재 요금제를 표시하려면 effectiveTier를 요금제 목록의 data[].id와 비교하세요. 일치하는 것이 없으면 종량제이거나 판매하지 않는 등급입니다. SDK에서는 client.billing.subscription(), CLI에서는 nodaro billing subscription입니다.

종량제

API를 사용하는 데 구독은 필요하지 않습니다.

• 구매하면 바로 활성화됩니다. 크레딧 팩을 구매하거나, 결제 페이지에서 $5~$1,000 사이의 금액을 1달러 단위로 충전하면 계정이 종량제로 전환됩니다. 많이 충전할수록 크레딧당 단가가 낮아집니다.
• 모든 기능이 열립니다. effectiveTier가 payg가 되어, 모든 모델을 쓸 수 있고 결과에 워터마크가 없으며 일일 사용 한도도 없습니다.
• 구매일로부터 크레딧이 12개월 동안 유효합니다.
• 개발자용 환경에서 씁니다. 종량제 크레딧은 API, SDK, CLI, MCP에서 사용할 수 있습니다. 웹 에디터에는 구독이 필요하며, 종량제 계정이 웹 에디터에서 크레딧을 쓰면 403 subscription_required를 받습니다. 토큰 호출에서는 이 오류가 발생하지 않습니다.
• 꾸준히 사용한다면 구독이 크레딧당 더 저렴합니다.

알아 둘 점이 두 가지 있습니다.

• 결과는 기본적으로 공개됩니다. 비공개 결과는 표준 요금제 이상의 구독 기능이므로, 종량제 결과는 공개 갤러리에 표시됩니다. MCP로 만든 작업은 항상 비공개입니다.
• 계정이 활성 상태인 동안 미디어가 유지됩니다. 구매도 크레딧 사용도 없이 약 3개월이 지나면, 60일보다 오래된 파일이 삭제될 수 있습니다. 크레딧을 다시 사용하면 정리가 중단됩니다. 정리는 생성 작업이 자기 결과로 저장한 파일만 삭제하며, 결과가 되풀이한 입력이나 내 라이브러리 항목이 아직 쓰는 파일은 삭제하지 않습니다. 파일이 삭제되면 그 파일을 담은 모든 작업 결과에서 링크가 null로 바뀝니다.

구매 자체는 웹 앱에서 이루어집니다. 결제 진행, 충전, 요금제 변경, 자동 충전, 구매 내역, 결제 포털을 다루는 결제 라우트는 API 토큰과 OAuth 토큰을 거부합니다. 결제는 app.nodaro.ai/billing에서 관리하세요.

배포 환경의 과금 방식 읽기

두 라우트를 쓰면 클라이언트가 배포 환경의 결제 방식을 가정하지 않고도 비용과 사용량 화면을 만들 수 있습니다.

GET /v1/billing/surface는 토큰이 필요 없으며 모든 사용자에게 같은 응답을 반환합니다.

{
  "data": {
    "contract": 2,
    "providerId": "…",
    "displayUnit": "credits",
    "canReport": true,
    "canQuote": true,
    "canAccount": true,
    "mountCostTab": true,
    "deploymentPayer": false
  }
}

• displayUnit은 비용 화면에 기본으로 표시할 단위입니다. 예: credits, usd.
• 크레딧이 없는 Community 설치에서는 providerId가 none이고 mountCostTab이 false입니다. 이때는 비용 화면을 표시하지 마세요.
• deploymentPayer는 하나의 결제 계정이 모든 사용자의 비용을 낼 때 true입니다. 그 계정이 어느 계정인지는 표시되지 않습니다.

GET /v1/billing/account는 내 계정 요약을 { "data": … } 형태로 반환합니다. 결제 서비스가 응답하지 못하면 data가 null입니다. 이때는 잔액 0이 아니라 “사용할 수 없음”으로 표시하세요. 요약에는 항상 다음 필드가 있습니다.

배포 환경은 periodStart, generations, spent, payg, daily, reserveValue, byCategory 같은 선택 필드를 추가할 수 있으며, 클라이언트는 받은 필드만 표시합니다. 금액은 { amount, currency } 객체입니다. daily에서 limit이 0이면 무제한이 아니라 차단을 뜻하며, 둘 다 있으면 daily가 dailyAllowance보다 우선합니다. 모든 null은 0이 아니라 “사용할 수 없음”을 뜻하므로 대시를 표시하세요.

POST /v1/jobs/cost-summary는 여러 작업의 크레딧을 합산합니다. 최상위와 각 세부 행의 total_credits는 숫자 또는 null입니다. 응답에는 unit이 명시되고, 가격을 매길 수 없었던 작업 수가 unavailable에 들어갑니다. null 합계는 일괄 처리의 어떤 작업에도 알려진 청구 금액이 없었다는 뜻입니다. 0이라는 뜻이 아닙니다.

워크스페이스와 공유 결제

• 워크스페이스 예산. 조직의 워크스페이스 안에서의 사용은 내 잔액이 아니라 워크스페이스 예산으로 결제되며, 그 거래에는 payer: "workspace"가 붙습니다. 예산을 넘는 실행은 402 budget_exceeded를, 그 워크스페이스에서 내 한도를 넘는 실행은 402 member_cap_exceeded를 반환합니다. 워크스페이스와 조직을 참조하세요.
• 결제 계정이 하나인 배포 환경. 하나의 결제 계정이 모든 사용자의 비용을 내는 배포 환경에서는 GET /v1/user/credits에 내 허용량을 크레딧으로 나타낸 allowance: { granted, remaining, enforced }가 추가됩니다. enforced: false는 허용량이 표시되기만 하고 실행을 막지는 않는다는 뜻입니다. 결제 계정 자신이거나 허용량을 읽지 못한 경우 allowance는 null이므로, null을 0으로 해석하지 마세요. 배포 환경이 허용량을 적용하면, 내 허용량을 넘는 실행은 402 user_allowance_exceeded를 반환합니다. 결제 계정은 자신의 브라우저 세션에서만 풀을 관리합니다. 토큰으로 잔액을 읽으면 403 payer_balance_jwt_only가 반환됩니다. 자체 지갑으로 사용을 승인하는 배포 환경은 외부 지갑을 참조하세요.