> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API 키 관리하기

> Admin 키를 사용하여 코드에서 Venice API 키를 생성하고, 상한을 설정하고, 추적하고, 업데이트하고, 폐기하세요.

Admin 키는 API를 통해 다른 모든 API 키를 관리할 수 있습니다. 각 앱, 환경 또는 고객에게 전용 Inference 키를 발급하고, 키별 지출 한도를 제한하고, 키별 사용량을 추적하며, 대시보드를 열지 않고도 키를 변경하거나 폐기할 수 있습니다.

> [card] [생성](#create-a-key)
>
> 지출 상한이 있는 키 발급

> [card] [추적](#track-usage)
>
> 각 키의 지출 확인

> [card] [변경](#change-limits-and-settings)
>
> 상한 상향 또는 만료 연장

> [card] [폐기](#revoke-or-rotate-a-key)
>
> 키를 즉시 차단

## 작동 방식

Admin 키
제어용 키
키 생성, 변경 및 폐기
사용량 및 청구 정보 조회
서버에만 보관

Inference
cust:acme

\$50 / 월
프라이빗 모델만

Inference
cust:globex

\$5 / 월
11.22.33.0/24에서만

Inference
staging

\$10 / 일
6월 30일 만료

Admin 키는 키를 관리하고 청구 정보를 조회하는 엔드포인트를 포함하여 모든 엔드포인트를 호출할 수 있습니다. Inference 키는 모델을 호출할 수 있지만 키를 관리하거나 청구 정보를 조회할 수는 없으므로, 외부에 나누어 주는 키는 Inference 키입니다.

| | Admin | Inference |
| - | :-: | :-: |
| 모델 및 기타 추론 엔드포인트 호출 | ✓ | ✓ |
| 자체 잔액 및 속도 제한 확인 (`GET /api_keys/rate_limits`) | ✓ | ✓ |
| 키 생성, 업데이트 및 폐기 (`/api_keys`) | ✓ | |
| 사용량 및 청구 정보 조회 (`/billing/*`) | ✓ | |

> [!NOTE]
>
> 첫 번째 Admin 키는 대시보드에서 생성하십시오. [API 키 생성하기](https://docs.venice.ai/ko/guides/getting-started/generating-api-key.md)를 따라 키 유형으로 **Admin**을 선택합니다. 이 키는 클라이언트 코드가 아닌 서버 측 시크릿 저장소에 보관하십시오.

이 페이지의 예제는 `VENICE_ADMIN_KEY`에서 Admin 키를 읽습니다:

```bash cURL theme={"system"}
export VENICE_ADMIN_KEY="your-admin-key"
```

```python Python theme={"system"}
import os
import requests

BASE = "https://api.venice.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['VENICE_ADMIN_KEY']}"}
```

```javascript Node.js theme={"system"}
const BASE = "https://api.venice.ai/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.VENICE_ADMIN_KEY}`,
  "Content-Type": "application/json",
};
```

## 키 생성하기

다음은 한 고객을 위한 Inference 키를 생성하는 예제로, 월 \$50의 상한이 있으며 2027년 6월 30일에 만료됩니다:

```bash cURL theme={"system"}
curl https://api.venice.ai/api/v1/api_keys \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKeyType": "INFERENCE",
    "description": "cust:acme",
    "consumptionLimit": { "usd": 50 },
    "limitPeriod": "MONTH",
    "expiresAt": "2027-06-30"
  }'
```

```python Python theme={"system"}
resp = requests.post(f"{BASE}/api_keys", headers=HEADERS, json={
    "apiKeyType": "INFERENCE",
    "description": "cust:acme",
    "consumptionLimit": {"usd": 50},
    "limitPeriod": "MONTH",
    "expiresAt": "2027-06-30",
})
resp.raise_for_status()
key = resp.json()["data"]
key_id, secret = key["id"], key["apiKey"]
```

```javascript Node.js theme={"system"}
const res = await fetch(`${BASE}/api_keys`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    apiKeyType: "INFERENCE",
    description: "cust:acme",
    consumptionLimit: { usd: 50 },
    limitPeriod: "MONTH",
    expiresAt: "2027-06-30",
  }),
});
const { data: key } = await res.json();
const { id: keyId, apiKey: secret } = key;
```

```json Response theme={"system"}
{
  "success": true,
  "data": {
    "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
    "apiKey": "VENICE_INFERENCE_KEY_...",
    "apiKeyType": "INFERENCE",
    "description": "cust:acme",
    "consumptionLimit": { "usd": 50, "vcu": null, "diem": null },
    "limitPeriod": "MONTH",
    "modelPrivacy": "ALL",
    "expiresAt": "2027-06-30T00:00:00.000Z",
    "ipAllowlist": []
  }
}
```

> [!WARNING]
>
> `data.apiKey`는 키의 비밀 값이며, 이 응답에서만 확인할 수 있습니다. 즉시 저장하십시오. 분실한 경우 해당 키를 폐기하고 새로 생성하십시오. `data.id`도 보관하십시오. 이 페이지의 다른 모든 호출에서 사용됩니다.

### 키 설정

키를 생성할 때 이 값들을 설정하거나, 나중에 `PATCH /api_keys`로 변경할 수 있습니다. 요청 본문은 엄격하게 검증되므로 알 수 없는 필드가 있으면 `400`이 반환됩니다.

| 필드 | 값 | 설명 |
| - | - | - |
| `apiKeyType` | `INFERENCE` 또는 `ADMIN` | 생성 시 필수입니다. 나중에 변경할 수 없습니다. |
| `description` | 최대 64자 | 생성 시 필수입니다. 사용량 분석에서 이 값으로 키를 표시하므로 `cust:acme`처럼 자체 식별자를 입력하십시오. |
| `consumptionLimit` | `{ "usd": 50 }` | 각 `limitPeriod`의 지출 상한으로, `usd`, `diem` 또는 둘 다로 지정합니다. 상한을 두지 않으려면 해당 통화를 생략하거나 `null`로 설정하십시오. USD 상한은 USD, 번들 크레딧 및 획득 크레딧을 합산하여 계산합니다. |
| `limitPeriod` | `EPOCH`, `MONTH`, `LIFETIME` | 상한이 초기화되는 시점입니다. 기본값인 `EPOCH`는 매일 00:00 UTC에, `MONTH`는 매월 1일(UTC)에 초기화되며, `LIFETIME`은 초기화되지 않습니다. |
| `expiresAt` | `"2027-06-30"` | 날짜 또는 `"2027-06-30T23:59:59Z"`와 같은 UTC 시간입니다. 날짜만 지정하면 해당 일의 00:00 UTC를 의미합니다. 만료되지 않는 키를 만들려면 생략하십시오. |
| `modelPrivacy` | `ALL`, `PRIVATE_TEXT`, `PRIVATE_ONLY` | 기본값인 `ALL`은 모든 모델을 허용합니다. `PRIVATE_TEXT`는 텍스트 및 임베딩 모델에 Private, TEE 또는 E2EE 모델을 요구합니다. `PRIVATE_ONLY`는 모든 모델에 이를 요구합니다. |
| `ipAllowlist` | `["11.22.33.0/24"]` | 최대 100개의 공인 IPv4 또는 IPv6 주소 또는 CIDR 범위입니다. 빈 목록은 모든 IP를 허용합니다. |

분당 최대 20개의 키를 생성할 수 있으며, 활성 키는 최대 500개까지 유지할 수 있습니다. 더 필요한 경우 지원팀에 문의하십시오.

> [!TIP]
>
> 에이전트를 구축하고 계신가요? Base에서 스테이킹된 VVV를 보유한 지갑은 Venice 계정 없이도 자체 키를 발급할 수 있습니다. [자율 에이전트 API 키 생성](https://docs.venice.ai/ko/guides/integrations/generating-api-key-agent.md)을 참조하십시오.

## 사용량 추적하기

| 확인할 내용 | 호출 | 확인할 필드 |
| - | - | - |
| 한 키가 이번 기간에 지출한 금액 | `GET /api_keys/{id}` | `currentPeriodUsage` |
| 각 키가 최근 7일 동안 지출한 금액 | `GET /api_keys` | `usage.trailingSevenDays` |
| 일별 키당 지출 | `GET /billing/usage-analytics` | `byKey`, `byKeyDaily` |
| 청구된 키가 포함된 모든 요금 내역 | `GET /billing/usage-history` | `apiKeyId` |
| 키가 지금 지출할 수 있는지 여부 | 해당 키로 호출한 `GET /api_keys/rate_limits` | `accessPermitted`, `balances` |
| 속도 제한에 걸리고 있는 키 | `GET /api_keys/rate_limits/log` | `apiKeyId`, `modelId` |

### 단일 키

```bash cURL theme={"system"}
curl https://api.venice.ai/api/v1/api_keys/e28e82dc-9df2-4b47-b726-d0a222ef2ab5 \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"
```

```python Python theme={"system"}
key = requests.get(f"{BASE}/api_keys/{key_id}", headers=HEADERS).json()["data"]
```

```javascript Node.js theme={"system"}
const res = await fetch(`${BASE}/api_keys/${keyId}`, { headers });
const { data: key } = await res.json();
```

```json Response (trimmed) theme={"system"}
{
  "data": {
    "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
    "description": "cust:acme",
    "consumptionLimits": { "usd": 50, "diem": null, "vcu": null },
    "limitPeriod": "MONTH",
    "currentPeriodUsage": { "usd": "12.5000", "diem": "0.0000" },
    "usage": { "trailingSevenDays": { "usd": "4.2000", "diem": "0.0000", "vcu": "0.0000" } },
    "lastUsedAt": "2026-11-03T14:05:00.000Z"
  }
}
```

이 키는 이번 달 $50 중 $12.50를 사용했습니다. `currentPeriodUsage`는 USD 또는 DIEM 상한이 있는 키에만 표시되며, 사용량 금액은 소수점 이하 네 자리의 문자열입니다. 응답은 `consumptionLimits`(복수형)를 반환하지만, 요청에서는 `consumptionLimit`(단수형)을 보냅니다.

### 시간에 따른 키별 지출

`GET /billing/usage-analytics`는 `byKey`에 키별 합계를, `byKeyDaily`에 일별 한 행씩을 반환하므로 바로 차트로 만들 수 있습니다. `lookback`(기본값 `7d`, 최대 `90d`) 또는 최대 90일 범위의 `startDate`와 `endDate` 쌍을 전달하십시오. 결과는 10분 동안 캐시됩니다.

```bash cURL theme={"system"}
curl "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=30d" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"
```

```json Response (trimmed) theme={"system"}
{
  "byKey": [
    {
      "apiKeyId": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
      "description": "cust:acme",
      "totalUsd": 12.5,
      "totalDiem": 0,
      "totalUnits": 1830000
    }
  ]
}
```

### 키별 모든 요금 내역

`GET /billing/usage-history`는 모든 요금 내역을 나열하며, 각 항목에는 청구된 `apiKeyId`가 포함됩니다. 지출을 대사하거나 자체 고객에게 요금을 청구할 때 사용하십시오. 항목은 오래된 순으로 반환됩니다. `nextCursor`가 `null`이 될 때까지 해당 값을 단독으로 `cursor`로 다시 보내십시오. CSV로 받으려면 `Accept: text/csv`를 보내십시오.

```bash cURL theme={"system"}
curl -G https://api.venice.ai/api/v1/billing/usage-history \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  --data-urlencode "startTimestamp=2026-10-01T00:00:00Z" \
  --data-urlencode "endTimestamp=2026-11-01T00:00:00Z"
