---
title: "로컬 파일 인식"
slug: "ai-application-service-clovaspeech-longsentence-local"
updated: 2026-07-23T09:04:22Z
published: 2026-07-23T09:04:22Z
canonical: "api.ncloud-docs.com/ai-application-service-clovaspeech-longsentence-local"
---

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

# 로컬 파일 인식

Classic/VPC 환경에서 이용 가능합니다.

로컬에 저장되어 있는 오디오/비디오 파일을 인식하고 텍스트로 변환합니다.

## 요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

| 메서드 | URI |
| --- | --- |
| POST | /recognizer/upload |

### 요청 헤더

CLOVA Speech API에서 공통으로 사용하는 헤더에 대한 정보는 [CLOVA Speech 요청 헤더](/docs/ai-application-service-clovaspeech#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오.

### 요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `media` | File | Required | 로컬 오디오/비디오 파일 - 지원 파일 형식 - 오디오: `MP3`, `AAC`, `AC3`, `OGG`, `FLAC`, `WAV`, `M4A` - 비디오: `AVI`, `MP4`, `MOV`, `WMV`, `FLV`, `MKV` |
| `params` | Object | Required | 파라미터 세부 정보 |
| `params.language` | String | Required | 텍스트 인식 언어 - `ko-KR` (기본값) \| `en-US` \| `enko` \| `ja` \| `zh-cn` \| `zh-tw` - `ko-kR`: 한국어 - `en-US`: 영어 - `enko`: 한/영 동시 인식 - `ja`: 일본어 - `zh-cn`: 중국어(간체) - `zh-tw`: 중국어(번체) |
| `params.completion` | String | Optional | 인식 요청 후 응답 방식 - `sync` \| `async` (기본값) - `sync`(동기): 결과를 JSON 형식으로 반환 - `async`(비동기): Callback URL 또는 `resultToObs` (ObjectStorage) 형식으로 반환 |
| `params.callback` | String | Conditional | Callback URL - `completion`이 `async`일 때 `callback` 또는 `resultToObs` 중 하나 필수 입력 |
| `params.wordAlignment` | Boolean | Optional | 인식 결과의 음성과 텍스트 정렬 출력 여부 - `true` (기본값) \| `false` - `true`: 출력 - `false`: 미출력 |
| `params.fullText` | Boolean | Optional | 전체 인식 결과 텍스트 출력 여부 - `true` (기본값) \| `false` - `true`: 출력 - `false`: 미출력 |
| `params.resultToObs` | Boolean | Conditional | Object Storage 내 결과 저장 여부 - `completion`이 `async`일 때만 동작 - `true` \| `false` (기본값) - `true`: 결과 저장 - `false`: 결과 미저장 |
| `params.noiseFiltering` | Boolean | Optional | 노이즈 필터링 여부 - `true` (기본값) \| `false` - `true`: 필터링 동작 - `false`: 필터링 미동작 |
| `params.boostings` | Array | Optional | 키워드 부스팅 세부 정보: [boostings](/docs/ai-application-service-clovaspeech-longsentence-local#boostings1) - 음성 인식률을 높일 키워드 목록 - `useDomainBoostings`와 동시 사용 불가 - 최대 1,000개까지 입력 가능 - 한글, 영어만 지원 - 영어: 기본적으로 소문자 변환, 대문자 키워드 부스팅 요청 시 대문자로 치환 - 1음절의 단어는 오인식의 위험이 있어 부스팅 미지원 - <예시> `네`, `응`, `no` - 띄어쓰기 여부와 관계 없이 부스팅 처리 - <예시> "클로바스피치"와 "클로바 스피치" 중 한 개의 키워드만 부스팅 요청 - 키워드 길이의 제약은 없으나, 부스팅할 대상이 여러 단어들이 조합된 구문일 경우 해당 구문이 아니면 부스팅의 영향을 받기 어려움 - <예시> "클로바 스피치"라고 키워드를 부스팅하는 경우, "클로바 스피치"가 포함된 모든 문장은 부스팅의 영향을 받음 - <예시> "클로바 스피치의 미디어 음성인식 기술" 이라는 조합된 긴 길이의 키워드를 부스팅하는 경우, "클로바 스피치"만 들어간 문장은 부스팅의 영향을 받기 어려움 |
| `params.useDomainBoostings` | Boolean | Optional | 도메인 부스팅 사용 여부 - `true` \| `false`(기본값) - `true`: 부스팅 사용 - `false`: 부스팅 미사용 - `boostings`와 동시 사용 불가 |
| `params.forbiddens` | String | Optional | 민감 키워드 - 음성 인식률을 낮출 키워드 목록(인식 결과에 표시하고 싶지 않은 경우) - 키워드 개수 및 길이 제한 없음 - 띄어쓰기, 영문 대소문자 모두 완전 일치 필요 |
| `params.diarization` | Object | Optional | 화자 인식 세부 정보 |
| `params.diarization.enable` | Boolean | Optional | 화자 인식 여부 - `true` (기본값) \| `false` - `true`: 화자 인식 - `false`: 화자 미인식 |
| `sed` | Object | Optional | 이벤트 탐지 결과 세부 정보 |
| `sed.enable` | Boolean | Optional | 이벤트 탐지 여부 - `true` \| `false` (기본값) - `true`: 이벤트 탐지 - `false`: 이벤트 미탐지 |
| `format` | String | Optional | 응답 결과 반환 형식 - `JSON` (기본값) \| `SRT` \| `SMI` |

#### boostings

`boostings`에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `words` | String | Optional | 키워드 부스팅할 단어 목록 |
| `weight` | String | Optional | 키워드 부스팅 가중치 |

참고

`completion`(요청 후 응답 방식)을 `async`로 요청 시, 입력한 Callback URL 주소 유무 또는 resultToObs(ObjectStorage) 여부에 따라 인식 결과를 다음과 같이 반환합니다.

| Callback URL | resultToObs(ObjectStorage) | 결과 |
| --- | --- | --- |
| URL 주소 있음 | True | Callback URL과 Object Storage 모두 결과 반환 |
| URL 주소 있음 | False | Callback URL에만 결과 반환 |
| URL 주소 없음 | True | Object Storage에만 결과 반환 |
| URL 주소 없음 | False | 오류 반환 |

### 요청 예시

요청 예시는 다음과 같습니다.

```
curl --location --request POST 'https://clovaspeech-gw.ncloud.com/external/v1/8881/5f7e1b4c866f1c605946c9236f9***********/recognizer/upload' \
--header 'Content-Type: multipart/form-data' \
--header 'X-CLOVASPEECH-API-KEY: {앱 등록 시 발급받은 Secret Key}' \
--form 'media=@"{media}"' \
--form 'params="{\"language\":\"ko-KR\",\"completion\":\"sync\", \"callback\":\"\", \"fullText\":true,\"\"}"' \
--form 'type="application/json"'
```

## 응답

응답 형식을 설명합니다.

### 응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `result` | String | - | 응답 코드 |
| `message` | String | - | 응답 메시지 |
| `token` | String | - | 결과 토큰 |
| `version` | String | - | 엔진 버전 |
| `params` | Object | - | 파라미터 세부 정보 |
| `params.service` | String | - | 서비스 코드 |
| `params.domain` | String | - | 도메인 유형 - 엔진 호출 시 사용 - `general` |
| `params.lang` | String | - | 인식 언어 - `ko` \| `en` \| `enko` \| `ja` \| `zh-cn` \| `zh-tw` - `ko`: 한국어 - `en`: 영어 - `enko`: 한/영 동시 번역 - `ja`: 일본어 - `zh-cn`: 중국어(간체) - `zh-tw`: 중국어(번체) |
| `params.completion` | String | - | 인식 요청 후 응답 방식 - `sync`(동기): 결과를 JSON 형식으로 반환 - `async`(비동기): Callback URL 또는 `resultToObs` (ObjectStorage) 형식으로 반환 |
| `params.callback` | String | - | Callback URL |
| `params.diarization` | Object | - | 화자 인식(분리) 세부 정보 |
| `params.diarization.enable` | Boolean | - | 화자 인식(분리) 여부 - `true` \| `false` - `true`: 화자 인식 - `false`: 화자 미인식 |
| `params.diarization.speakerCountMin` | Integer | - | 최소 화자 수 |
| `params.diarization.speakerCountMax` | Integer | - | 최대 화자 수 |
| `params.sed` | Object | - | 이벤트 탐지 결과 |
| `params.sed.enable` | Boolean | - | 이벤트 탐지 여부 - `true` \| `false` (기본값) - `true`: 이벤트 탐지 - `false`: 이벤트 미탐지 |
| `params.boostings` | Array | - | 키워드 부스팅 세부 정보: [boostings](/docs/ai-application-service-clovaspeech-longsentence-local#boostings2) - 자세한 내용은 [요청 바디](/docs/ai-application-service-clovaspeech-longsentence-local#%EC%9A%94%EC%B2%AD%EB%B0%94%EB%94%94)의 `boostings` 참조 |
| `params.forbiddens` | String | - | 민감 키워드 - 자세한 내용은 [요청 바디](/docs/ai-application-service-clovaspeech-longsentence-local#%EC%9A%94%EC%B2%AD%EB%B0%94%EB%94%94)의 `forbiddens` 참조 |
| `params.wordAlignment` | Boolean | - | 인식 결과의 음성과 텍스트 정렬 출력 여부 - `true` (기본값) \| `false` - `true`: 출력 - `false`: 미출력 |
| `params.fullText` | Boolean | - | 전체 인식 결과 텍스트 출력 여부 - `true` (기본값) \| `false` - `true`: 출력 - `false`: 미출력 |
| `params.noiseFiltering` | Boolean | - | 노이즈 필터링 여부 - `true` (기본값) \| `false` - `true`: 필터링 동작 - `false`: 필터링 미동작 |
| `params.resultToObs` | Boolean | - | Object Storage 내 결과 저장 여부 - `completion`이 `async`일 때만 동작 - `true` \| `false` (기본값) - `true`: 결과 저장 - `false`: 결과 미저장 |
| `params.priority` | Integer | - | 우선 순위 - 0~4 - 낮을수록 우선순위가 높음 |
| `params.userdata` | Object | - | 사용자 데이터 세부 정보 |
| `params.userdata._ncp_DomainCode` | String | - | 도메인 코드 - `long-speech` \| `short-speech` - `long-speech`: 장문 인식 - `short-speech`: 단문 인식 |
| `params.userdata._ncp_DomainId` | Integer | - | 도메인 아이디 |
| `params.userdata._ncp_TaskId` | Integer | - | 태스크 아이디 - 구체적인 인식 태스크 추적 시 사용 |
| `params.userdata._ncp_TraceId` | String | - | 트레이스 아이디 - 로그 추적 시 사용 |
| `progress` | Integer | - | 인식 진행률 |
| `keywords` | Object | - | 키워드 부스팅된 단어 목록 |
| `segments` | Array | - | segments 세부 정보: [segments](/docs/ai-application-service-clovaspeech-longsentence-local#segments) |
| `text` | String | - | 전체 텍스트 |
| `confidence` | Double | - | 전체 정확도 |
| `speakers` | Array | - | 전체 화자 세부 정보: [speakers](/docs/ai-application-service-clovaspeech-longsentence-local#speakers) |
| `events` | Array | - | 이벤트 세부 정보: [events](/docs/ai-application-service-clovaspeech-longsentence-local#events) |
| `eventTypes` | Array | - | 인식된 모든 이벤트 세부 정보: [eventTypes](/docs/ai-application-service-clovaspeech-longsentence-local#eventTypes) |

#### boostings

`boostings`에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `words` | String | - | 키워드 부스팅 단어 목록 |
| `weight` | String | - | 키워드 부스팅 가중치 |

#### segments

`#segments`에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `start` | Long | - | 분석 시작 시각(ms) |
| `end` | Long | - | 분석 종료 시각(ms) |
| `text` | String | - | 분석 텍스트 |
| `confidence` | Double | - | 분석 정확도 - 0.0~1.0 |
| `diarization` | Object | - | 인식된 화자 세부 정보 |
| `diarization.label` | String | - | 인식된 화자의 번호 |
| `speaker` | Object | - | 변경된 화자 세부 정보 |
| `speaker.label` | String | - | 변경된 화자의 번호 |
| `speaker.name` | String | - | 변경된 화자의 이름 |
| `speaker.edited` | Boolean | - | 화자 변경 여부 - `true` \| `false` (기본값) - `true`: 화자 변경 - `false`: 화자 동일 |
| `words` | Array<Long, Long, String> | - | 인식된 단어 목록 |
| `words.[0]` | Long | - | 세그먼트 시작 시각(ms) |
| `words.[1]` | Long | - | 세그먼트 종료 시각(ms) |
| `words.[2]` | String | - | 세그먼트 텍스트 |
| `textEdited` | String | - | 수정 내용 |

#### speakers

`speakers`에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `label` | String | - | 전체 화자 번호 |
| `name` | String | - | 전체 화자의 이름 |
| `edited` | Boolean | - | 화자 변경 여부 - `true` \| `false` (기본값) - `true`: 화자 변경 - `false`: 화자 동일 |

#### events

`events`에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `type` | String | - | 이벤트 타입 |
| `label` | String | - | 이벤트 이름 |
| `labelEdited` | String | - | 이벤트 변경 이름 |
| `start` | Long | - | 이벤트 시작 시각 |
| `end` | Long | - | 이벤트 종료 시각 |

#### eventTypes

`eventTypes`에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `label` | String | - | 인식된 이벤트 |

### 응답 상태 코드

CLOVA Speech API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [CLOVA Speech 응답 상태 코드](/docs/ai-application-service-clovaspeech#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C)를 참조해 주십시오.

### 응답 예시

응답 예시는 다음과 같습니다.

#### `async`로 요청하여 json으로 반환

`async`로 요청하여 json 형식으로 반환하는 응답 예시는 다음과 같습니다.

```
{
    "token": "*****f6a1015466bae2c926177f26310",
    "result": "SUCCEEDED",
    "message": "Succeeded"
}
```

#### `sync`로 요청하여 json으로 반환

`sync`로 요청하여 json 형식으로 반환하는 응답 예시는 다음과 같습니다.

```
{
    "result": "COMPLETED",
    "message": "Succeeded",
    "token": "*****166039e486abbb90e4a84c3b3a5",
    "version": "ncp_v2_v2.3.0-aa6cd8d-20231205_231211-3cf30bfc_v0.0.0_",
    "params": {
        "service": "ncp",
        "domain": "general",
        "lang": "enko",
        "completion": "sync",
        "callback": "",
        "diarization": {
            "enable": true,
            "speakerCountMin": -1,
            "speakerCountMax": -1
        },
        "sed": {
            "enable": true
        },
        "boostings": [
            {
                "words": "안녕하세요, 테스트"
                "weight": 1
            }
        ],
        "forbiddens": "",
        "wordAlignment": true,
        "fullText": true,
        "noiseFiltering": true,
        "resultToObs": false,
        "priority": 0,
        "userdata": {
            "_ncp_DomainCode": "NEST",
            "_ncp_DomainId": 1,
            "_ncp_TaskId": **442,
            "_ncp_TraceId": "*****ce98ec342d8a8c8fe9191cec343",
            "id": 1
        }
    },
    "progress": 100,
    "keywords": {},
    "segments": [
        {
            "start": 5870,
            "end": 8160,
            "text": "서울 수영장입니다.",
            "confidence": 0.9626975,
            "diarization": {
                "label": "2"
            },
            "speaker": {
                "label": "2",
                "name": "B",
                "edited": false
            },
            "words": [
                [
                    5871,
                    6730,
                    "서울"
                ],
                [
                    6860,
                    7530,
                    "수영장입니다."
                ]
            ],
            "textEdited": "서울 수영장입니다."
        },
        {
            "start": 8160,
            "end": 12950,
            "text": "입장료가 얼마예요? 5천 원이에요. 감사합니다.",
            "confidence": 0.8835926,
            "diarization": {
                "label": "1"
            },
            "speaker": {
                "label": "1",
                "name": "A",
                "edited": false
            },
            "words": [
                [
                    8161,
                    9220,
                    "입장료가"
                ],
                [
                    9390,
                    10020,
                    "얼마예요?"
                ],
                [
                    10410,
                    10640,
                    "5천"
                ],
                [
                    10710,
                    11140,
                    "원이에요."
                ],
                [
                    11910,
                    12500,
                    "감사합니다."
                ]
            ],
            "textEdited": "입장료가 얼마예요? 5천 원이에요. 감사합니다."
        }
    ],
    "text": "서울 수영장입니다. 입장료가 얼마예요? 5천 원이에요. 감사합니다.",
    "confidence": 0.9071357,
    "speakers": [
        {
            "label": "1",
            "name": "A",
            "edited": false
        },
        {
            "label": "2",
            "name": "B",
            "edited": false
        }
    ],
    "events": [
        {
            "type": "music",
            "label": "music",
            "labelEdited": "music",
            "start": 1400,
            "end": 5000
        }
    ],
    "eventTypes": [
        "music"
    ]
}
```

#### `sync`로 요청하여 srt로 반환

`sync`로 요청하여 srt 형식으로 반환하는 응답 예시는 다음과 같습니다.

```
1
00:00:00,000 --> 00:00:01,425
A: 저 얼마 전에

2
00:00:02,533 --> 00:00:11,550
A: 옥수수를 먹었거든요. 정말 달고 맛있던데요 그런데 나는 그게 동네 이름인 줄 알았어.

3
00:00:11,550 --> 00:00:19,025
A: 초사이어있을 때 그 초자에다가 달다는 당이었어 몰랐어요. 몰랐어. 나는 초당이 초당두부 이런 건 줄 알았어.

4
00:00:19,025 --> 00:00:26,317
C: 사카린 생각했죠. 조금. 작가님 초당으로 드셨는데.

5
00:00:26,317 --> 00:00:28,240
A: 옥수수에요?

6
00:00:28,240 --> 00:00:35,318
B: 아니 지금 두부 단 맛나는 두부가 어디 있어. 지금 이 도는 이해를 못 해. 상도면 초당 지역 아니야?

7
00:00:35,318 --> 00:00:42,800
A: 아니. 초당 옥수수는 슈퍼 스위트란 뜻이었어. 초 달다고 아무도 이해 못했어요. 지금.
```

#### `sync`로 요청하여 smi로 반환

`sync`로 요청하여 smi 형식으로 반환하는 응답 예시는 다음과 같습니다.

```
<SAMI>
<Body>
  <SYNC Start=0>
    <P>A: 저 얼마 전에
  <SYNC Start=2533>
    <P>A: 옥수수를 먹었거든요. 정말 달고 맛있던데요 그런데 나는 그게 동네 이름인 줄 알았어.
  <SYNC Start=11550>
    <P>A: 초사이어있을 때 그 초자에다가 달다는 당이었어 몰랐어요. 몰랐어. 나는 초당이 초당두부 이런 건 줄 알았어.
  <SYNC Start=19025>
    <P>C: 사카린 생각했죠. 조금. 작가님 초당으로 드셨는데.
  <SYNC Start=26317>
    <P>A: 옥수수에요?
  <SYNC Start=28240>
    <P>B: 아니 지금 두부 단 맛나는 두부가 어디 있어. 지금 이 도는 이해를 못 해. 상도면 초당 지역 아니야?
  <SYNC Start=35318>
    <P>A: 아니. 초당 옥수수는 슈퍼 스위트란 뜻이었어. 초 달다고 아무도 이해 못했어요. 지금.
</Body>
</SAMI>
```