> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 개인 액세스 토큰

> 원하는 권한과 만료 기간으로 개인 액세스 토큰을 만들어 API 키를 관리하고, 잔액과 결제 내역을 읽고, 요청별 사용량을 USD 기준으로 대조하세요.

# 개인 액세스 토큰

개인 액세스 토큰은 BeatAPI 계정을 자동화하기 위한 자격 증명입니다. 토큰마다 권한을 직접 정하므로 스크립트는 허용한 일만 할 수 있습니다. 잔액 조회, API 키 관리, 결제 내역 조회, 작업이나 텍스트 요청별 비용 같은 계정 데이터 조회가 가능합니다. 모델, 작업, 워크플로 요청에는 계속 API 키를 사용합니다.

## 개인 액세스 토큰과 API 키

|          | 개인 액세스 토큰                                                     | API 키                               |
| -------- | ------------------------------------------------------------- | ----------------------------------- |
| 접두사      | `nap_`                                                        | `sk-`                               |
| 용도       | 계정 자동화(예: `GET /v1/account`, `GET /v1/account/usage/records`) | 모델, 작업, 워크플로 요청                     |
| 개수       | 계정당 최대 20개, 각각 고유한 이름                                         | 필요한 만큼                              |
| 한도       | 선택한 권한. 자체 모델·IP·지출 제한 없음                                     | 키별 모델·IP·지출 제한(선택)                  |
| 만료       | 선택: 7, 30, 90, 365일 또는 만료 없음                                  | 키별 만료(선택)                           |
| 사용 가능한 곳 | `/v1/account` 및 `GET /v1/usage` 아래의 엔드포인트                     | 모델, 작업, 워크플로 엔드포인트와 `GET /v1/usage` |

## 토큰 만들기와 관리

