> 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 서비스를 이용할 때(서버리스 클라우드 API, 배치 처리 등 포함, 이에 국한되지 않음) 청구 귀속은 프로젝트의 폴더가 아니라 요청에 포함된 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 저장은 작업 공간에 귀속됩니다(한 폴더에 두 프로젝트가 모두 포함되지 않음) ``` ### 폴더 작업 메뉴 폴더 제어는 폴더의 작업 메뉴(점 세 개 아이콘)에 있습니다. 폴더 목록에서 또는 폴더 이름 옆의 폴더 프로젝트 페이지 헤더에서 열 수 있습니다. 여기에는 "폴더 사용량", "폴더 API 키", "권한 설정"이 있습니다. ### 사용량 보기 폴더별로 세분화된 사용량을 포함해 작업 공간의 크레딧 사용량 페이지에서 사용량을 볼 수 있으며, 귀속 필터를 다음으로 전환할 수 있습니다: **폴더**. 자세히 [사용량을 청구 폴더로 필터링하는 방법](/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 잠김` 상태 코드 * 해당 폴더에는 새로운 과금 대상 사용량이 기록되지 않습니다 "모든 하위 폴더의 사용량 일시 중지"를 전환하여 폴더와 그 모든 하위 폴더를 한 번에 일시 중지할 수도 있습니다. 그러면 선택한 폴더와 그 아래에 중첩된 모든 폴더의 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개 요청) |