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

# 검수 차단 사유 조회

> GET /v1/video/generations/moderation-result/{task_id}

## 소개

Seedance 2.0 작업이 **콘텐츠 안전 / 저작권 / 공인 / 실인물 얼굴** 정책으로 `failed`된 경우, `GET /v1/video/generations/{task_id}`는 일반적인 오류만 반환할 수 있습니다. 업스트림 차단 카테고리와 세부 정보는 이 엔드포인트를 사용하세요.

<Warning>
  **기본적으로 비활성화**—BytePlus 화이트리스트 필요. BytePlus 영업팀에 문의하고 관리자가 채널에서 "moderation result query"를 활성화해야 합니다. 미활성화 시: `403 channel_not_whitelisted`.
</Warning>

## 인증

<ParamField header="Authorization" type="string" required>
  Bearer Token, 예: `Bearer sk-xxxxxxxxxx`
</ParamField>

## 경로 매개변수

<ParamField path="task_id" type="string" required>
  실패한 작업의 `task_id`(`seedance-2-0` / `seedance-2-0-fast`만 해당)
</ParamField>

## 제한

| 제한   | 설명                                                  |
| ---- | --------------------------------------------------- |
| 모델   | seedance-2-0 시리즈 실패 작업만                             |
| 시간 창 | 생성 후 **14일** 이내; 초과 시 `400 query_window_expired`    |
| 상태   | `failed`만 해당; 그 외 `400 invalid_task_status`         |
| 소유권  | 본인 작업만(토큰 `user_id`)                                |
| 속도   | 채널당 **10 QPM**; `429 rate_limited`                  |
| 캐시   | 첫 성공 조회가 저장됨; 반복 조회는 `"cached": true` 반환, QPM 소비 없음 |

## 예제

```bash theme={null}
curl "https://api.gravitex.ai/v1/video/generations/moderation-result/cgt-20260430135030-xxxxx" \
  -H "Authorization: Bearer sk-xxxxxxxxxx"
```

## 응답

```json theme={null}
{
  "task_id": "cgt-20260430135030-xxxxx",
  "block_reasons": [
    {
      "label": "Celebrity",
      "sub_label": "Celebrity",
      "detail": "Potentially contains Public Figures."
    },
    {
      "label": "Copyright",
      "sub_label": "IP",
      "detail": "Potential copyright restriction. Potentially related content: Spider-Man: Homecoming-Peter Parker"
    }
  ],
  "cached": false,
  "queried_at": 1715140800
}
```

### block\_reasons 필드

| 필드          | 설명                                                                                       |
| ----------- | ---------------------------------------------------------------------------------------- |
| `label`     | 카테고리: `Safety` / `Copyright` / `Celebrity` / `Deepfake`                                  |
| `sub_label` | 하위 카테고리: `Safety`; `Copyright` 하위 `IP` / `Other`; `Celebrity`; `Deepfake` 하위 `RealHuman` |
| `detail`    | 사람이 읽을 수 있는 세부 정보; IP 또는 공인 이름 포함 가능                                                     |

## 일반적인 오류

| HTTP  | `error.type`              | 의미                                                           |
| ----- | ------------------------- | ------------------------------------------------------------ |
| `400` | `invalid_request`         | `task_id` 누락                                                 |
| `400` | `invalid_task_status`     | 작업이 `failed`가 아님; 조회할 검수 차단 없음                               |
| `400` | `unsupported_model`       | seedance-2-0 시리즈가 아님                                         |
| `400` | `query_window_expired`    | 14일 조회 창 밖                                                   |
| `403` | `channel_not_whitelisted` | 채널에서 검수 결과 조회 미활성화                                           |
| `404` | `not_found`               | 작업 없음, 또는 업스트림 `NotFound.Id`(검수 차단 아님 / 잘못된 ID / 채널 미화이트리스트) |
| `429` | `rate_limited`            | 채널 10 QPM 제한 초과; 나중에 재시도                                     |
| `502` | `upstream_error`          | 404가 아닌 업스트림 오류; `error.message` 참조                          |

오류 본문은 다른 엔드포인트와 동일한 형식입니다. 예: 화이트리스트 미활성화 시:

```json theme={null}
{
  "error": {
    "message": "moderation query is not enabled on this channel; please contact admin to apply for BytePlus whitelist activation",
    "type": "channel_not_whitelisted"
  }
}
```

> `block_reasons` 배열이 비어 있으면 작업이 `failed`였지만 **검수에 의해 차단되지 않음**(다른 실패 원인).