메인 콘텐츠로 건너뛰기
GET
/
v1
/
user
/
balance
curl --request GET \
  --url 'https://api.apimart.ai/v1/user/balance' \
  --header 'Authorization: Bearer <token>'
import requests

API_BASE = 'https://api.apimart.ai'
API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxx'

headers = {
    'Authorization': f'Bearer {API_KEY}'
}

def get_user_balance():
    response = requests.get(f'{API_BASE}/v1/user/balance', headers=headers)
    data = response.json()
    
    if data.get('success'):
        print(f"남은 잔액: {data['remain_balance']}")
        print(f"사용된 잔액: {data['used_balance']}")
    else:
        print(f"조회 실패: {data.get('message')}")
    
    return data

get_user_balance()
const API_BASE = 'https://api.apimart.ai';
const API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxx';

async function getUserBalance() {
  const response = await fetch(`${API_BASE}/v1/user/balance`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });
  
  const data = await response.json();
  
  if (data.success) {
    console.log(`남은 잔액: ${data.remain_balance}`);
    console.log(`사용된 잔액: ${data.used_balance}`);
  } else {
    console.error('조회 실패:', data.message);
  }
  
  return data;
}

getUserBalance();
package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

type BalanceResponse struct {
    Success        bool    `json:"success"`
    Message        string  `json:"message,omitempty"`
    RemainBalance  float64 `json:"remain_balance"`
    UsedBalance    float64 `json:"used_balance"`
}

func main() {
    url := "https://api.apimart.ai/v1/user/balance"

    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer <token>")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    
    var result BalanceResponse
    json.Unmarshal(body, &result)
    
    if result.Success {
        fmt.Printf("남은 잔액: %.2f\n", result.RemainBalance)
        fmt.Printf("사용된 잔액: %.2f\n", result.UsedBalance)
    }
}
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://api.apimart.ai/v1/user/balance";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", "Bearer <token>")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}
<?php

$api_key = 'sk-xxxxxxxxxxxxxxxxxxxxxx';

$ch = curl_init('https://api.apimart.ai/v1/user/balance');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $api_key"
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

if ($data['success']) {
    echo "남은 잔액: " . $data['remain_balance'] . "\n";
    echo "사용된 잔액: " . $data['used_balance'] . "\n";
} else {
    echo "조회 실패: " . $data['message'] . "\n";
}
?>
require 'net/http'
require 'json'
require 'uri'

api_key = 'sk-xxxxxxxxxxxxxxxxxxxxxx'

url = URI("https://api.apimart.ai/v1/user/balance")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = "Bearer #{api_key}"

response = http.request(request)
data = JSON.parse(response.body)

if data['success']
  puts "남은 잔액: #{data['remain_balance']}"
  puts "사용된 잔액: #{data['used_balance']}"
else
  puts "조회 실패: #{data['message']}"
end
import Foundation

let apiKey = "sk-xxxxxxxxxxxxxxxxxxxxxx"
let url = URL(string: "https://api.apimart.ai/v1/user/balance")!

var request = URLRequest(url: url)
request.httpMethod = "GET"
request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let error = error {
        print("Error: \(error)")
        return
    }

    if let data = data, let responseString = String(data: data, encoding: .utf8) {
        print(responseString)
    }
}

task.resume()
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var apiKey = "sk-xxxxxxxxxxxxxxxxxxxxxx";
        var url = "https://api.apimart.ai/v1/user/balance";

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");

        var response = await client.GetAsync(url);
        var result = await response.Content.ReadAsStringAsync();

        Console.WriteLine(result);
    }
}
{
  "success": true,
  "remain_balance": 100.0,
  "remain_credits": 1000,
  "used_balance": 25.5,
  "used_credits": 255
}
{
  "success": false,
  "message": "사용자 잔액을 가져오지 못했습니다: record not found"
}
{
  "success": false,
  "message": "사용된 잔액을 가져오지 못했습니다: record not found"
}
{
  "error": {
    "code": 401,
    "message": "인증에 실패했습니다. API 키를 확인하세요",
    "type": "authentication_error"
  }
}
{
  "error": {
    "code": 429,
    "message": "요청이 너무 많습니다. 나중에 다시 시도하세요",
    "type": "rate_limit_error"
  }
}
현재 사용자 계정의 남은 잔액과 사용된 잔액을 조회합니다. 이 엔드포인트는 특정 토큰에 의존하지 않는 사용자 수준의 잔액 정보를 반환하며, 전체 계정 잔액을 확인하는 데 사용됩니다.
curl --request GET \
  --url 'https://api.apimart.ai/v1/user/balance' \
  --header 'Authorization: Bearer <token>'
import requests

API_BASE = 'https://api.apimart.ai'
API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxx'

headers = {
    'Authorization': f'Bearer {API_KEY}'
}

def get_user_balance():
    response = requests.get(f'{API_BASE}/v1/user/balance', headers=headers)
    data = response.json()
    
    if data.get('success'):
        print(f"남은 잔액: {data['remain_balance']}")
        print(f"사용된 잔액: {data['used_balance']}")
    else:
        print(f"조회 실패: {data.get('message')}")
    
    return data

get_user_balance()
const API_BASE = 'https://api.apimart.ai';
const API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxx';

async function getUserBalance() {
  const response = await fetch(`${API_BASE}/v1/user/balance`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });
  
  const data = await response.json();
  
  if (data.success) {
    console.log(`남은 잔액: ${data.remain_balance}`);
    console.log(`사용된 잔액: ${data.used_balance}`);
  } else {
    console.error('조회 실패:', data.message);
  }
  
  return data;
}

