---
title: "텍스트 및 이미지"
slug: "clovastudio-chatcompletionsv3"
updated: 2026-09-17T09:15:56Z
published: 2026-09-17T09:15:56Z
canonical: "api.ncloud-docs.com/clovastudio-chatcompletionsv3"
---

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

이미지를 해석하고 이해할 수 있는 HCX-005 비전 모델과 경량화된 HCX-DASH-002 모델을 이용할 수 있는 v3 Chat Completions에 대해 설명합니다.

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

| 메서드 | URI |
| --- | --- |
| POST |<ul><li>/v3/chat-completions/{modelName}<ul><li>모델을 사용하여 문장 생성</li></ul></li><li>/v3/tasks/{taskId}/chat-completions<ul><li>튜닝 학습한 작업을 사용하여 문장 생성</li><li>이미지 입력, 추론, Function calling, Structured Outputs 미지원</li></ul></li></ul> |

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

### 요청 경로 파라미터<a name="요청경로파라미터"></a>

요청 경로 파라미터에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `modelName` | Enum | Required | 모델 이름 <ul><li><예시> `HCX-005`</li></ul> |
| `taskId` | String | Conditional | 학습 아이디<ul><li>튜닝 학습한 작업을 사용하여 문장 생성을 하려는 경우</li><li>[학습 생성](/docs/clovastudio-posttask) 참조</li></ul> |

