--- title: "텍스트 및 이미지" slug: "clovastudio-chatcompletionsv3" updated: 2026-10-22T10:46:35Z published: 2026-10-22T10:46:35Z canonical: "api-gov.ncloud-docs.com/clovastudio-chatcompletionsv3" --- > ## Documentation Index > Fetch the complete documentation index at: https://api-gov.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # 텍스트 및 이미지 Classic/VPC 환경에서 이용 가능합니다. 이미지를 해석하고 이해할 수 있는 HCX-005 비전 모델과 경량화된 HCX-DASH-002 모델을 이용할 수 있는 v3 Chat Completions에 대해 설명합니다. ## 요청 요청 형식을 설명합니다. 요청 형식은 다음과 같습니다. | 메서드 | URI | | --- | --- | | POST | - /v3/chat-completions/{modelName} - 모델을 사용하여 문장 생성 - /v3/tasks/{taskId}/chat-completions - 튜닝 학습한 작업을 사용하여 문장 생성 - 이미지 입력, 추론, Function calling, Structured Outputs 미지원 | #### 요청 헤더 CLOVA Studio API에서 공통으로 사용하는 헤더에 대한 정보는 [CLOVA Studio 요청 헤더](/docs/clovastudio-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오. ### 요청 경로 파라미터 요청 경로 파라미터에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `modelName` | Enum | Required | 모델 이름 - <예시> `HCX-005` | | `taskId` | String | Conditional | 학습 아이디 - 튜닝 학습한 작업을 사용하여 문장 생성을 하려는 경우 - [학습 생성](/docs/clovastudio-posttask) 참조 | 참고 - HCX-005와 HCX-DASH-002는 Chat Completions v3 API에서만 사용할 수 있습니다. - 이미지 입력은 HyperCLOVA X 비전 모델인 HCX-005에서만 사용할 수 있으며, 튜닝 학습은 지원하지 않습니다. ### 요청 바디 요청 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `messages` | Array | Required | 대화 메시지: [messages](/docs/clovastudio-chatcompletionsv3#messages) | | `topP` | Double | Optional | 생성 토큰 후보군을 누적 확률을 기반으로 샘플링 - 0.00 ＜ `topP` ≤ 1.00 (기본값: 0.80) | | `topK` | Integer | Optional | 생성 토큰 후보군에서 확률이 높은 K개를 후보로 지정하여 샘플링 - 0 ≤ `topK` ≤ 128 (기본값: 0) | | `maxTokens` | Integer | Optional | 최대 생성 토큰 수 - 1 ≤ `maxTokens` ≤ 모델 최대값 - `maxCompletionTokens`와 동시에 사용 불가 | | `maxCompletionTokens` | Integer | Optional | 최대 생성 토큰 수 (추론 모델) - 1 ≤ `maxCompletionTokens` ≤ 모델 최대값 - `maxTokens`와 동시에 사용 불가 | | `temperature` | Double | Optional | 생성 토큰에 대한 다양성 정도(설정값이 높을수록 다양한 문장 생성) - 0.00 ≤ `temperature` ≤ 1.00 (기본값: 0.50) | | `repetitionPenalty` | Double | Optional | 같은 토큰을 생성하는 것에 대한 패널티 정도(설정값이 높을수록 같은 결괏값을 반복 생성할 확률 감소) - 0.0 ＜ `repetitionPenalty` ≤ 2.0 (기본값: 1.1) | | `stop` | Array | Optional | 토큰 생성 중단 문자 - [](기본값) - 추론 시 사용 불가 | | `seed` | Integer | Optional | 모델 반복 실행 시 결괏값의 일관성 수준 조정 - 0: 일관성 수준 랜덤 적용 (기본값) - 1 ≤ `seed` ≤ 4294967295: 일관되게 생성하고자 하는 결괏값의 `seed` 값 또는 사용자가 지정하고자 하는 `seed` 값 | | `includeAiFilters` | Boolean | Optional | AI 필터(생성된 결괏값에 대해 욕설, 비하/차별/혐오, 성희롱/음란 등 카테고리별로 해당하는 정도) 결과 표시 여부 - `true` \| `false` (기본값) - `true`: 표시 - `false`: 표시 안 함 | #### `messages` `messages`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `role` | Enum | Required | 대화 메시지 역할 - `system` \| `user` \| `assistant` - `system`: 역할을 규정하는 지시문 - `user`: 사용자의 발화 또는 질문 - `assistant`: 사용자의 발화 또는 질문에 대한 답변 | | `content` | String \| Array | Required | 대화 메시지 내용 - 텍스트 입력(String) - 텍스트, 이미지 URL로 구성하여 입력(Array): [content](/docs/clovastudio-chatcompletionsv3#content) | #### `content` `content`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `type` | Enum | Required | 대화 메시지 내용의 형식 - `text` \| `image_url` - `text` : 텍스트 - `image_url` : 이미지 URL | | `text` | String | Conditional | 대화 메시지 내용 - 텍스트 입력 | | `imageUrl` | Object | Conditional | 이미지 목록 - `type`이 `image_url`인 경우, `imageUrl`과 `dataUri` 중 필수 입력 - 턴당 이미지 1개 포함 가능 - 최적의 결과를 위해 `text`와 함께 요청 권장 | | `imageUrl.url` | String | Conditional | 파일 확장자를 포함한 단일 이미지의 공개 URL - 이미지 지원 사양 - 형식: BMP, PNG, JPG, JPEG, WEBP - 크기: 0Byte 초과 20MB 이하 - 비율: 가로, 세로가 1:5 또는 5:1 이하 - 길이: 가로, 세로 중 긴 쪽은 2240px이하. 짧은 쪽은 4px 이상 | | `dataUri` | Object | Conditional | 이미지 목록 - `type`이 `image_url`인 경우, `imageUrl`과 `dataUri` 중 필수 입력 - 턴당 이미지 1개 포함 가능 - 최적의 결과를 위해 `text`와 함께 요청 권장 | | `dataUri.data` | String | Conditional | Base64로 인코딩된 이미지 문자열 - 이미지 지원 사양 - 형식: BMP, PNG, JPG, JPEG, WEBP - 크기: 0Byte 초과 20MB 이하 - 비율: 가로, 세로가 1:5 또는 5:1 이하 - 길이: 가로, 세로 중 긴 쪽은 2240px이하. 짧은 쪽은 4px 이상 | 참고 일부 필드 입력 시 다음 내용을 확인해 주십시오. - `role`: `system`인 [대화 메시지](/docs/clovastudio-chatcompletionsv3#messages)는 요청당 1개만 포함할 수 있습니다. - HCX-005 - 입력 토큰과 출력 토큰의 합은 128000 토큰을 초과할 수 없습니다. - 입력 토큰은 최대 128000 토큰까지 가능합니다. - 모델에 요청할 출력 토큰(maxTokens)은 최대 4096 토큰까지 가능합니다. - `messages`: 턴 당 이미지는 1개 포함 가능하고, 요청당 이미지는 최대 5개 포함할 수 있습니다. - 전체 Request Body 크기는 50MB 이하여야 합니다. 따라서 여러 개의 이미지를 요청에 포함하는 경우 base64 형식보다 image URL 사용을 권장합니다. - HCX-DASH-002 - 입력 토큰과 출력 토큰의 합은 32000 토큰을 초과할 수 없습니다. - 입력 토큰은 최대 32000 토큰까지 가능합니다. - 모델에 요청할 출력 토큰(maxTokens)은 최대 4096 토큰까지 가능합니다. ### 요청 예시 요청 예시는 다음과 같습니다. ``` 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": [] }' ``` ## 응답 응답 형식을 설명합니다. ### 응답 헤더 응답 헤더에 대한 설명은 다음과 같습니다. | 헤더 | 필수 여부 | 설명 | | --- | --- | --- | | `Content-Type` | - | 응답 데이터의 형식 - `application/json` | ### 응답 바디 응답 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `status` | Object | - | [응답 상태](/docs/clovastudio-overview#%EC%9D%91%EB%8B%B5) 참조 | | `result` | Object | - | 응답 결과 | | `result.created` | Integer | - | 응답 날짜 - Unix timestamp miliseconds 형식 | | `result.usage` | Object | - | 토큰 사용량 | | `result.usage.completionTokens` | Integer | - | 생성 토큰 수 | | `result.usage.promptTokens` | Integer | - | 입력(프롬프트) 토큰 수 | | `result.usage.totalTokens` | Integer | - | 전체 토큰 수 - 생성 토큰 수+입력 토큰 수 | | `result.message` | Object | - | 대화 메시지 | | `result.message.role` | Enum | - | 대화 메시지 역할 - `system` \| `user` \| `assistant` - `system`: 역할을 규정하는 지시문 - `user`: 사용자의 발화 또는 질문 - `assistant`: 모델의 답변 | | `result.message.content` | String | - | 대화 메시지 내용 | | `result.finishReason` | String | - | 토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달) - `length` \| `stop` \| `tool_calls` - `length`: 길이 제한 - `stop`: 답변 생성 중 `stop`에 지정한 문자 출현 - `tool_calls`: 모델이 정상적으로 도구 호출 완료 | | `result.seed` | Integer | - | 입력 seed 값(0 입력 또는 미입력 시 랜덤 값 반환) | | `result.aiFilter` | Array | - | AI 필터 결과: [aiFilter](/docs/clovastudio-chatcompletionsv3#aiFilter) | #### `aiFilter` `aiFilter`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `groupName` | String | - | AI 필터 카테고리 - `curse` \| `unsafeContents` - `curse`: 비하, 차별, 혐오 및 욕설 - `unsafeContents`: 성희롱, 음란 | | `name` | String | - | AI 필터 세부 카테고리 - `discrimination` \| `insult` \| `sexualHarassment` - `discrimination`: 비하, 차별, 혐오 - `insult`: 욕설 - `sexualHarassment`: 성희롱, 음란 | | `score` | String | - | AI 필터 점수 - `-1` \| `0` \| `1` \| `2` - `-1`: AI 필터 오류 발생 - `0`: 대화 메시지에 민감/위험 표현 포함 가능성 높음 - `1`: 대화 메시지에 민감/위험 표현 포함 가능성 있음 - `2`: 대화 메시지에 민감/위험 표현 포함 가능성 낮음 | | `result` | String | - | AI 필터 정상 작동 여부 - `OK` \| `ERROR` - `OK`: 정상 작동 - `ERROR`: 오류 발생 | 참고 AI Filter는 최대 500자까지 분석할 수 있습니다. 단, 분석 대상 텍스트에 비정상적인 형식, 이모티콘, 특수 문자 등이 많은 경우, 정상적으로 분석되지 않을 수 있습니다. ### 응답 예시 응답 예시는 다음과 같습니다. #### 성공 호출이 성공한 경우의 응답 예시는 다음과 같습니다. ``` { "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" } ] } } ``` #### 실패 호출이 실패한 경우의 응답 예시는 다음과 같습니다. - [클라이언트 공통 오류 문제(4xx)](/docs/clovastudio-troubleshoot-c4xx) - [서버 공통 오류 문제(5xx)](/docs/clovastudio-troubleshoot-c5xx) ## 응답 스트림 생성되는 토큰을 하나씩 출력하도록 토큰 스트리밍을 사용할 수 있습니다. 토큰 스트리밍 형식을 설명합니다. ### 응답 헤더 응답 헤더에 대한 설명은 다음과 같습니다. | 헤더 | 필수 여부 | 설명 | | --- | --- | --- | | `Accept` | - | 응답 데이터의 형식 - `text/event-stream` | ### 응답 바디 응답 바디에 대한 설명은 다음과 같습니다. #### StreamingChatCompletionsTokenEvent `StreamingChatCompletionsTokenEvent`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `created` | Integer | - | 응답 시간 타임스탬프 | | `usage` | Object | - | 토큰 사용량 | | `usage.promptTokens` | Integer | - | 입력(프롬프트) 토큰 수 | | `usage.completionTokens` | Integer | - | 생성 토큰 수 | | `message` | Object | - | 대화 메시지 | | `message.role` | Enum | - | 대화 메시지 역할 - `user` \| `assistant` - `user`: 사용자의 발화 또는 질문 - `assistant`: 모델의 답변 | | `message.content` | String | - | 대화 메시지 내용 | | `finishReason` | String | - | 토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달) - `length` \| `stop` - `length`: 길이 제한 - `stop`: 답변 생성 중 `stop`에 지정한 문자 출현 | #### StreamingChatCompletionsResultEvent `StreamingChatCompletionsResultEvent`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `created` | Integer | - | 응답 시간 타임스탬프 | | `usage` | Object | - | 토큰 사용량 | | `usage.promptTokens` | Integer | - | 입력(프롬프트) 토큰 수 | | `usage.completionTokens` | Integer | - | 생성 토큰 수 | | `usage.totalTokens` | Integer | - | 전체 토큰 수 - 생성 토큰 수+입력 토큰 수 | | `message` | Object | - | 대화 메시지 | | `message.role` | Enum | - | 대화 메시지 역할 - `user` \| `assistant` - `user`: 사용자의 발화 또는 질문 - `assistant`: 모델의 답변 | | `message.content` | String | - | 대화 메시지 내용 | | `finishReason` | String | - | 토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달) - `length` \| `stop` - `length`: 길이 제한 - `stop`: 답변 생성 중 `stop`에 지정한 문자 출현 | | `aiFilter` | Array | - | AI 필터 결과: [aiFilter](/docs/clovastudio-chatcompletionsv3#aiFilter) | #### ErrorEvent `ErrorEvent`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `status` | Object | - | [응답 상태](/docs/clovastudio-overview#%EC%9D%91%EB%8B%B5) | | `status.code` | Object | - | 응답 상태 코드 - [CLOVA Studio 문제 해결](/docs/clovastudio-troubleshoot) 참조 | | `status.message` | Object | - | 응답 상태 메시지 - [CLOVA Studio 문제 해결](/docs/clovastudio-troubleshoot) 참조 | #### SignalEvent `SignalEvent`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `data` | String | - | 전달할 시그널 데이터 정보 | ### 응답 예시 응답 예시는 다음과 같습니다. #### 성공 호출이 성공한 경우의 응답 예시는 다음과 같습니다. ``` 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}} ``` #### 실패 호출이 실패한 경우의 응답 예시는 다음과 같습니다. - [클라이언트 공통 오류 문제(4xx)](/docs/clovastudio-troubleshoot-c4xx) - [서버 공통 오류 문제(5xx)](/docs/clovastudio-troubleshoot-c5xx)