getUserBalance();
package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

type BalanceResponse struct {
    Success        bool    `json:"success"`
    Message        string  `json:"message,omitempty"`
    RemainBalance  float64 `json:"remain_balance"`
    UsedBalance    float64 `json:"used_balance"`
}

func main() {
    url := "https://api.apimart.ai/v1/user/balance"

    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer <token>")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    
    var result BalanceResponse
    json.Unmarshal(body, &result)
    
    if result.Success {
        fmt.Printf("남은 잔액: %.2f\n", result.RemainBalance)
        fmt.Printf("사용된 잔액: %.2f\n", result.UsedBalance)
    }
}
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://api.apimart.ai/v1/user/balance";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", "Bearer <token>")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}
<?php

$api_key = 'sk-xxxxxxxxxxxxxxxxxxxxxx';

$ch = curl_init('https://api.apimart.ai/v1/user/balance');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $api_key"
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

if ($data['success']) {
    echo "남은 잔액: " . $data['remain_balance'] . "\n";
    echo "사용된 잔액: " . $data['used_balance'] . "\n";
} else {
    echo "조회 실패: " . $data['message'] . "\n";
}
?>
require 'net/http'
require 'json'
require 'uri'

api_key = 'sk-xxxxxxxxxxxxxxxxxxxxxx'

url = URI("https://api.apimart.ai/v1/user/balance")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = "Bearer #{api_key}"

response = http.request(request)
data = JSON.parse(response.body)

if data['success']
  puts "남은 잔액: #{data['remain_balance']}"
  puts "사용된 잔액: #{data['used_balance']}"
else
  puts "조회 실패: #{data['message']}"
end
import Foundation

let apiKey = "sk-xxxxxxxxxxxxxxxxxxxxxx"
let url = URL(string: "https://api.apimart.ai/v1/user/balance")!

var request = URLRequest(url: url)
request.httpMethod = "GET"
request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let error = error {
        print("Error: \(error)")
        return
    }

    if let data = data, let responseString = String(data: data, encoding: .utf8) {
        print(responseString)
    }
}

task.resume()
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var apiKey = "sk-xxxxxxxxxxxxxxxxxxxxxx";
        var url = "https://api.apimart.ai/v1/user/balance";

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");

        var response = await client.GetAsync(url);
        var result = await response.Content.ReadAsStringAsync();

        Console.WriteLine(result);
    }
}
{
  "success": true,
  "remain_balance": 100.0,
  "remain_credits": 1000,
  "used_balance": 25.5,
  "used_credits": 255
}
{
  "success": false,
  "message": "사용자 잔액을 가져오지 못했습니다: record not found"
}
{
  "success": false,
  "message": "사용된 잔액을 가져오지 못했습니다: record not found"
}
{
  "error": {
    "code": 401,
    "message": "인증에 실패했습니다. API 키를 확인하세요",
    "type": "authentication_error"
  }
}
{
  "error": {
    "code": 429,
    "message": "요청이 너무 많습니다. 나중에 다시 시도하세요",
    "type": "rate_limit_error"
  }
}

인증

Authorization
string
필수
모든 API 엔드포인트에는 Bearer Token 인증이 필요합니다API 키 받기:API 키 관리 페이지에서 API 키를 받으세요요청 헤더에 추가:
Authorization: Bearer YOUR_API_KEY

엔드포인트

GET /v1/user/balance
GET /user/balance
두 엔드포인트는 동일한 기능을 가지고 있습니다. 둘 중 하나를 사용할 수 있습니다.

응답

success
boolean
요청 성공 여부
message
string
오류 메시지 (실패 시에만 반환)
remain_balance
float
사용자 남은 잔액 (성공 시 반환)
remain_credits
integer
사용자 남은 크레딧 (성공 시 반환)
used_balance
float
사용자 사용된 잔액 (성공 시 반환)
used_credits
float
사용자 사용된 크레딧 (성공 시 반환)

토큰 잔액 vs 사용자 잔액

비교 항목토큰 잔액 (/v1/balance)사용자 잔액 (/v1/user/balance)
범위단일 토큰전체 사용자 계정
데이터 소스Token의 RemainQuota와 UsedQuotaUser의 quota와 used_quota
사용 사례단일 API 키 사용량 모니터링전체 계정 잔액 확인
제한 대상토큰 수준 한도사용자 수준 한도

사용 사례

  • 사용자 계정의 전체 잔액 확인
  • 충전 알림 및 잔액 경고 설정
  • 사용자 대시보드에서 계정 잔액 표시
잔액 단위 정보잔액 값의 단위는 시스템 설정에 따라 다릅니다:
  • USD - 미국 달러
  • CNY - 중국 위안
  • Tokens - 토큰 수

일반적인 오류

오류 메시지원인해결 방법
Authorization 헤더 없음Authorization 헤더가 제공되지 않음Authorization: Bearer sk-xxxxx 헤더 추가
사용자 잔액 가져오기 실패사용자가 존재하지 않음토큰과 연결된 사용자가 존재하는지 확인
사용된 잔액 가져오기 실패데이터베이스 쿼리 오류관리자에게 연락하여 시스템 상태 확인
보안 참고 사항API 키는 비밀번호와 같습니다. 안전하게 보관하고 다른 사람과 공유하지 마세요. 프로덕션에서는 항상 HTTPS를 사용하세요.