텍스트 및 이미지

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 미지원

요청 헤더

요청 헤더에 대한 설명은 다음과 같습니다.

헤더	필수 여부	설명
`Authorization`	Required	인증을 위한 API 키 <예시> `Bearer nv-************`
`X-NCP-CLOVASTUDIO-REQUEST-ID`	Optional	요청에 대한 아이디
`Content-Type`	Required	요청 데이터의 형식 `application/json`
`Accept`	Conditional	응답 데이터의 형식 `text/event-stream`

참고

응답 결과는 기본적으로 JSON 형태로 반환되지만, Accept를 text/event-stream으로 지정 시 응답 결과를 스트림 형태로 반환합니다.

요청 경로 파라미터

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

필드	타입	필수 여부	설명
`modelName`	Enum	Required	모델 이름 <예시> `HCX-005`

참고

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

요청 바디

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

필드	타입	필수 여부	설명
`messages`	Array	Required	대화 메시지
`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`

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

필드	타입	필수 여부	설명
`type`	Enum	Required	대화 메시지 내용의 형식 `text` \| `image_url` `text` : 텍스트 `image_url` : 이미지 URL
`text`	String	Conditional	대화 메시지 내용 텍스트 입력 `type`이 `text`인 경우, 필수 입력
`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인 대화 메시지는 요청당 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	-	응답 상태
`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` `length`: 길이 제한 `stop`: 답변 생성 중 `stop`에 지정한 문자 출현 `tool_calls`: 모델이 정상적으로 도구 호출 완료
`result.seed`	Integer	-	입력 seed 값(0 입력 또는 미입력 시 랜덤 값 반환)
`result.aiFilter`	Array	-	AI 필터 결과

`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"
         }
        ]
    }
}

실패

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

응답 스트림

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

응답 헤더

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

헤더	필수 여부	설명
`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 필터 결과

ErrorEvent

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

필드	타입	필수 여부	설명
`status`	Object	-	응답 상태
`status.code`	Object	-	응답 상태 코드 CLOVA Studio 문제 해결 참조
`status.message`	Object	-	응답 상태 메시지 CLOVA Studio 문제 해결 참조

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

실패

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