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

# 멀티모달 입력

> 이미지·오디오·문서·아카이브·동영상을 콘텐츠 파트로 Starfort Guard API에 보내고, 파트별 결과를 응답으로 확인합니다 (Starfort v1.4 문서)

`user` 메시지의 `content`는 **콘텐츠 파트** 배열이 될 수 있으므로, 하나의 요청에 텍스트와 파일을 함께 담을 수 있습니다. **여섯 가지 Input Type**(Text, Image, Audio, Video, Document, Archive)이 있으며, Guardian은 [Input Type](/ko/v1.4/concepts/guardian)이 활성화된 각 파트를 검사합니다.

```json theme={"dark"}
{
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "Please review the attached file." },
      { "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0..." } }
    ]
  }],
  "processType": "input"
}
```

## 콘텐츠 파트 타입

| `type`        | Input Type         | 인코딩                                                                                       |
| ------------- | ------------------ | ----------------------------------------------------------------------------------------- |
| `text`        | Text               | `text`의 일반 문자열                                                                            |
| `image_url`   | Image              | `image_url.url`을 `data:` URI로(PNG, JPG, WebP, GIF, BMP, TIFF, AVIF, HEIC)                 |
| `input_audio` | Audio              | `input_audio.data`(base64) + `input_audio.format`(`wav`, `mp3`)                           |
| `file`        | Document / Archive | `file.file_data`를 `data:` URI로 + `file.filename`(PDF, DOCX, XLSX, PPTX, TXT, CSV, …, ZIP) |
| `video_url`   | Video              | `video_url.url`을 `data:` URI로(MP4) — Starfort 확장 기능                                       |

Document와 Archive는 모두 `type: "file"`을 사용합니다. Starfort는 `type` 필드가 아니라 파일의 **실제 MIME / 매직 바이트 타입**으로 올바른 Input Type에 라우팅합니다. `data:` URI 페이로드는 **표준** base64(`+`, `/`, `=`)로 인코딩하세요 — URL-safe base64(`-`, `_`)는 지원되지 않습니다.

## 규칙

* 파트는 **Guardian에서 해당 Input Type이 활성화된 경우에만** 검사됩니다. 그렇지 않으면 Guardian의 미지원 파일 처리 방식(아래)에 따라 요청이 거부되거나 해당 파트가 검사에서 제외됩니다.
* 응답에서 각 파트는 `text` / `image` / `audio` / `video` / `document` / `archive` 중 하나의 `type`을 가진 자체 `input_results[]` 항목으로 보고되며, 파일 파트는 `identifier`(파일 이름)를 포함합니다.

## 미지원 파일

**파일** 파트의 카테고리나 확장자가 Guardian에서 활성화되지 않은 경우, Guardian의 **Unsupported File Handling** 설정이 동작을 결정합니다. v1.4부터 이 설정의 적용 지점은 **Guardian 단일**입니다 — 게이트웨이가 미지원 파일을 스스로 판정·드롭하지 않고 설정을 Guardian에 전달하며, Guardian이 **최상위 파일과 아카이브(ZIP) 내부 멤버에 동일하게** 적용합니다.

* **BLOCK(기본값)** — 미지원 파일이 하나라도 있으면 **요청 전체**가 거부됩니다. 지원되는 파트(텍스트, 허용된 파일)도 검사되지 않습니다. 분석할 수 없는 콘텐츠를 무검사로 통과시키지 않는 fail-closed 동작입니다.
* **PASS** — 미지원 파일 파트만 **검사에서 제외되며**, 나머지 요청은 정상적으로 검사됩니다. 아카이브 내부도 같은 규칙입니다 — 미지원 멤버만 건너뛰고 나머지 멤버는 검사되므로, 확장자 없는 부속 파일이 섞인 정상 아카이브가 통째로 거부되지 않습니다.

<Note>
  **검사에서 제외된 파일의 원본은 외부로 전달되지 않습니다.** Guardian이 내용을 확인하지 못한 입력은 [처리본](/ko/v1.4/api/response-format)(`processed_content`)을 만들 수 없어 `null`로 반환되며, 처리본이 없는 입력은 egress 대상이 아닙니다.
</Note>

<Note>
  **위장된 파일은 항상 차단됩니다.** PASS 설정에서도, 확장자는 허용되지만 실제 콘텐츠(매직 바이트)가 선언된 타입과 일치하지 않는 파일은 차단됩니다 — 검사는 파일 이름이 아니라 실제 콘텐츠를 기준으로 합니다.
</Note>

버킷에 저장된 파일 자체를 비식별화해 **마스킹된 파일로 저장**해야 한다면(예: `.docx`를 마스킹된 `.docx`로 재구성), [S3 연계 비식별화 배치](/ko/v1.4/api/batch/overview)를 사용하세요.

<Note>
  [Guardian을 등록](/ko/v1.4/admin/register-guardian)할 때 전송하려는 Input Type을 활성화하세요. 기본 `VLM-OCR` 프리셋은 텍스트와 더불어 다양한 이미지, 문서, 아카이브 형식을 지원합니다.
</Note>