---
title: "외부 파일 인식"
slug: "ai-application-service-clovaspeech-longsentence-externalurl"
updated: 2026-09-17T09:15:53Z
published: 2026-09-17T09:15:53Z
canonical: "api.ncloud-docs.com/ai-application-service-clovaspeech-longsentence-externalurl"
---

> ## 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.

# 외부 파일 인식

<p class="platform-info type-classic-vpc">Classic/VPC 환경에서 이용 가능합니다.</p>

외부에서 접속 가능한 오디오/비디오 파일의 URL을 호출하여 인식하고 텍스트로 변환합니다.

## 요청 <a name="요청"></a>
요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

| 메서드 | URI |
| :--- | :--- |
| POST | /recognizer/url |


### 요청 헤더 <a name="요청헤더"></a>
CLOVA Speech API에서 공통으로 사용하는 헤더에 대한 정보는 [CLOVA Speech 요청 헤더](/docs/ai-application-service-clovaspeech#요청헤더)를 참조해 주십시오.


### 요청 바디 <a name="요청바디"></a>

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

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


#### `boostings` <a name="boostings1"></a>

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

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

:::(Info) (참고)
`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 | 오류 반환 |
:::

### 요청 예시 <a name="요청예시"></a>
요청 예시는 다음과 같습니다.
```shell
curl --location --request POST 'https://clovaspeech-gw.ncloud.com/external/v1/8881/5f7e1b4c866f1c605946c9236f9aa8************/recognizer/url' \
--header 'Content-Type: application/json' \
--header 'X-CLOVASPEECH-API-KEY: {앱 등록 시 발급받은 Secret Key}' \
--data '{
  "language": "ko-KR",
  "completion":"async",
  "url": "{url}",
  "resultToObs" : true
}'
```


## 응답 <a name="응답"></a>
응답 형식을 설명합니다.


### 응답 바디 <a name="응답바디"></a>
응답 바디에 대한 설명은 다음과 같습니다.

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


#### boostings <a name="boostings2"></a>
`boostings`에 대한 설명은 다음과 같습니다.

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


#### segments <a name="segments"></a>
`segments`에 대한 설명은 다음과 같습니다.

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


#### speakers <a name="speakers"></a>
`speakers`에 대한 설명은 다음과 같습니다.

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


#### events <a name="events"></a>
`events`에 대한 설명은 다음과 같습니다.

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


#### eventTypes <a name="eventTypes"></a>
`eventTypes`에 대한 설명은 다음과 같습니다.

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


### 응답 상태 코드 <a name="응답상태코드"></a>
CLOVA Speech API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [CLOVA Speech 응답 상태 코드](/docs/ai-application-service-clovaspeech#응답상태코드)를 참조해 주십시오.


### 응답 예시 <a name="응답예시"></a>
응답 예시는 다음과 같습니다.

#### `async`로 요청하여 json으로 반환<a name="async로요청하여json으로반환"></a>

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

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

#### `sync`로 요청하여 json으로 반환<a name="sync로요청하여json으로반환"></a>

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

```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로 반환<a name="sync로요청하여srt로반환"></a>

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

```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로 반환<a name="sync로요청하여smi로반환"></a>

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

```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>
```