1. [대시보드](https://beatapi.io/dashboard/security)에 로그인하고 **계정 보안**을 여세요.
2. **개인 토큰 만들기**를 선택하고 이름을 입력한 뒤, 토큰에 필요한 권한을 체크하고 만료 기간을 고르세요: 7, 30(기본값), 90, 365일 또는 만료 없음.
3. 인증 단계를 마친 뒤 토큰을 복사하세요. 전체 토큰은 한 번만 표시되며, 창을 닫으면 페이지에서 사라집니다.
4. 자동화를 실행하는 곳에 시크릿으로 저장하세요(예: `BEATAPI_PERSONAL_TOKEN`).

계정당 토큰은 최대 20개입니다. 실행 위치를 알 수 있는 이름을 붙이고 필요한 권한만 부여하세요. 토큰 목록에는 각 토큰의 이름, 권한, 만료일, 마지막 사용 시각이 표시됩니다.

토큰 이름은 인증 없이 언제든 바꿀 수 있습니다. 권한 변경과 토큰 폐기에는 인증이 필요합니다. 권한을 바꿔도 같은 토큰에 적용되므로 다시 배포할 필요가 없습니다. **폐기**하면 토큰이 삭제되고, 이 토큰을 쓰는 도구는 즉시 접근 권한을 잃습니다. 토큰은 신뢰할 수 있는 서버에만 두고, 브라우저 코드, 모바일 앱, 공유 저장소에는 절대 넣지 마세요.

여러 토큰을 지원하기 전에 만든 토큰은 기존 권한으로 계속 동작합니다.

## 권한

각 토큰에는 체크한 권한만 부여됩니다. 토큰에 없는 권한이 필요한 호출은 `403 forbidden`으로 거부되며, 메시지에 부족한 권한이 표시됩니다.

| 권한               | 허용 범위                                 | 엔드포인트                                                                                  |
| ---------------- | ------------------------------------- | -------------------------------------------------------------------------------------- |
| `usage:read`     | 사용 기록과 사용량 요약 조회                      | `GET /v1/account/usage/records`, `GET /v1/account/usage/records/{id}`, `GET /v1/usage` |
| `api_key:read`   | API 키 목록 및 조회(키는 마스킹됨)                | `GET /v1/account/keys`, `GET /v1/account/keys/{id}`                                    |
| `api_key:write`  | API 키 생성(전체 키는 한 번만 반환), 편집, 비활성화, 삭제 | `POST /v1/account/keys`, `PATCH /v1/account/keys/{id}`, `DELETE /v1/account/keys/{id}` |
| `api_key:reveal` | 기존 API 키의 전체 시크릿 조회                   | `POST /v1/account/keys/{id}/reveal`                                                    |
| `wallet:read`    | 결제(충전) 내역 조회                          | `GET /v1/account/payments`                                                             |
| `profile:read`   | 프로필, 잔액, 알림 설정 조회                     | `GET /v1/account`, `GET /v1/account/notifications`                                     |
| `profile:write`  | 알림 설정 변경                              | `PATCH /v1/account/notifications`                                                      |

토큰으로는 잔액 충전, 로그인·보안 설정 변경, 다른 토큰 관리를 할 수 없으며, 이런 작업은 대시보드에서만 할 수 있습니다. `api_key:reveal`은 키 시크릿을 꼭 읽어야 하는 토큰에만 부여하세요.

## 호출할 수 있는 엔드포인트

토큰은 `Authorization: Bearer <token>`으로 보내세요. 엔드포인트마다 표시된 권한이 필요합니다.

| 엔드포인트                                | 권한               | 용도                                     |
| ------------------------------------ | ---------------- | -------------------------------------- |
| `GET /v1/account`                    | `profile:read`   | 계정 프로필과 USD 잔액                         |
| `GET /v1/account/notifications`      | `profile:read`   | 잔액 알림 설정 조회                            |
| `PATCH /v1/account/notifications`    | `profile:write`  | 알림 유형, 임계값, 이메일 변경                     |
| `GET /v1/account/payments`           | `wallet:read`    | 결제 목록(최신순)                             |
| `GET /v1/account/keys`               | `api_key:read`   | API 키 목록(최신순)                          |
| `GET /v1/account/keys/{id}`          | `api_key:read`   | API 키 하나 조회                            |
| `POST /v1/account/keys`              | `api_key:write`  | API 키 만들기                              |
| `PATCH /v1/account/keys/{id}`        | `api_key:write`  | API 키 편집, 비활성화, 다시 활성화                 |
| `DELETE /v1/account/keys/{id}`       | `api_key:write`  | API 키 삭제                               |
| `POST /v1/account/keys/{id}/reveal`  | `api_key:reveal` | API 키의 전체 시크릿 조회                       |
| `GET /v1/account/usage/records`      | `usage:read`     | 과금된 요청 목록(최신순)                         |
| `GET /v1/account/usage/records/{id}` | `usage:read`     | 작업 ID나 요청 ID로 기록 하나 조회                 |
| `GET /v1/usage`                      | `usage:read`     | 계정 합계와 세부 내역. [빠른 시작](/quick-guide) 참고 |

`/v1/account` 엔드포인트는 API 키를 `403 forbidden`으로 거부합니다. `GET /v1/usage`는 API 키나 `usage:read` 권한이 있는 토큰 모두 받으며 같은 요약을 반환합니다. 응답은 `data`로 감싸져 있습니다. ID는 문자열, 시각은 Unix 초, 금액은 USD입니다. 목록은 `object`, `data`, `has_more`, `next_cursor`를 반환하며 `limit`(1–100, 기본값 20)과 `cursor`를 받습니다. 알 수 없는 쿼리 파라미터는 `400 bad_request`로 거부됩니다.

## 잔액 조회

`profile:read` 권한이 필요합니다.

```bash
curl https://api.beatapi.io/v1/account \
  -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN"
```

```json
{
  "data": {
    "object": "account",
    "id": "1042",
    "username": "ada",
    "display_name": "Ada",
    "email": "ada@example.com",
    "credit_balance": 42.5,
    "currency": "USD"
  }
}
```

## API 키 목록 조회

`api_key:read` 권한이 필요합니다. 키는 마스킹되어 앞부분 문자인 `key_prefix`만 반환됩니다. 키 하나를 읽으려면 `GET /v1/account/keys/{id}`를 사용하세요.

```bash
curl -G https://api.beatapi.io/v1/account/keys \
  -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \
  --data-urlencode "limit=20"
```

```json
{
  "data": {
    "object": "list",
    "data": [
      {
        "object": "api_key",
        "id": "1287",
        "title": "production",
        "key_prefix": "sk-Ab3d",
        "status": "active",
        "created_at": 1793200000,
        "last_used_at": 1793247312,
        "expires_at": null,
        "remaining_credits": null,
        "credits_used": 18.42,
        "models": [],
        "allowed_ips": []
      }
    ],
    "has_more": false
  }
}
```

## API 키 만들기

`api_key:write` 권한이 필요합니다. 필수 값은 `title`뿐입니다. `expires_at`(Unix 초), `remaining_credits`(USD), `models`, `allowed_ips`는 선택 사항이며, 생략하면 만료 없음, 지출 상한 없음, 모든 모델, 모든 IP 주소가 적용됩니다. 전체 키는 이 응답의 `key`에만 있고 이후 조회에서는 `key_prefix`만 반환되므로 지금 저장하세요.

```bash
curl -X POST https://api.beatapi.io/v1/account/keys \
  -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "ci-runner", "remaining_credits": 20, "models": ["deepseek-v4.1-flash"], "allowed_ips": ["203.0.113.7"]}'
```

```json
{
  "data": {
    "object": "api_key",
    "id": "1304",
    "title": "ci-runner",
    "key_prefix": "sk-Qm8R",
    "key": "sk-Qm8RExampleFullKeyShownOnlyInThisResponse",
    "status": "active",
    "created_at": 1793250000,
    "last_used_at": null,
    "expires_at": null,
    "remaining_credits": 20,
    "credits_used": 0,
    "models": ["deepseek-v4.1-flash"],
    "allowed_ips": ["203.0.113.7"]
  }
}
```

키를 편집하려면 `PATCH /v1/account/keys/{id}`로 `title`, `status`(`active` 또는 `disabled`), `expires_at`(만료 없음은 `null`), `remaining_credits`(무제한은 `null`), `models`(모든 모델은 `[]`), `allowed_ips` 중 원하는 값을 보내세요. `DELETE /v1/account/keys/{id}`는 `object`, `id`, `deleted: true`를 반환합니다.

## API 키 공개

`api_key:reveal` 권한이 필요하며, `api_key:read`와는 별개입니다. 키 목록을 볼 수 있는 토큰이라도 이 권한을 함께 부여하지 않으면 시크릿을 읽을 수 없습니다.

```bash
curl -X POST https://api.beatapi.io/v1/account/keys/1287/reveal \
  -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN"
```

```json
{
  "data": {
    "object": "api_key_secret",
    "id": "1287",
    "key": "sk-Ab3dExampleFullKey"
  }
}
```

## 결제 목록 조회

`wallet:read` 권한이 필요합니다. `status`는 `paid`(기본값), `pending`, `failed`, `expired`, `reviewing` 또는 `all`입니다. `currency`는 결제 통화로 `USD` 또는 `CNY`이며, `credits`는 결제로 추가되는 USD 잔액입니다.

```bash
curl -G https://api.beatapi.io/v1/account/payments \
  -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \
  --data-urlencode "status=paid" \
  --data-urlencode "limit=20"
```

```json
{
  "data": {
    "object": "list",
    "data": [
      {
        "object": "payment",
        "id": "5531",
        "order_no": "ORD20261027153012",
        "status": "paid",
        "amount_paid": 20,
        "currency": "USD",
        "credits": 20,
        "payment_method": "stripe",
        "created_at": 1793100000,
        "paid_at": 1793100042
      }
    ],
    "has_more": false
  }
}
```

## 알림 임계값 변경

`profile:write` 권한이 필요하며, `GET /v1/account/notifications`로 설정을 읽으려면 `profile:read` 권한이 필요합니다. `type`(`email` 또는 `none`), `threshold_credits`, `notification_email` 중 원하는 값을 보내세요. 사용하면서 잔액이 임계값 아래로 내려가면 BeatAPI가 알려 드립니다. `0`을 보내면 기본값이 적용됩니다. 응답은 변경된 설정이며, `effective_threshold_credits`가 현재 적용 중인 임계값입니다.

```bash
curl -X PATCH https://api.beatapi.io/v1/account/notifications \
  -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"threshold_credits": 5}'
```

```json
{
  "data": {
    "object": "notification_settings",
    "type": "email",
    "threshold_credits": 5,
    "effective_threshold_credits": 5,
    "default_threshold_credits": 1,
    "notification_email": "billing@example.com",
    "account_email": "ada@example.com"
  }
}
```

## 작업 하나 대조하기

작업 생성 응답의 `data.id`를 저장한 뒤 조회하세요.

```bash
curl https://api.beatapi.io/v1/account/usage/records/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ \
  -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN"
```

```json
{
  "data": {
    "object": "usage_record",
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "type": "image",
    "model": "seedream-5-pro",
    "task_id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "request_id": "202610290330051234567893f9a1c2eXy7Kp2Qd",
    "api_key": { "id": "1287", "title": "production", "key_prefix": "sk-Ab3d" },
    "status": "succeeded",
    "created_at": 1793244605,
    "currency": "USD",
    "credits_charged": 0.06,
    "credits_refunded": 0,
    "usage": { "images": 2 }
  }
}
```

텍스트 요청은 `X-BeatAPI-Request-Id` 응답 헤더의 요청 ID를 사용하세요. 텍스트 응답 본문의 `id`에 `chatcmpl-<request ID>`가 있다면 그 값도 쓸 수 있습니다. 작업 생성 호출의 요청 ID는 작업 ID와 같은 기록을 반환합니다.

## 사용 기록 목록 조회

```bash
curl -G https://api.beatapi.io/v1/account/usage/records \
  -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \
  --data-urlencode "start=2026-10-01T00:00:00Z" \
  --data-urlencode "end=2026-11-01T00:00:00Z" \
  --data-urlencode "limit=100"
```

```json
{
  "data": {
    "object": "list",
    "data": [
      {
        "object": "usage_record",
        "id": "20261029041512987654321b3f9a1c2eQm8Rt4Lw",
        "type": "text",
        "model": "deepseek-v4.1-flash",
        "request_id": "20261029041512987654321b3f9a1c2eQm8Rt4Lw",
        "api_key": { "id": "1287", "title": "production", "key_prefix": "sk-Ab3d" },
        "status": "succeeded",
        "created_at": 1793247312,
        "currency": "USD",
        "credits_charged": 0.002468,
        "credits_refunded": 0,
        "usage": { "input_tokens": 1200, "output_tokens": 350, "cached_tokens": 1024 }
      }
    ],
    "has_more": true,
    "next_cursor": "eyJ0IjoxNzkzMjQ3MzEyLCJpIjo5ODc2NTQzMn0"
  }
}
```

| 파라미터         | 의미                                                                       |
| ------------ | ------------------------------------------------------------------------ |
| `start`      | 포함할 가장 이른 `created_at`. Unix 초 또는 RFC 3339 형식(예: `2026-10-01T00:00:00Z`) |
| `end`        | 포함하지 않는 상한. 형식은 같습니다                                                     |
| `model`      | 공개 모델 ID(예: `seedream-5-pro`)                                            |
| `type`       | `text`, `image`, `video`, `workflow`, `data`, `realtime`, `other` 중 하나   |
| `api_key_id` | `api_key.id`에 있는 숫자 API 키 ID                                             |
| `limit`      | 페이지당 기록 수. 1\~100, 기본값 20                                                |
| `cursor`     | 이전 페이지의 `next_cursor`                                                    |

`has_more`가 `true`인 동안 `cursor`로 다음 페이지를 요청하세요. 알 수 없는 파라미터, 1–100 범위를 벗어난 `limit`, 밀리초 단위 타임스탬프는 무시되지 않고 `400 bad_request`로 거부됩니다.

## 사용 기록

| 필드                 | 의미                                                                                                                         |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `object`           | `usage_record`                                                                                                             |
| `id`               | 작업이면 작업 ID, 아니면 요청 ID                                                                                                      |
| `type`             | `text`, `image`, `video`, `workflow`, `data`, `realtime` 또는 `other`                                                        |
| `model`            | 공개 모델 ID                                                                                                                   |
| `task_id`          | 작업에만 있음                                                                                                                    |
| `request_id`       | 기록을 만든 호출의 요청 ID(알 수 있는 경우)                                                                                                |
| `api_key`          | 결제에 사용된 API 키의 `id`, `title`, `key_prefix`. 대시보드 플레이그라운드 사용은 `null`                                                        |
| `status`           | `queued`, `processing`, `succeeded`, `failed`, 또는 청구액이 전부 환불되었다면 `refunded`                                                |
| `created_at`       | Unix 초                                                                                                                     |
| `currency`         | `USD`                                                                                                                      |
| `credits_charged`  | 할인과 정산을 반영한 실제 결제 금액(USD, 소수점 이하 최대 6자리)                                                                                   |
| `credits_refunded` | 잔액으로 돌아온 USD                                                                                                               |
| `usage`            | 과금 수량: 텍스트는 `input_tokens`, `output_tokens`, `cached_tokens`, `cache_write_tokens`, 미디어는 `images`, `seconds`, `resolution` |

작업의 금액은 `GET /v1/tasks/{task_id}`의 `usage.credits_charged`, `usage.credits_refunded`와 일치합니다. 작업이 보류 금액보다 많거나 적게 정산되면 기록에는 정산된 합계가 표시됩니다. 내 기록만 읽을 수 있으며, 다른 계정의 ID는 `404 not_found`를 반환합니다.

## 오류

| 상태    | `code`         | 발생 조건                                                    |
| ----- | -------------- | -------------------------------------------------------- |
| `400` | `bad_request`  | 쿼리 파라미터나 본문 필드가 잘못되었거나, 쿼리에 알 수 없는 파라미터가 있습니다            |
| `401` | `unauthorized` | 토큰이 없거나, 알 수 없거나, 폐기되었거나, 만료되었습니다                        |
| `403` | `forbidden`    | 토큰에 엔드포인트가 요구하는 권한이 없거나(메시지에 표시됨) 계정 엔드포인트에 API 키를 보냈습니다 |
| `404` | `not_found`    | 계정에 해당 ID의 기록, 결제 또는 API 키가 없습니다                         |

오류는 표준 [오류 객체](/errors)를 사용합니다.