OpenAI 호환성 API를 통해 개발자는 OpenAI SDK를 사용하여 Clova Studio의 모델을 사용할 수 있습니다. 기존 OpenAI 기반 애플리케이션을 Clova Studio 모델로 쉽게 전환할 수 있으며, 대규모 리팩토링 없이 OpenAI SDK를 계속 사용할 수 있습니다.

​
지원되는 API

Clova Studio는 다음 OpenAI 호환 API를 제공합니다:
  • Chat Completions - 대화형 AI 및 텍스트 생성
  • Embeddings - 텍스트 임베딩 생성
  • Speech to Text (STT) - 음성을 텍스트로 변환
  • Text to Speech (TTS) - 텍스트를 음성으로 변환

​
설치 및 설정

​
Python

먼저 OpenAI SDK를 설치하고 패키지를 가져옵니다. 
pip install openai
그런 다음 Clova Studio Gov API 베이스 URL과 API 키로 클라이언트를 구성합니다. 
from openai import OpenAI

client = OpenAI(
    base_url="https://api.clovastudio.go.kr/v1",
    api_key="YOUR_API_KEY`",
)

​
TypeScript / JavaScript

npm install openai

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.clovastudio.go.kr/v1',
  apiKey: 'YOUR_API_KEY',
});

​
Chat Completions

OpenAI SDK를 사용하여 Chat Completions API를 호출하는 기본 예제입니다. 
from openai import OpenAI

client = OpenAI(
    base_url="https://api.clovastudio.go.kr/v1",
    api_key="YOUR_API_KEY",
)

completion = client.chat.completions.create(
    model="hcx-gov-think",
    messages=[
        {
            "role": "user",
            "content": "대한민국의 수도는 어디인가요?",
        },
    ],
)

print(completion.choices[0].message)

​
Embeddings

텍스트 임베딩을 생성하려면 embeddings.create 메서드를 사용합니다. 
from openai import OpenAI

client = OpenAI(
    base_url="https://api.clovastudio.go.kr/v1",
    api_key="YOUR_API_KEY",
)

response = client.embeddings.create(
    input=["안녕하세요, 세계!"],
    model="bge-m3",
)

print(response.data[0].embedding[:5])  # 첫 5개 차원 출력

​
Speech to Text (STT)

음성 파일을 텍스트로 변환하려면 audio.transcriptions.create 메서드를 사용합니다. 
from openai import OpenAI

client = OpenAI(
    base_url="https://api.clovastudio.go.kr/v1",
    api_key="YOUR_API_KEY",
)

with open("audio.mp3", "rb") as audio_file:
    transcription = client.audio.transcriptions.create(
        model="whisper-large-v3",
        file=audio_file,
    )

print(transcription.text)

​
Text to Speech (TTS)

텍스트를 음성으로 변환하려면 audio.speech.create 메서드를 사용합니다. 
from openai import OpenAI
from pathlib import Path

client = OpenAI(
    base_url="https://api.clovastudio.go.kr/v1",
    api_key="YOUR_API_KEY",
)

response = client.audio.speech.create(
    model="melo-tts-ko",
    voice="nara",
    input="안녕하세요, 반갑습니다.",
)

speech_file_path = Path(__file__).parent / "speech.mp3"
response.stream_to_file(speech_file_path)

​
에러 처리

OpenAI 호환 API는 OpenAI 형식의 에러 응답을 반환합니다: 
{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "401"
  }
}
에러 코드와 처리 방법에 대한 자세한 내용은 에러 처리 문서를 참조하세요.

​
다음 단계

Chat Completions

Chat Completions API 사용법 알아보기

텍스트 임베딩

텍스트 임베딩 생성 방법 알아보기

STT

음성을 텍스트로 변환하기

TTS

텍스트를 음성으로 변환하기