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

# Usage Query

> MPS 태스크 유형별 사용량(호출 수/처리 시간) 조회 API Reference

MPS 각 태스크 유형의 사용량을 조회합니다. 트랜스코딩 계열은 처리 시간(초), AIGC/분석 계열은 호출 횟수 기준으로 집계됩니다.

## 요청 방법

| 항목         | 값                                       |
| ---------- | --------------------------------------- |
| API Action | `DescribeUsageData`                     |
| 엔드포인트      | `mps.tencentcloudapi.com`               |
| API 버전     | `2019-06-12`                            |
| 인증         | TC3-HMAC-SHA256 (SecretId/SecretKey 서명) |
| 요청 방식      | HTTP POST, JSON                         |

동기 조회 API로 즉시 집계 결과를 반환합니다.

## 요청 파라미터

| 파라미터           | 타입              | 필수 여부 | 예시                               | 설명                                       |
| -------------- | --------------- | ----- | -------------------------------- | ---------------------------------------- |
| StartTime      | String          | 필수    | `2026-03-01T00:00:00+08:00`      | 조회 시작 시각(ISO 8601). 최근 90일 이내            |
| EndTime        | String          | 필수    | `2026-03-07T23:59:59+08:00`      | 조회 종료 시각(ISO 8601)                       |
| Types          | Array of String | 선택    | `["Transcode","Enhance","AIGC"]` | 태스크 유형 목록. 미지정 시 `Transcode`. 아래 유형 표 참조 |
| ProcessRegions | Array of String | 선택    | `["ap-guangzhou","ap-hongkong"]` | 처리 리전 목록. 여러 리전 지정 가능                    |

조회 가능한 태스크 유형은 다음과 같습니다.

| Type                    | 설명                  |
| ----------------------- | ------------------- |
| `Transcode`             | 트랜스코딩(기본값)          |
| `Enhance`               | 화질 개선               |
| `AIAnalysis`            | 지능 분석(오디오/영상 이해 포함) |
| `AIRecognition`         | 지능 인식               |
| `AIReview`              | 콘텐츠 심사              |
| `Snapshot`              | 스크린샷                |
| `AnimatedGraphics`      | 움직이는 이미지            |
| `AiQualityControl`      | 품질 검사               |
| `Evaluation`            | 영상 평가               |
| `ImageProcess`          | 이미지 처리              |
| `AddBlindWatermark`     | 디지털 워터마크 삽입         |
| `AddNagraWatermark`     | Nagra 워터마크 삽입       |
| `ExtractBlindWatermark` | 디지털 워터마크 추출         |
| `AIGC`                  | 이미지/영상 생성           |

## 응답 파라미터

| 파라미터                   | 타입              | 필수 여부 | 예시                                     | 설명                                                                        |
| ---------------------- | --------------- | ----- | -------------------------------------- | ------------------------------------------------------------------------- |
| Data                   | Array of Object | 항상    | 아래 응답 예시 참조                            | 태스크 유형별 사용량 목록. 조회 기간 사용량이 없으면 빈 배열                                       |
| Data.N.TaskType        | String          | 항상    | `Transcode`                            | 태스크 유형                                                                    |
| Data.N.Summary         | Array of Object | 항상    | -                                      | 일자별 요약 목록                                                                 |
| Data.N.Summary.N.Time  | String          | 항상    | `2026-03-08T00:00:00+08:00`            | 집계 일자                                                                     |
| Data.N.Summary.N.Count | Integer         | 항상    | `12`                                   | 해당 일 태스크 수                                                                |
| Data.N.Summary.N.Usage | Integer         | 항상    | `3600`                                 | 해당 일 사용량. 트랜스코딩/개선/이미지 처리 계열은 초(seconds), AIGC/분석/심사/품질 검사/평가/워터마크 계열은 횟수 |
| Data.N.Details         | Array of Object | 항상    | -                                      | 상세 사용량 목록                                                                 |
| RequestId              | String          | 항상    | `3c140219-cfe9-470e-b241-907877d6fb03` | 요청 식별자                                                                    |

## 호출 예시

```python theme={null}
import json
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.mps.v20190612 import mps_client, models

cred = credential.Credential("<SecretId>", "<SecretKey>")
http_profile = HttpProfile()
http_profile.endpoint = "mps.tencentcloudapi.com"
client = mps_client.MpsClient(cred, "ap-guangzhou", ClientProfile(httpProfile=http_profile))

# 최근 7일, 트랜스코딩 + AIGC 사용량
req = models.DescribeUsageDataRequest()
req.from_json_string(json.dumps({
    "StartTime": "2026-03-08T00:00:00+08:00",
    "EndTime": "2026-03-14T23:59:59+08:00",
    "Types": ["Transcode", "AIGC"]
}))
resp = client.DescribeUsageData(req)
print(resp.to_json_string())
```

```python theme={null}
# 여러 리전의 지능 분석(영상 이해) 사용량
req.from_json_string(json.dumps({
    "StartTime": "2026-02-12T00:00:00+08:00",
    "EndTime": "2026-03-14T23:59:59+08:00",
    "Types": ["AIAnalysis"],
    "ProcessRegions": ["ap-guangzhou", "ap-hongkong"]
}))
resp = client.DescribeUsageData(req)
print(resp.to_json_string())
```

## 응답 예시

```json theme={null}
{
  "Data": [
    {
      "TaskType": "Transcode",
      "Summary": [
        {"Time": "2026-03-08T00:00:00+08:00", "Count": 12, "Usage": 3600},
        {"Time": "2026-03-09T00:00:00+08:00", "Count": 8, "Usage": 2100}
      ],
      "Details": []
    }
  ],
  "RequestId": "3c140219-cfe9-470e-b241-907877d6fb03"
}
```

## 주의사항

<Warning>
  조회 기간은 최대 90일입니다. `Types`를 지정하지 않으면 `Transcode`만 집계되므로, 다른 유형이 필요하면 명시적으로 지정하세요.
</Warning>

<Note>
  대모델 오디오/영상 이해([Content Understanding](/mps/content-understanding)) 사용량은 `AIAnalysis` 유형에 포함됩니다. `Usage` 단위는 유형에 따라 다륩니다. 초 단위 유형은 분/시간으로 환산해 해석합니다.
</Note>