> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/get-started/ko/platform/billing-and-plans/billing-folders.md). # 청구 폴더 ## 소개 {% hint style="info" %} Billing Folders는 **프리미엄** Enterprise 요금제에서 사용할 수 있는 기능입니다. 작업 공간에서 Billing Folders를 사용하도록 설정하려면 [Roboflow 영업팀](https://roboflow.com/sales) 또는 계정 담당자에게 문의하세요. 사용 가능한 요금제에 대한 자세한 내용은 [요금 페이지를 방문하세요](https://roboflow.com/pricing). {% endhint %} 활성화되면 모든 사용량(예: 학습, 추론, 이미지 저장, 라벨링 등)이 사용 중인 프로젝트를 포함하는 폴더에 자동으로 할당됩니다. 이를 통해 조직은 팀, 부서 또는 고객 전반에 걸쳐 세분화된 비용 가시성과 지출 통제를 확보할 수 있습니다. ### 사용량 할당 방식 Billing Folders가 활성화되면 작업 공간의 각 폴더는 자체 API 키를 받습니다. 폴더 내 프로젝트에서 발생하는 모든 청구 대상 사용량은 해당 폴더의 API 키로 추적됩니다. 즉, 사용량 보고서와 대시보드에서 각 폴더가 얼마나 사용하고 있는지 정확히 확인할 수 있습니다. {% hint style="info" %} 사용량 할당은 자동으로 이루어집니다. 사용량을 수동으로 폴더에 할당할 필요가 없습니다. 사용량은 프로젝트에서 상위 폴더로 전달됩니다. {% endhint %} #### API 또는 배포 사용량 API 키를 사용하여 Roboflow 서비스를 이용할 때(Serverless API, Batch Processing 등을 포함하되 이에 국한되지 않음) 청구 할당은 프로젝트의 폴더가 아니라 요청에 포함된 API 키를 따릅니다. 작업 공간 수준 API 키로 보낸 요청은 사용된 모델이 폴더 안의 프로젝트에 속하더라도 작업 공간에 할당됩니다. 직접 API 또는 배치 사용량을 폴더에 할당하려면 해당 폴더의 API 키로 요청하세요. #### 이미지 저장 할당 이미지 저장은 이미지를 참조하는 프로젝트가 포함된 폴더에 할당됩니다. 같은 폴더 내 여러 프로젝트(또는 같은 상위 폴더의 하위 폴더들)에서 이미지가 공유되는 경우, 저장 공간은 해당 이미지를 사용하는 모든 프로젝트를 포함하는 가장 깊은 폴더에 할당됩니다: ``` 워크스페이스 ├── 폴더 A │ ├── 프로젝트 1 ← image.jpg │ └── 프로젝트 2 ← image.jpg (공유됨) └── 폴더 B └── 프로젝트 3 image.jpg 저장은 폴더 A에 할당됩니다(이를 참조하는 모든 프로젝트를 포함하는 가장 깊은 폴더) ``` 공통 상위 폴더가 없는 서로 다른 루트 폴더의 프로젝트 간에 이미지가 공유되는 경우, 저장 공간은 작업 공간 수준에서 할당됩니다: ``` 워크스페이스 ├── 폴더 A │ └── 프로젝트 1 ← image.jpg └── 폴더 B └── 프로젝트 2 ← image.jpg (공유됨) image.jpg 저장은 작업 공간에 할당됩니다(두 프로젝트를 모두 포함하는 단일 폴더가 없음) ``` ### 폴더 작업 메뉴 폴더 제어는 폴더의 작업 메뉴(점 3개 아이콘)에 있습니다. 폴더 목록 또는 폴더 이름 옆에 있는 폴더 프로젝트 페이지의 헤더에서 열 수 있습니다. 여기에는 "폴더 사용량", "폴더 API 키", "권한 설정"이 포함되어 있습니다. ### 사용량 보기 작업 공간의 크레딧 사용량 페이지에서 폴더별로 세분화된 사용량을 확인할 수 있으며, 할당 필터를 **폴더**. Learn [에서 청구 폴더 기준으로 사용량을 필터링하는 방법](/get-started/ko/platform/billing-and-plans/credits/view-credit-usage.md#usage-chart) 또는 [에서 일반적으로 사용량을 보는 방법](/get-started/ko/platform/billing-and-plans/credits/view-credit-usage.md) 특정 폴더의 사용량으로 바로 이동하려면 해당 폴더의 작업 메뉴에서 "폴더 사용량"을 선택하세요. ### 폴더 사용량 일시 중지 및 재개 작업 공간 관리자는 폴더 내의 모든 청구 대상 사용량을 일시적으로 중지할 수 있습니다. 이는 비용을 통제하거나 실수로 인한 사용을 방지하는 데 유용합니다. #### 폴더 일시 중지 폴더를 일시 중지하려면 폴더의 작업 메뉴에서 "폴더 API 키"를 선택한 다음 "폴더 사용량 일시 중지"를 전환하고, 나타나는 메시지에서 확인하세요.
폴더가 일시 중지되면: * 해당 폴더에 속한 모든 API 키가 비활성화됩니다 * 해당 폴더에 대해 사용량이 발생하는 모든 API 요청은 `423 Locked` 상태 코드와 함께 거부됩니다 * 폴더에 대해 새로운 청구 대상 사용량은 기록되지 않습니다 "모든 하위 폴더 사용량 일시 중지"를 전환하면 폴더와 그 모든 하위 폴더를 한 번에 일시 중지할 수도 있습니다. 이렇게 하면 선택한 폴더와 그 아래에 중첩된 모든 폴더의 API 키가 비활성화됩니다. #### 폴더 재개 일시 중지된 폴더를 재개하려면 "폴더 API 키" 모달을 다시 열고 일시 중지 제어를 끈 다음 확인하세요. 이렇게 하면 폴더의 API 키가 다시 활성화되고 정상 작동이 복원됩니다. 마찬가지로 폴더와 그 모든 하위 항목을 한 번에 재개할 수도 있습니다. 재개는 폴더 일시 중지 기능으로 중지된 키에만 영향을 줍니다. 다른 이유로 비활성화된 키에는 영향을 주지 않습니다. ### 폴더 API 키 Billing Folders가 활성화되면 각 폴더는 자동으로 자체 API 키를 받습니다. 이 키들은 어떤 폴더에 청구 대상 사용량이 속하는지 추적하기 위해 내부적으로 사용됩니다. * **키 보기**: 폴더와 연결된 API 키를 보려면 폴더의 작업 메뉴에서 "폴더 API 키"를 선택하세요. * **자동 생성**: 폴더가 생성되거나 작업 공간에서 Billing Folders가 처음 활성화될 때 API 키가 자동으로 생성됩니다. 수동으로 만들 필요가 없습니다. ### 일반적인 시나리오 | 시나리오 | 발생하는 일 | | ------------------------ | ---------------------------------------------------------------------------- | | **프로젝트를 다른 폴더로 이동** | 해당 프로젝트의 향후 사용량은 새 폴더에 할당됩니다. 과거 사용량은 원래 폴더에 계속 할당됩니다. | | **폴더 삭제** | 폴더가 작업 공간에서 제거됩니다. 하위 프로젝트와 하위 폴더는 상위 폴더로 재할당됩니다. 과거 사용량 데이터는 청구 보고서에 보존됩니다. | | **새 폴더 만들기** | 새 폴더에는 청구 할당을 위한 API 키가 자동으로 부여됩니다. 추가 설정은 필요하지 않습니다. | | **Billing Folders 비활성화** | 폴더 수준 할당이 중지됩니다. 새로운 사용량은 작업 공간 수준에서만 추적됩니다. 폴더 청구 기간의 과거 사용량 데이터는 보존됩니다. | ### 사용량 보고서 API 다음의 [청구 사용량 보고서 REST API](#http-api). ## HTTP API **엔드포인트** `POST` `https://api.roboflow.com/{workspace_url}/billing-usage-report` **인증** 다음 권한 범위를 가진 API 키 `workspaceStats.read` 를 쿼리 매개변수로 전달합니다(`?api_key=YOUR_API_KEY`). **요청 제한** API 키당 분당 10개 요청. #### 요청 매개변수 모든 매개변수는 요청 본문에 JSON으로 전달됩니다. 모두 선택 사항입니다. | 매개변수 | 유형 | 기본값 | 설명 | | ------------------ | ------------- | ----- | ---------------------------------------------------------------------------------------------------- | | `startAt` | 문자열(ISO 8601) | 7일 전 | 보고 기간의 시작(포함) | | `endAt` | 문자열(ISO 8601) | 지금 | 보고 기간의 종료(미포함) | | `api_key_prefixes` | 문자열 또는 문자열\[] | 모든 키 | 특정 API 키 접두사로 필터링합니다. 각 접두사는 전체 API 키의 처음 5자입니다(예: `rf_ab` 키의 경우 `rf_abCdEfGhIjK...`). 정확히 일치해야 합니다. | | `features` | 문자열 또는 문자열\[] | 모든 기능 | 특정 청구 기능으로 필터링 | #### 예시 {% tabs %} {% tab title="기본" %} 기본값은 최근 7일, 모든 기능, 모든 API 키입니다. ```shellscript curl -X POST "https://api.roboflow.com/my-workspace/billing-usage-report?api_key=$ROBOFLOW_API_KEY" ``` {% endtab %} {% tab title="사용자 지정 날짜 범위" %} ```shellscript curl -X POST "https://api.roboflow.com/my-workspace/billing-usage-report?api_key=$ROBOFLOW_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "startAt": "2025-01-01T00:00:00.000Z", "endAt": "2025-02-01T00:00:00.000Z" }' ``` {% endtab %} {% tab title="기능별 필터링" %} ```shellscript curl -X POST "https://api.roboflow.com/my-workspace/billing-usage-report?api_key=$ROBOFLOW_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "features": ["train", "serverless-inference-run"] }' ``` {% endtab %} {% tab title="모든 매개변수" %} ```shellscript curl -X POST "https://api.roboflow.com/my-workspace/billing-usage-report?api_key=$ROBOFLOW_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "startAt": "2025-01-01T00:00:00.000Z", "endAt": "2025-02-01T00:00:00.000Z", "api_key_prefixes": ["rf_ab", "rf_de"], "features": ["train", "serverless-inference-run"] }' ``` {% endtab %} {% endtabs %} #### 응답 스키마 API는 사용량 기록의 JSON 배열을 반환합니다: ```json [ { "api_key_prefix": "rf_ab", "feature": "train", "total_credits_used": 150.5, "usage_events": 12, "earliest_usage": "2025-01-02T10:30:00.000Z", "latest_usage": "2025-01-28T14:15:00.000Z", "billing_entity_id": "folder-id-123", "billing_entity_name": "My Project Folder", "billing_entity_type": "folder" } ] ``` | 필드 | 유형 | 설명 | | --------------------- | --- | ----------------------------------------------------- | | `api_key_prefix` | 문자열 | 사용량과 연결된 API 키의 처음 5자 | | `feature` | 문자열 | 청구 기능 식별자(예: `"train"`, `"serverless-inference-run"`) | | `total_credits_used` | 숫자 | 이 키/기능 조합에 대해 소비된 총 크레딧 | | `usage_events` | 숫자 | 개별 사용 이벤트 수 | | `earliest_usage` | 문자열 | 해당 범위의 첫 번째 사용 이벤트의 ISO 타임스탬프 | | `latest_usage` | 문자열 | 해당 범위의 마지막 사용 이벤트의 ISO 타임스탬프 | | `billing_entity_id` | 문자열 | 이 사용량을 소유한 폴더 ID 또는 작업 공간 ID | | `billing_entity_name` | 문자열 | 청구 엔터티의 사람이 읽을 수 있는 이름 | | `billing_entity_type` | 문자열 | 다음 중 하나 `"folder"` 또는 `"workspace"` | #### 오류 코드 | 상태 | 설명 | | ----- | ------------------------------------------------------------- | | `400` | 이 작업 공간에 대해 Billing Folders가 활성화되어 있지 않거나, 요청 매개변수가 유효하지 않습니다 | | `401` | API 키가 유효하지 않거나 누락되었거나, 권한이 부족합니다 | | `423` | 폴더의 사용량이 일시 중지되었습니다 | | `429` | 요청 한도 초과(분당 10개 요청) |