```

```python Python theme={"system"}
from collections import defaultdict

spend = defaultdict(float)
params = {"startTimestamp": "2026-10-01T00:00:00Z", "endTimestamp": "2026-11-01T00:00:00Z"}
while True:
    page = requests.get(f"{BASE}/billing/usage-history", headers=HEADERS, params=params).json()
    for entry in page["data"]:
        if entry["apiKeyId"]:
            spend[(entry["apiKeyId"], entry["currency"])] -= entry["amount"]
    if page["nextCursor"] is None:
        break
    params = {"cursor": page["nextCursor"]}
```

요금 항목의 `amount`는 음수이므로, 루프에서 이를 빼서 키 및 통화별 양수 합계를 구합니다. `apiKeyId`가 없는 항목은 Venice 웹 앱에서 발생했거나 크레딧 구매와 같은 계정 항목입니다.

### 키가 지금 지출할 수 있는지 여부

`GET /api_keys/rate_limits`는 모든 키로 호출할 수 있으며, 호출한 키에 대한 정보를 보고합니다. `accessPermitted`는 키가 지금 지출할 수 있는지 여부를 알려주고, `balances`는 남은 지출 가능 금액을 보여줍니다.

```bash cURL theme={"system"}
curl https://api.venice.ai/api/v1/api_keys/rate_limits \
  -H "Authorization: Bearer $VENICE_API_KEY"