:::(Info) (참고)
* HCX-005와 HCX-DASH-002는 Chat Completions v3 API에서만 사용할 수 있습니다.
* 이미지 입력은 HyperCLOVA X 비전 모델인 HCX-005에서만 사용할 수 있으며, 튜닝 학습은 지원하지 않습니다.
:::

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

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

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `messages` | Array | Required | 대화 메시지: [messages](#messages) |
| `topP` | Double | Optional | 생성 토큰 후보군을 누적 확률을 기반으로 샘플링<ul><li>0.00 ＜ `topP` ≤ 1.00 (기본값: 0.80)</li></ul> |
| `topK` | Integer | Optional | 생성 토큰 후보군에서 확률이 높은 K개를 후보로 지정하여 샘플링<ul><li>0 ≤ `topK` ≤ 128 (기본값: 0)</li></ul> |
| `maxTokens` | Integer | Optional | 최대 생성 토큰 수<ul><li>1 ≤ `maxTokens` ≤ 모델 최대값 </li><li>`maxCompletionTokens`와 동시에 사용 불가</li></ul> |
| `maxCompletionTokens` | Integer | Optional | 최대 생성 토큰 수 (추론 모델)<ul><li>1 ≤ `maxCompletionTokens` ≤ 모델 최대값 </li><li>`maxTokens`와 동시에 사용 불가 </li></ul> |
| `temperature` | Double | Optional | 생성 토큰에 대한 다양성 정도(설정값이 높을수록 다양한 문장 생성) <ul><li>0.00 ≤ `temperature` ≤ 1.00 (기본값: 0.50)</li></ul> |
| `repetitionPenalty` | Double | Optional | 같은 토큰을 생성하는 것에 대한 패널티 정도<ul><li>0.0 ＜ `repetitionPenalty` ≤ 2.0 (기본값: 1.1)</li><li>설정값이 높을수록 같은 결괏값을 반복 생성할 확률 감소</li><li>1.0~1.1에서 0.05 단위로 미세 조정 권장</li></ul>|
| `stop` | Array | Optional | 토큰 생성 중단 문자<ul><li>\[\](기본값)</li><li>추론 시 사용 불가</li></ul> |
| `seed` | Integer | Optional | 모델 반복 실행 시 결괏값의 일관성 수준 조정 <ul><li>0: 일관성 수준 랜덤 적용 (기본값)</li><li>1 ≤ `seed` ≤ 4294967295: 일관되게 생성하고자 하는 결괏값의 `seed` 값 또는 사용자가 지정하고자 하는 `seed` 값</li></ul>  |
| `includeAiFilters` | Boolean  | Optional | AI 필터(생성된 결괏값에 대해 욕설, 비하/차별/혐오, 성희롱/음란 등 카테고리별로 해당하는 정도) 결과 표시 여부<ul><li>`true` \| `false` (기본값)<ul><li>`true`: 표시</li><li>`false`: 표시 안 함</li></ul></li></ul> |

#### `messages`<a name="messages"></a>

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

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `role` | Enum | Required | 대화 메시지 역할<ul><li>`system` \| `user` \| `assistant`<ul><li>`system`: 역할을 규정하는 지시문</li><li>`user`: 사용자의 발화 또는 질문</li><li>`assistant`: 사용자의 발화 또는 질문에 대한 답변</li></ul></li></ul>|
| `content` | String \| Array | Required | 대화 메시지 내용<ul><li>텍스트 입력(String) </li><li>텍스트, 이미지 URL로 구성하여 입력(Array): [content](#content)</li></ul> |

#### `content`<a name="content"></a>

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

| 필드  | 타입    | 필수 여부   | 설명    |
| --- | --- | --- | --- |
| `type` | Enum | Required | 대화 메시지 내용의 형식<ul><li>`text` \| `image_url`<ul><li>`text` : 텍스트</li><li>`image_url` : 이미지 URL</li></ul></li></ul> |
| `text` | String | Conditional | 대화 메시지 내용<ul><li>텍스트 입력</li><ul><li>`type`이 `text`인 경우, 필수 입력</li></ul></ul> |
| `imageUrl` | Object | Conditional | 이미지 목록<ul><li>`type`이 `image_url`인 경우, `imageUrl`과 `dataUri` 중 필수 입력</li><li>턴당 이미지 1개 포함 가능</li><li>최적의 결과를 위해 `text`와 함께 요청 권장</li></ul> |
| `imageUrl.url` | String | Conditional | 파일 확장자를 포함한 단일 이미지의 공개 URL<ul><li>이미지 지원 사양<ul><li>형식: BMP, PNG, JPG, JPEG, WEBP</li><li>크기: 0Byte 초과 20MB 이하</li><li>비율: 가로, 세로가 1:5 또는 5:1 이하</li><li>길이: 가로, 세로 중 긴 쪽은 2240px이하. 짧은 쪽은 4px 이상</li></ul></li></ul></li></ul> |
| `dataUri` | Object | Conditional | 이미지 목록<ul><li>`type`이 `image_url`인 경우, `imageUrl`과 `dataUri` 중 필수 입력</li><li>턴당 이미지 1개 포함 가능</li><li>최적의 결과를 위해 `text`와 함께 요청 권장</li></ul> |
| `dataUri.data` | String | Conditional | Base64로 인코딩된 이미지 문자열<ul><li>이미지 지원 사양<ul><li>형식: BMP, PNG, JPG, JPEG, WEBP</li><li>크기: 0Byte 초과 20MB 이하</li><li>비율: 가로, 세로가 1:5 또는 5:1 이하</li><li>길이: 가로, 세로 중 긴 쪽은 2240px이하. 짧은 쪽은 4px 이상</li></ul></li></ul> |


:::(Info) (참고)
일부 필드 입력 시 다음 내용을 확인해 주십시오.
* `role`: `system`인 [대화 메시지](#messages)는 요청당 1개만 포함할 수 있습니다.
* HCX-005
    * 입력 토큰과 출력 토큰의 합은 128000 토큰을 초과할 수 없습니다.
    * 입력 토큰은 최대 128000 토큰까지 가능합니다.
    * 모델에 요청할 출력 토큰(maxTokens)은 최대 4096 토큰까지 가능합니다.
     * `messages`: 턴 당 이미지는 1개 포함 가능하고, 요청당 이미지는 최대 5개 포함할 수 있습니다.
        * 전체 Request Body 크기는 50MB 이하여야 합니다. 따라서 여러 개의 이미지를 요청에 포함하는 경우 base64 형식보다 image URL 사용을 권장합니다.
* HCX-DASH-002
    * 입력 토큰과 출력 토큰의 합은 32000 토큰을 초과할 수 없습니다.
    * 입력 토큰은 최대 32000 토큰까지 가능합니다.
    * 모델에 요청할 출력 토큰(maxTokens)은 최대 4096 토큰까지 가능합니다.
:::

### 요청 예시<a name="요청예시"></a>

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

```shell
curl --location --request POST 'https://clovastudio.stream.ntruss.com/v3/chat-completions/HCX-005' \
--header 'Authorization: Bearer {CLOVA Studio API Key}' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' \
--header 'Content-Type: application/json' \
--header 'Accept: text/event-stream' \
--data '{
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "- 친절하게 답변하는 AI 어시스턴트입니다."
          }
        ]
      },
      {
        "role": "user",
        "content": [
          {
            "type": "image_url",
            "imageUrl": {
              "url": "https://www.******.com/image_a1b1c1.png"
            }
          },
          {
            "type": "text",
            "text": "이 사진에 대해서 설명해줘"
          }
        ]
      }
    ],
    "topP": 0.8,
    "topK": 0,
    "maxTokens": 100,
    "temperature": 0.5,
    "repetitionPenalty": 1.1,
    "stop": []
  }'
```
    
    
## 응답<a name="응답"></a>

응답 형식을 설명합니다.

### 응답 헤더<a name="응답헤더"></a>

응답 헤더에 대한 설명은 다음과 같습니다.

| 헤더 | 필수 여부 | 설명 |
| --- | --- | --- |
| `Content-Type` | - | 응답 데이터의 형식<ul><li>`application/json`</li></ul> |

### 응답 바디<a name="응답바디"></a>

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

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `status` | Object | -  | [응답 상태](/docs/ai-naver-clovastudio-summary#응답) 참 |
| `result` | Object | - | 응답 결과 |
| `result.created` | Integer | - | 응답 날짜<ul><li>Unix timestamp miliseconds 형식</li></ul> |
| `result.usage` | Object | - | 토큰 사용량 |
| `result.usage.completionTokens` | Integer | - | 생성 토큰 수 |
| `result.usage.promptTokens` | Integer | - | 입력(프롬프트) 토큰 수 |
| `result.usage.totalTokens` | Integer | - | 전체 토큰 수<ul><li>생성 토큰 수+입력 토큰 수</li></ul> |
| `result.message` | Object | - | 대화 메시지 |
| `result.message.role` | Enum | - | 대화 메시지 역할<ul><li>`system` \| `user` \| `assistant`<ul><li>`system`: 역할을 규정하는 지시문</li><li>`user`: 사용자의 발화 또는 질문</li><li>`assistant`: 모델의 답변</li></ul></li></ul> |
| `result.message.content` | String | - | 대화 메시지 내용 |
| `result.finishReason` | String | - | 토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달)<ul><li>`length` \| `stop` \| `tool_calls`<ul><li>`length`: 길이 제한</li><li>`stop`: 답변 생성 중 `stop`에 지정한 문자 출현</li><li>`tool_calls`: 모델이 정상적으로 도구 호출 완료</li></ul></li></ul> |
| `result.seed` | Integer | - | 입력 seed 값(0 입력 또는 미입력 시 랜덤 값 반환) |
| `result.aiFilter`  | Array | - | AI 필터 결과: [aiFilter](#aiFilter) |  


#### `aiFilter`<a name="aiFilter"></a>

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

| 필드  | 타입    | 필수 여부   | 설명    |
| --- | --- | --- | --- |
| `groupName` | String | - | AI 필터 카테고리<ul><li>`curse` \| `unsafeContents`<ul><li>`curse`: 비하, 차별, 혐오 및 욕설</li><li>`unsafeContents`: 성희롱, 음란</li></ul></li></ul> |
| `name` | String | - | AI 필터 세부 카테고리<ul><li>`discrimination` \| `insult` \| `sexualHarassment`<ul><li>`discrimination`: 비하, 차별, 혐오</li><li>`insult`: 욕설</li><li>`sexualHarassment`: 성희롱, 음란</li></ul></li></ul>  |
| `score` | String | - | AI 필터 점수<ul><li>`-1` \| `0` \| `1` \| `2`<ul><li>`-1`: AI 필터 오류 발생</li><li>`0`: 대화 메시지에 민감/위험 표현 포함 가능성 높음</li><li>`1`: 대화 메시지에 민감/위험 표현 포함 가능성 있음</li><li>`2`: 대화 메시지에 민감/위험 표현 포함 가능성 낮음</li></ul></li></ul> | 
| `result` | String  | - | AI 필터 정상 작동 여부<ul><li>`OK` \| `ERROR`<ul><li>`OK`: 정상 작동</li><li>`ERROR`: 오류 발생</li></ul></li></ul> |

:::(Info) (참고)
AI Filter는 최대 500자까지 분석할 수 있습니다. 단, 분석 대상 텍스트에 비정상적인 형식, 이모티콘, 특수 문자 등이 많은 경우, 정상적으로 분석되지 않을 수 있습니다.
:::

### 응답 예시<a name="응답예시1"></a>

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

#### 성공<a name="성공1"></a>

호출이 성공한 경우의 응답 예시는 다음과 같습니다.

```json
{
    "status": {
        "code": "20000",
        "message": "OK"
    },
    "result": {
        "created": 1791043155000,
        "usage": {
            "completionTokens": 80,
            "promptTokens": 843,
            "totalTokens": 923
        },        
        "message": {
            "role": "assistant",
            "content": "사진에는 어린 아이가 양에게 먹이를 주는 모습이 담겨 있습니다. 아이는 파란색 옷을 입고 있으며, 줄문의 모자를 쓰고 있습니다. 아이의 표정은 집중하고 있는 듯 보이며, 양은 아이가 주는 먹이를 먹으려고 머리를 숙이고 있습니다. 배경에는 다른 양들도 보이며, 이 장소가 양 목장임을 짐작할 수 있습니다."
        },
        "seed": 1561390649,
        "aiFilter": [
         {
          "groupName": "curse",
          "name": "insult",
         "score": "1"
         },
         {
          "groupName": "curse",
          "name": "discrimination",
          "score": "0"
         },
         {
          "groupName": "unsafeContents",
          "name": "sexualHarassment",
          "score": "2"
         }
        ]
    }
}
```

#### 실패<a name="실패1"></a>

호출이 실패한 경우의 응답 예시는 다음과 같습니다.
* [클라이언트 공통 오류 문제(4xx)](/docs/clovastudio-troubleshoot-c4xx) 
* [서버 공통 오류 문제(5xx)](/docs/clovastudio-troubleshoot-c5xx) 

## 응답 스트림<a name="응답스트림"></a>

생성되는 토큰을 하나씩 출력하도록 토큰 스트리밍을 사용할 수 있습니다. 토큰 스트리밍 형식을 설명합니다.

### 응답 헤더<a name="응답헤더"></a>

응답 헤더에 대한 설명은 다음과 같습니다.

| 헤더 | 필수 여부 | 설명 |
| --- | --- | --- |
| `Accept` | - | 응답 데이터의 형식<ul><li>`text/event-stream`</li></ul> |

### 응답 바디<a name="응답바디"></a>

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

#### StreamingChatCompletionsTokenEvent<a name="StreamingChatCompletionsTokenEvent"></a>

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

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `created` | Integer | - | 응답 시간 타임스탬프 |
| `usage` | Object | - | 토큰 사용량 |
| `usage.promptTokens` | Integer | - | 입력(프롬프트) 토큰 수 |
| `usage.completionTokens` | Integer | - | 생성 토큰 수 |
| `message` | Object | - | 대화 메시지 |
| `message.role` | Enum | - | 대화 메시지 역할<ul><li>`user` \| `assistant`<ul><li>`user`: 사용자의 발화 또는 질문</li><li>`assistant`: 모델의 답변</li></ul></li></ul> |
| `message.content` | String | - | 대화 메시지 내용 |
| `finishReason` | String | - | 토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달)<ul><li>`length` \| `stop`<ul><li>`length`: 길이 제한</li><li>`stop`: 답변 생성 중 `stop`에 지정한 문자 출현</li></ul></li></ul> |


#### StreamingChatCompletionsResultEvent<a name="StreamingChatCompletionsResultEvent"></a>

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

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `created` | Integer | - | 응답 시간 타임스탬프 |
| `usage` | Object | - | 토큰 사용량 |
| `usage.promptTokens` | Integer | - | 입력(프롬프트) 토큰 수 |
| `usage.completionTokens` | Integer | - | 생성 토큰 수 |
| `usage.totalTokens` | Integer | - | 전체 토큰 수<ul><li>생성 토큰 수+입력 토큰 수</li></ul> |
| `message` | Object | - | 대화 메시지 |
| `message.role` | Enum | - | 대화 메시지 역할<ul><li>`user` \| `assistant`<ul><li>`user`: 사용자의 발화 또는 질문</li><li>`assistant`: 모델의 답변</li></ul></li></ul> |
| `message.content` | String | - | 대화 메시지 내용 |
| `finishReason` | String | - | 토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달)<ul><li>`length` \| `stop`<ul><li>`length`: 길이 제한</li><li>`stop`: 답변 생성 중 `stop`에 지정한 문자 출현</li></ul></li></ul> |
| `aiFilter`  | Array | - | AI 필터 결과: [aiFilter](#aiFilter) |  

#### ErrorEvent <a name="ErrorEvent"></a>

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

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `status` | Object | - | [응답 상태](/docs/ai-naver-clovastudio-summary#응답) |
| `status.code` | Object | - | 응답 상태 코드<ul><li>[CLOVA Studio 문제 해결](/docs/clovastudio-troubleshoot) 참조</li></ul> |
| `status.message` | Object | - | 응답 상태 메시지<ul><li>[CLOVA Studio 문제 해결](/docs/clovastudio-troubleshoot) 참조</li></ul> |


#### SignalEvent <a name="SignalEvent"></a>

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

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `data` | String | - | 전달할 시그널 데이터 정보 |

### 응답 예시<a name="응답예시2"></a>

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

#### 성공<a name="성공2"></a>

호출이 성공한 경우의 응답 예시는 다음과 같습니다.

```python
id: aabdfe-dfgwr-edf-hpqwd-f3asd-g
event: token
data: {"message": {"role": "assistant", "content": “안”},"finishReason": null, "created": 1744710905, "seed": 3284419119, "usage": null} 

id: aabdfe-dfgwr-edf-hpqwd-f2asd-g
event: token
data: {"message": {"role": "assistant", "content": “녕”},"finishReason": null, "created": 1744710905, "seed": 3284419119, "usage": null} 

id: aabdfe-dfgwr-edf-hpqwd-f1asd-g
event: result
data: {"message": {"role": "assistant", "content": “안녕”}, "finishReason": "stop", "created": 1744710905, "seed": 3284419119, "usage": {"promptTokens": 20, "completionTokens": 5, "totalTokens": 25}}
```

#### 실패<a name="실패2"></a>

호출이 실패한 경우의 응답 예시는 다음과 같습니다.
* [클라이언트 공통 오류 문제(4xx)](/docs/clovastudio-troubleshoot-c4xx) 
* [서버 공통 오류 문제(5xx)](/docs/clovastudio-troubleshoot-c5xx)