개인 액세스 토큰

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

개인 액세스 토큰과 API 키

토큰 만들기와 관리

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

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

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

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

권한

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

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

호출할 수 있는 엔드포인트

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

/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 권한이 필요합니다.

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

{
  "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}를 사용하세요.

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

{
  "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만 반환되므로 지금 저장하세요.

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"]}'

{
  "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와는 별개입니다. 키 목록을 볼 수 있는 토큰이라도 이 권한을 함께 부여하지 않으면 시크릿을 읽을 수 없습니다.

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

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

결제 목록 조회

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

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

{
  "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가 현재 적용 중인 임계값입니다.

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}'

{
  "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를 저장한 뒤 조회하세요.

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

{
  "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와 같은 기록을 반환합니다.

사용 기록 목록 조회

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"

{
  "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"
  }
}

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

사용 기록

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

오류

오류는 표준 오류 객체를 사용합니다.