```

Admin 키로 `GET /api_keys/rate_limits/log`를 호출하면 최근 50건의 속도 제한 발생 내역이 각각의 `apiKeyId` 및 `modelId`와 함께 반환됩니다.

## 한도 및 설정 변경하기

키의 `id`와 변경하려는 필드만 보내십시오. 나머지는 그대로 유지됩니다. 다음 예제는 상한을 월 \$100로 상향합니다:

```bash cURL theme={"system"}
curl -X PATCH https://api.venice.ai/api/v1/api_keys \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
    "consumptionLimit": { "usd": 100 }
  }'
```

```python Python theme={"system"}
requests.patch(f"{BASE}/api_keys", headers=HEADERS, json={
    "id": key_id,
    "consumptionLimit": {"usd": 100},
}).raise_for_status()
```

```javascript Node.js theme={"system"}
await fetch(`${BASE}/api_keys`, {
  method: "PATCH",
  headers,
  body: JSON.stringify({ id: keyId, consumptionLimit: { usd: 100 } }),
});
```

다른 변경을 하려면 대신 다음 필드 중 하나를 보내십시오:

| 목적 | 보낼 값 |
| - | - |
| 상한 제거 | `"consumptionLimit": { "usd": null }` |
| 상한을 매일이 아닌 매월 초기화 | `"limitPeriod": "MONTH"` |
| 상한을 일회성 예산으로 설정 | `"limitPeriod": "LIFETIME"` |
| 만료 연장 | `"expiresAt": "2027-12-31"` |
| 만료 제거 | `"expiresAt": null` |
| 자체 서버의 요청만 허용 | `"ipAllowlist": ["11.22.33.0/24"]` |
| 다시 모든 IP의 요청 허용 | `"ipAllowlist": []` |
| 프라이빗 모델만 허용 | `"modelPrivacy": "PRIVATE_ONLY"` |
| 키 이름 변경 | `"description": "cust:acme-prod"` |

새 `limitPeriod`는 즉시 적용되므로, `LIFETIME`으로 전환하면 키의 과거 지출 전체가 상한에 반영됩니다. `apiKeyType`은 변경할 수 없으므로 대신 새 키를 생성하십시오.

## 키 폐기 또는 교체하기

```bash cURL theme={"system"}
curl -X DELETE \
  "https://api.venice.ai/api/v1/api_keys?id=e28e82dc-9df2-4b47-b726-d0a222ef2ab5" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"
