텍스트 및 이미지

Prev Next

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

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

요청

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

메서드 URI
POST /v3/chat-completions/{modelName}

요청 헤더

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

헤더 필수 여부 설명
Authorization Required 인증을 위한 API 키 <예시> Bearer nv-************
X-NCP-CLOVASTUDIO-REQUEST-ID Optional 요청에 대한 아이디
Content-Type Required 요청 데이터의 형식
  • application/json
Accept Conditional 응답 데이터의 형식
  • text/event-stream
참고
  • 응답 결과는 기본적으로 JSON 형태로 반환되지만, Accepttext/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 최대 생성 토큰 수
  • 0 < maxTokens ≤ 4096 (기본값: 100)
  • 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 필터(생성된 결괏값에 대해 욕설, 비하/차별/혐오, 성희롱/음란 등 카테고리별로 해당하는 정도) 결과 표시 여부
    • false (기본값) | true
      • false: 표시 안 함
      • true: 표시

    messages

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

    필드 타입 필수 여부 설명
    role Enum Required 대화 메시지 역할
    • system | user | assistant
      • system: 역할을 규정하는 지시문
      • user: 사용자의 발화 또는 질문
      • assistant: 사용자의 발화 또는 질문에 대한 답변
    content String | Array Required 대화 메시지 내용

    content

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

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

    일부 필드 입력 시 다음 내용을 확인해 주십시오.

    • HCX-005
      • 입력 토큰과 출력 토큰의 합은 128,000 토큰을 초과할 수 없습니다.
      • 입력 토큰은 최대 128,000 토큰까지 가능합니다.
      • 모델에 요청할 출력 토큰(maxTokens)은 최대 4,096 토큰까지 가능합니다.
      • messages: 턴 당 이미지는 1개 포함 가능하고, 요청당 이미지는 최대 5개 포함할 수 있습니다.
        • 전체 Request Body 크기는 50MB 이하여야 합니다. 따라서 여러 개의 이미지를 요청에 포함하는 경우 base64 형식보다 image URL 사용을 권장합니다.
    • HCX-DASH-002
      • 입력 토큰과 출력 토큰의 합은 32,000 토큰을 초과할 수 없습니다.
      • 입력 토큰은 최대 32,000 토큰까지 가능합니다.
      • 모델에 요청할 출력 토큰(maxTokens)은 최대 4,096 토큰까지 가능합니다.
    • 이미지 입력과 Function calling 요청을 동시에 할 수 없습니다.

    요청 예시

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

    curl --location --request POST 'https://clovastudio.stream.gov-ntruss.com/testapp/v3/chat-completions/{modelName}' \
    --header 'Authorization: Bearer <API-KEY>' \
    --header 'X-NCP-CLOVASTUDIO-REQUEST-ID: <X-NCP-CLOVASTUDIO-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": "이 사진에 대해서 설명해줘"
              }
            ]
          }
        ],
            "temperature": 0.5,
            "topK": 0,
            "topP": 0.8,
            "repetitionPenalty": 1.1,
            "stop": [],
            "maxTokens": 100,
            "includeAiFilters": false
        }'
    

    응답

    응답 형식을 설명합니다.

    응답 헤더

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

    헤더 필수 여부 설명
    Content-Type - 응답 데이터의 형식
    • application/json

    응답 바디

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

    필드 타입 필수 여부 설명
    status Object - 응답 상태
    result Object - 응답 결과
    result.created Integer - 응답 날짜 (Unix timestamp 형식)
    result.usage Object - 토큰 수 정보
    result.usage.promptTokens Integer - 입력 토큰 수
    result.usage.completionTokens Integer - 생성 토큰 수
    result.usage.totalTokens Integer - 전체 토큰 수(promptTokens+completionTokens
    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 에 지정한 문자 출현 또는 모델이 정상적으로 생성 완료
    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

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

    필드 타입 필수 여부 설명
    id String - 요청을 식별하는 이벤트 아이디
    message Object - 대화 메시지
    message.role Enum - 대화 메시지 역할
    • system | user | assistant
      • system: 역할을 규정하는 지시문
      • user: 사용자의 발화 또는 질문
      • assistant: 모델의 답변
    message.content String - 대화 메시지 내용
    finishReason String - 결괏값 생성 중단 이유
    • length | stop
      • length: 설정한 최대 토큰 수 도달
      • stop: 답변 생성 중 stop 에 지정한 문자 출현 또는 모델이 정상적으로 생성 완료
    created Integer - 응답 날짜 (Unix timestamp 형식)
    seed Integer - 입력 seed 값(0 입력 또는 미입력 시 랜덤 값 반환)
    usage Object - 토큰 수 정보

    StreamingChatCompletionsResultEvent

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

    필드 타입 필수 여부 설명
    id String - 요청을 식별하는 이벤트 아이디
    message Object - 대화 메시지
    message.role Enum - 대화 메시지 역할
    • system | user | assistant
      • system: 역할을 규정하는 지시문
      • user: 사용자의 발화 또는 질문
      • assistant: 모델의 답변
    message.content String - 대화 메시지 내용
    finishReason String - 결괏값 생성 중단 이유
    • length | stop
      • length: 설정한 최대 토큰 수 도달
      • stop: 답변 생성 중 stop 에 지정한 문자 출현 또는 모델이 정상적으로 생성 완료
    created Integer - 응답 날짜 (Unix timestamp 형식)
    seed Integer - 입력 seed 값(0 입력 또는 미입력 시 랜덤 값 반환)
    usage Object - 토큰 수 정보
    usage.promptTokens Integer - 입력 토큰 수
    usage.completionTokens Integer - 생성 토큰 수
    result.usage.totalTokens Integer - 전체 토큰 수(promptTokens+completionTokens
    aiFilter Array - AI 필터 결과

    ErrorEvent

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

    필드 타입 필수 여부 설명
    status Object - 응답 상태

    SignalEvent

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

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

    응답 예시

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

    성공

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

    id: 484f9a63-8231-441b-b2dc-683ed135dd03
    event: signal
    data:
    {
      "data": "[DONE]"
    }
    
    id: 8138bd06-9d29-43fb-9a91-72bc12bd31a1
    event: result
    data:
    {
      "message": {
          "role": "assistant",
          "content": "문구: 생각을 기록하고, 꿈을 그리다. 내 삶의 이야기, 다이어리가 함께합니다."
      },
      "finishReason": "stop",
      "created": 1734016821,
      "seed": 1342914828,
      "usage": {
          "promptTokens": 98,
          "completionTokens": 212,
          "totalTokens": 310
     }
    }
    
    id: 9517637c-17aa-4a4a-a076-3fde680a953e
    event: token
    data:
    {
      "message": {
          "role": "assistant",
          "content": "."
      },
      "finishReason": null,
      "created": 1734016821,
      "seed": 1342914828,
      "usage": null
    }
    
    id: 1dd8d882-4b8c-4435-abc5-f58bdbbc17a8
    event: token
    data:
    {
      "message": {
          "role": "assistant",
          "content": "합니다"
      },
      "finishReason": null,
      "created": 1734016821,
      "seed": 1342914828,
      "usage": null
    }
    …
    

    실패

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