잔액과 API 키 사용 한도

콘텐츠를 생성하는 모든 요청은 선불 USD 잔액에서 결제됩니다. API 키마다 사용할 수 있는 금액에 한도를 둘 수도 있습니다. 이 페이지에서는 잔액과 키의 한도를 읽는 방법, 그리고 둘 중 하나 때문에 요청이 거부되었을 때 해야 할 일을 설명합니다.

두 엔드포인트 모두 Authorization: Bearer로 보내는 API 키가 필요합니다. 인증을 참고하세요.

GET /v1/balance 엔드포인트는 계정의 잔액을 반환합니다.

curl "https://api.sakuranbo.ai/v1/balance" \
  -H "Authorization: Bearer $SAKURANBO_API_KEY"

const response = await fetch("https://api.sakuranbo.ai/v1/balance", {
  headers: {
    Authorization: `Bearer ${process.env.SAKURANBO_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);

import os

import requests

response = requests.get(
    "https://api.sakuranbo.ai/v1/balance",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
    },
)
print(response.json())

응답에는 다음 필드가 있습니다.

• available_micro_usd와 available_usd는 새 요청에 사용할 수 있는 금액입니다.
• held_micro_usd와 held_usd는 실행 중인 요청이 확보해 둔 금액입니다.

각 금액은 두 가지로 제공됩니다. micro USD(1 USD = 1,000,000 micro USD) 단위의 정수와 USD 십진수 문자열입니다.

잔액을 충전하려면 대시보드의 충전 페이지를 여세요. 요금과 과금을 참고하세요.

Sakuranbo AI는 비용이 드는 요청을 받아들일 때 금액을 확보합니다. 확보한 금액은 available에서 held로 옮겨집니다. 요청이 끝나면 실제 비용이 청구되고 차액은 available로 돌아옵니다. 취소되거나 거부된 요청, 또는 모델이 출력을 하나도 생성하기 전에 실패한 요청은 확보했던 금액 전부를 돌려받으며 요금이 청구되지 않습니다. 모델이 출력(추론 출력 포함)을 생성하기 시작한 뒤 채팅 스트림이 끊기면 생성된 출력을 포함해 요청에 요금이 청구되고, 확보한 금액의 나머지는 available로 돌아옵니다. 채팅을 참고하세요.

드물게 이미지나 영상 작업이, 모델 제공업체가 요청을 받았는지 Sakuranbo AI가 확인하기 전에 실패하는 경우가 있습니다. 이때 작업은 upstream_error와 함께 failed가 됩니다. 확보한 금액은 Sakuranbo AI가 과금 여부를 확인할 때까지 held에 남으며, 저절로 available로 돌아오지 않습니다. 계속 held에 남아 있다면 작업 ID와 함께 지원팀에 문의하세요.

금액이 확보되므로 요청이 실행되는 동안 available은 전체 잔액보다 낮을 수 있습니다. 새 요청은 available을 기준으로 검사합니다.

사용 한도는 API 키 하나에 속합니다. 대시보드의 API 키 페이지에서 키를 만들 때 설정합니다. 한도는 USD 금액과 기간으로 이루어집니다. 기간은 none, day, month 중 하나입니다.

• day: 키가 UTC 기준 달력상 하루 동안 사용할 수 있는 금액입니다. 카운터는 UTC 00:00에 다시 시작합니다.
• month: UTC 기준 달력상 한 달 동안의 금액입니다. 카운터는 매월 1일 UTC 00:00에 다시 시작합니다.
• none: 키의 수명 전체에 대한 금액입니다. 카운터는 다시 시작하지 않습니다.

한도가 없는 키는 잔액이 허용하는 만큼 사용할 수 있으며, 사용량은 그래도 집계됩니다. 키에 만료일을 설정할 수도 있습니다. 만료된 키로 보낸 요청은 401을 반환합니다. 인증을 참고하세요.

대시보드의 Playground에서 실행하는 요청은 API 키를 사용하지 않으므로 어떤 키의 한도에도 집계되지 않습니다.

GET /v1/key 엔드포인트는 요청을 보낸 키를 한도와 사용량과 함께 반환합니다.

curl "https://api.sakuranbo.ai/v1/key" \
  -H "Authorization: Bearer $SAKURANBO_API_KEY"

const response = await fetch("https://api.sakuranbo.ai/v1/key", {
  headers: {
    Authorization: `Bearer ${process.env.SAKURANBO_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);

import os

import requests

response = requests.get(
    "https://api.sakuranbo.ai/v1/key",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
    },
)
print(response.json())

응답에는 다음 필드가 있습니다.

• limit은 키에 한도가 없으면 null입니다. 한도가 있으면 금액과 기간이 들어 있습니다.
• usage.used_micro_usd와 usage.used_usd는 실행 중인 요청이 확보한 금액에 현재 기간에 이미 청구된 금액을 더한 값입니다.
• usage.remaining_micro_usd와 usage.remaining_usd는 한도까지 남은 금액입니다. 키에 한도가 없으면 null입니다.
• usage.resets_at은 카운터가 다시 시작되는 시각입니다. 기간이 none이면 null입니다.

요청은 두 가지 경우에 402로 거부됩니다. error.details.limit_source로 둘을 구분합니다.

limit_source가 balance인 balance_insufficient: available 잔액이 요청이 확보해야 하는 금액보다 적습니다. error.details에는 requested_micro_usd, available_micro_usd, shortfall_micro_usd와, USD로 나타낸 같은 세 금액인 requested_usd, available_usd, shortfall_usd가 들어 있습니다. 잔액을 충전한 뒤 요청을 다시 보내세요.

limit_source가 key인 key_limit_exceeded: 키의 사용량에 요청이 확보해야 하는 금액을 더하면 키의 한도를 넘습니다. 한도에 정확히 도달하는 요청은 받아들여집니다. error.details에는 period, resets_at, requested_micro_usd, limit_micro_usd, used_micro_usd와, USD로 나타낸 같은 세 금액이 들어 있습니다. 두 경우가 모두 해당하면 키의 한도를 먼저 검사합니다.

다음 사항에 유의하세요.

• 확보는 즉시 집계되므로, 실제 비용이 한도 안에 들어오더라도 요청이 거부될 수 있습니다. max_tokens를 낮춘 채팅 요청처럼 작은 요청은 더 적은 금액을 확보합니다.
• 거부된 요청에는 아무것도 청구되지 않으며 작업도 만들어지지 않습니다.
• 402 응답에는 Retry-After 헤더가 없습니다. 키의 한도라면 error.details.resets_at을 읽어 카운터가 다시 시작되는 시각을 확인하세요. 값이 null이면 한도가 키의 수명 전체에 적용되므로 한도가 더 높은 키를 사용해야 합니다.

사용 가능한 잔액이 직접 정한 기준 아래로 내려가면 balance.low 웹훅 이벤트를 받을 수 있습니다. 기준은 대시보드의 설정에서 지정합니다. 웹훅을 참고하세요.

MCP 서버에는 같은 데이터를 읽는 도구 get_balance가 있습니다. MCP 서버를 참고하세요.

GET /v1/key 엔드포인트도 같은 코드를 반환합니다. 전체 코드 목록은 오류를 참고하세요.