# 크레딧

API는 SciFig 크레딧을 사용합니다. 웹사이트, API 및 MCP가 하나의 잔액을 공유합니다.

출처: https://scifig.ai/ko/docs/api/credits

## 잔액 조회

`GET /credits`(범위 `figures:read`)는 잔액, 실행 중인 작업의 예약 크레딧, 요금제 및 작업 제한을 반환합니다:

```json
{
  "balance": 2950,
  "reserved": 100,
  "granted_scopes": ["figures:read", "figures:generate"],
  "plan": "plus",
  "plan_level": 2,
  "limits": { "concurrent_tasks": 5, "tasks_per_hour": 200 },
  "top_up_url": "https://scifig.ai/pricing?utm_source=api"
}
```

- `plan`은 `free`, `starter`, `plus` 또는 `pro`입니다. 크레딧 팩 잔액이 0보다 큰 계정은 잔액이 남아 있는 동안 `pro`로 간주합니다.
- `tasks_per_hour`는 모든 요금제에서 200이며, `concurrent_tasks`는 요금제에 따라 다릅니다.
- `top_up_url`에는 API 직접 요청 시 `utm_source=api`, MCP 서버를 통한 요청 시 `utm_source=mcp`가 포함됩니다.
- `granted_scopes`는 현재 인증 정보의 권한을 나열합니다. `figures:read`와 허용된 경우 `figures:generate`가 포함됩니다.

`GET /pricing`은 인증 없이 전체 가격을 반환합니다. 이 문서의 가격도 같은 표에서 읽습니다. 별도 API 요금제는 없습니다. [가격 페이지](/ko/pricing)에서 크레딧이나 구독을 구매하세요.

## 크레딧 예약 흐름

- 작업 생성 시 요금을 원자적으로 예약하므로 두 요청이 같은 크레딧을 사용할 수 없습니다.
- 크레딧이 부족하면 `details.top_up_url`을 포함한 `402 INSUFFICIENT_CREDITS`를 반환합니다. 크레딧을 예약하거나 작업을 실행하지 않습니다. 거부된 요청은 해당 오류를 가진 실패 작업으로 `GET /jobs`에 남으며, 같은 키로 재요청하면 같은 응답을 반환합니다.
- 성공한 작업은 예약한 크레딧을 정확히 한 번 차감하며, 실패하거나 취소된 작업은 전액 반환합니다. 내부 재시도는 다시 예약하지 않고, `Idempotency-Key` 재요청도 기존 예약을 재사용합니다.
- 각 작업은 원장에서 읽은 `credits.reserved`, `credits.charged` 및 `credits.refunded`를 보고합니다.
- 크레딧은 웹사이트와 같은 순서로 사용됩니다. 먼저 만료되는 크레딧부터 사용하고, 만료되지 않는 팩 크레딧은 마지막에 사용합니다.

## cURL

```bash
curl https://scifig.ai/api/v1/credits \
  -H "Authorization: Bearer $SCIFIG_API_KEY"
```

## JavaScript

```javascript
const response = await fetch('https://scifig.ai/api/v1/credits', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SCIFIG_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

## Python

```python
import os

import requests

headers = {
    "Authorization": f"Bearer {os.environ['SCIFIG_API_KEY']}",
}
response = requests.get(
    "https://scifig.ai/api/v1/credits",
    headers=headers,
    timeout=60,
)
print(response.status_code, response.json())
```