```

```python Python theme={"system"}
requests.delete(f"{BASE}/api_keys", headers=HEADERS, params={"id": key_id}).raise_for_status()
```

```javascript Node.js theme={"system"}
await fetch(`${BASE}/api_keys?id=${keyId}`, { method: "DELETE", headers });
```

응답은 `{ "success": true }`입니다. 폐기는 즉시 적용됩니다. 해당 키의 다음 요청은 `401 Authentication failed`를 받으며, 키는 `GET /api_keys`에서 사라집니다. 과거 요금 내역은 사용 내역에 그대로 남습니다.

다운타임 없이 키를 교체하려면:

**1. 대체 키 생성**

동일한 설정으로 새 키를 생성하고 비밀 값을 저장합니다.

**2. 배포**

앱이 새 비밀 값을 사용하도록 전환합니다.

**3. 기존 키 폐기**

`GET /api_keys`에서 기존 키의 `lastUsedAt`이 더 이상 변하지 않으면 해당 키를 삭제합니다.

## 호출자에게 표시될 수 있는 오류

| 상태 | 메시지 | 해결 방법 |
| - | - | - |
| `402` | `API key USD spend limit exceeded...` 또는 DIEM에 대한 동일한 메시지 | 상한을 상향하거나 제거하거나, 다음 기간을 기다리십시오. 계정 자체에는 아직 자금이 있을 수 있습니다. |
| `403` | 키의 프라이버시 설정에서 해당 모델을 허용하지 않음 | Private, TEE 또는 E2EE 모델을 사용하거나 `modelPrivacy`를 변경하십시오. |
| `403` | `This API key is restricted to configured IP addresses...` | 호출자의 IP를 `ipAllowlist`에 추가하십시오. |
| `401` | `Authentication failed` | 키가 폐기되었거나, 만료되었거나, 잘못 입력되었습니다. |
| `401` | `Admin API key required` | Inference 키로 키 관리 또는 청구 엔드포인트를 호출했습니다. |
| `429` | `Too many API key creation requests...` | 키 생성은 분당 20개로 제한됩니다. 잠시 기다린 후 다시 시도하십시오. |
| `400` | `Maximum number of active API keys (500) reached...` | 더 이상 사용하지 않는 키를 폐기하거나 지원팀에 문의하십시오. |

전체 목록은 [Error Codes](https://docs.venice.ai/ko/api-reference/error-codes.md)를 참조하십시오.

## 모범 사례

* Admin 키는 서버에 보관하고, 외부에는 Inference 키만 나누어 주십시오.
* 모든 앱, 환경 및 고객에게 전용 키를 발급하여 각각을 개별적으로 추적하고 폐기할 수 있도록 하십시오.
* `description`에 자체 식별자를 입력하십시오. 사용량 분석에서 이 값으로 키를 표시합니다.
* 다른 사람에게 제공하는 모든 키에는 상한과 만료를 설정하고, 서버 간 키는 `ipAllowlist`로 자체 IP에 고정하십시오.

## API 레퍼런스

> [card] [API 키 생성](https://docs.venice.ai/ko/api-reference/endpoint/api_keys/create.md)
>
> 생성 시 허용되는 모든 필드.

> [card] [API 키 업데이트](https://docs.venice.ai/ko/api-reference/endpoint/api_keys/update.md)
>
> 한도, 만료, 프라이버시 및 IP 변경.

> [card] [API 키 목록 조회](https://docs.venice.ai/ko/api-reference/endpoint/api_keys/list.md)
>
> 모든 활성 키와 사용량.

> [card] [API 키 삭제](https://docs.venice.ai/ko/api-reference/endpoint/api_keys/delete.md)
>
> 키 폐기.

> [card] [사용량 분석](https://docs.venice.ai/ko/api-reference/endpoint/billing/usage-analytics.md)
>
> 키, 모델 및 일별 지출.

> [card] [사용 내역](https://docs.venice.ai/ko/api-reference/endpoint/billing/usage-history.md)
>
> API 키가 포함된 모든 요금 내역.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.