잔액 조회
curl --request GET \
--url https://maas.gravitex.ai/prod-api/api/account/balanceimport requests
url = "https://maas.gravitex.ai/prod-api/api/account/balance"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://maas.gravitex.ai/prod-api/api/account/balance', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://maas.gravitex.ai/prod-api/api/account/balance",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://maas.gravitex.ai/prod-api/api/account/balance"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://maas.gravitex.ai/prod-api/api/account/balance")
.asString();require 'uri'
require 'net/http'
url = URI("https://maas.gravitex.ai/prod-api/api/account/balance")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body인터페이스 모듈
잔액 조회
계정 또는 API 키의 잔액과 사용량을 조회합니다
GET
/
prod-api
/
api
/
account
/
balance
잔액 조회
curl --request GET \
--url https://maas.gravitex.ai/prod-api/api/account/balanceimport requests
url = "https://maas.gravitex.ai/prod-api/api/account/balance"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://maas.gravitex.ai/prod-api/api/account/balance', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://maas.gravitex.ai/prod-api/api/account/balance",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://maas.gravitex.ai/prod-api/api/account/balance"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://maas.gravitex.ai/prod-api/api/account/balance")
.asString();require 'uri'
require 'net/http'
url = URI("https://maas.gravitex.ai/prod-api/api/account/balance")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body엔드포인트 정보
| 항목 | 설명 |
|---|---|
| 기본 URL | https://maas.gravitex.ai/prod-api |
| 데이터 형식 | application/json |
| 문자 인코딩 | UTF-8 |
| 프로토콜 | HTTPS (필수) |
| 통화 | USD (미국 달러) |
1. 인증
HTTP 헤더에 Bearer 자격 증명을 포함하세요. 다음 두 가지 중 하나를 사용하세요.| 자격 증명 | 발급 위치 | 조회 범위 |
|---|---|---|
| 시스템 액세스 토큰 | 콘솔 → 개인 설정 → 시스템 액세스 토큰 | 계정 전체 |
| API 키 | 콘솔 → 토큰 관리. 일반적으로 sk-로 시작합니다. | 해당 키만 |
| 헤더 | 필수 여부 | 설명 |
|---|---|---|
Authorization | 예 | Bearer <credential> 형식으로 위 자격 증명 중 하나를 사용합니다. |
# 방법 1. 시스템 액세스 토큰
Authorization: Bearer <access_token>
# 방법 2. API 키
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx
2. 공통 응답 구조
{
"code": 200,
"msg": "操作成功",
"data": { }
}
| 필드 | 유형 | 설명 |
|---|---|---|
code | integer | 애플리케이션 상태 코드입니다. 200은 성공을 나타냅니다. |
msg | string | 상태 메시지 |
data | object | 응답 데이터입니다. 실패하면 null을 반환합니다. |
애플리케이션 상태 코드
| 코드 | 설명 |
|---|---|
| 200 | 성공 |
| 401 | 인증 실패 (자격 증명 누락, 유효하지 않음 또는 비활성화) |
요청 성공 여부는 응답 본문의 code로 확인하세요.
금액 형식
- 모든 금액은 미국 달러(USD) 기준이며 부동소수점 정밀도 손실을 방지하기 위해 문자열로 반환됩니다.
- 잔액 관련 금액은 항상 소수점 이하 네 자리로 표시됩니다. 예를 들어
"986.9275"입니다. - 모델 단가는 소수점 이하 자릿수를 0으로 채우지 않습니다. 예를 들어
"40","2.5","0.00075"입니다.
3. 잔액 조회
GET /api/account/balance
data.type으로 구분할 수 있습니다.
3.1 시스템 액세스 토큰으로 계정 잔액 조회 (type = account)
| 필드 | 유형 | 설명 |
|---|---|---|
type | string | 고정값 account |
username | string | 계정 사용자 이름 |
group | string | 계정 그룹 |
currency | string | 고정값 USD |
balance | string | 남은 잔액 |
usedAmount | string | 사용 금액 |
totalAmount | string | 총액 (잔액과 사용 금액의 합) |
{
"code": 200,
"msg": "操作成功",
"data": {
"type": "account",
"username": "demo_user",
"group": "default",
"currency": "USD",
"balance": "986.9275",
"usedAmount": "213.0725",
"totalAmount": "1200.0000"
}
}
기업 하위 계정은 해당 계정의 잔액만 조회할 수 있습니다.
3.2 API 키로 해당 키의 한도 조회 (type = token)
| 필드 | 유형 | 설명 |
|---|---|---|
type | string | 고정값 token |
tokenName | string | 키 이름 |
group | string | 키 그룹입니다. 값이 비어 있으면 계정 그룹을 따릅니다. |
unlimited | boolean | 키 한도의 무제한 여부 |
currency | string | 고정값 USD |
balance | string | 해당 키의 남은 사용 가능 금액 |
usedAmount | string | 해당 키의 사용 금액 |
totalAmount | string | 키의 총한도 (잔액과 사용 금액의 합) |
expiresAt | integer | 만료 시각의 초 단위 타임스탬프입니다. 0은 만료되지 않음을 나타냅니다. |
modelLimitsEnabled | boolean | 모델 제한 활성화 여부 |
modelLimits | string[] | 해당 키로 호출할 수 있는 모델입니다. 제한이 비활성화되면 빈 배열을 반환합니다. |
{
"code": 200,
"msg": "操作成功",
"data": {
"type": "token",
"tokenName": "my-key",
"group": "",
"unlimited": false,
"currency": "USD",
"balance": "100.0000",
"usedAmount": "50.0000",
"totalAmount": "150.0000",
"expiresAt": 0,
"modelLimitsEnabled": false,
"modelLimits": []
}
}
unlimited = true인 키에는 키 단위 한도가 없으므로balance가 음수일 수 있습니다. 키 사용량은usedAmount로 확인하고, 실제 사용 가능 금액은 계정 잔액을 기준으로 판단하세요.
4. 요청 예시
# 시스템 액세스 토큰으로 계정 잔액 조회
curl -s "https://maas.gravitex.ai/prod-api/api/account/balance" \
-H "Authorization: Bearer <access_token>"
# API 키로 해당 키의 한도 조회
curl -s "https://maas.gravitex.ai/prod-api/api/account/balance" \
-H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx"
5. 참고 사항
- 갱신 주기. 잔액 데이터는 약 1분 이내에 갱신됩니다. 충전이나 사용 내역이 반영되기까지 시간이 걸릴 수 있습니다.
- 최종 청구 금액. 이 엔드포인트는 조회 및 추정용입니다. 최종 청구 금액은 청구서를 확인하세요.
- 자격 증명 보호. 시스템 액세스 토큰으로 계정 전체 정보를 조회할 수 있으므로 외부에 공개하지 마세요. 특정 키의 한도만 조회하려면 해당 API 키를 사용하세요.
