---
title: "오픈AI 호환성"
slug: "clovastudio-openaicompatibility"
updated: 2026-10-22T10:46:35Z
published: 2026-10-22T10:46:35Z
canonical: "api-gov.ncloud-docs.com/clovastudio-openaicompatibility"
---

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

# 오픈AI 호환성

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

CLOVA Studio 서비스는 Chat Completions, 임베딩을 비롯한 주요 API에 대해 오픈AI API와의 호환성을 제공합니다.

## 호환 API

CLOVA Studio 서비스에서 오픈AI API와 호환되는 API 목록은 다음과 같습니다.

| API | 메서드 | URI |
| --- | --- | --- |
| Chat Completions, Chat Completions v3 | POST | `/chat/completions` |
| 임베딩 v2 | POST | `/embeddings` |
| 모델 조회 | GET | `/models` |

## 사용 방법

오픈AI 호환 API의 요청 형식과 응답 형식을 설명합니다.

### 요청

CLOVA Studio API의 요청 항목을 일부 조정하여 OpenAI 공식 라이브러리(SDK) 및 REST API로 이용할 수 있습니다.

#### API 키

CLOVA Studio 서비스에서 발급받은 테스트 또는 서비스 API 키를 이용합니다.

          주의

          

오픈AI 호환 API는 CLOVA Studio의 **[API 키]** 에서 발급받은 테스트 API 키나 서비스 API 키를 통해서만 사용할 수 있습니다. 테스트 API 키를 사용하는 경우에는 테스트 앱을, 서비스 API 키를 사용하는 경우에는 서비스 앱을 이용하는 것으로 간주합니다.

#### API URL

요청 API URL은 다음과 같습니다.

```
https://clovastudio.stream.gov-ntruss.com/v1/openai/
```

          참고

          

오픈AI 호환 API URL은 `testapp`, `serviceapp`을 포함하지 않습니다. 테스트 앱과 서비스 앱은 API 키를 통해 구별합니다. 다음 예시를 참고해 주십시오. <예시>

- Chat Completions v3 API URL
  - 테스트 앱: https://clovastudio.stream.gov-ntruss.com/testapp/v3/chat-completions/{modelName}
  - 서비스 앱: https://clovastudio.stream.gov-ntruss.com/serviceapp/v3/chat-completions/{modelName}
- 오픈AI 호환 Chat Completions API URL
  - https://clovastudio.stream.gov-ntruss.com/v1/openai/chat/completions

#### 모델

요청 바디의 모델 이름은 CLOVA Studio 서비스에서 제공하는 모델 이름으로 입력해 주십시오.

#### 명명 규칙

요청 필드의 명명 규칙은 스네이크 표기법(snake_case)을 준수합니다.

### 응답

오픈AI API와 동일한 구조와 형식의 응답 결과를 지원합니다.

## SDK 예제

OpenAI 공식 라이브러리를 활용하여 CLOVA Studio 서비스를 이용하는 예제를 소개합니다.

### Python

Python으로 작성한 예제는 다음과 같습니다.

```
from openai import OpenAI

client = OpenAI(
    api_key="CLOVA_STUDIO_API_KEY",  # CLOVA Studio API 키
    base_url="https://clovastudio.stream.gov-ntruss.com/v1/openai"  # CLOVA Studio 오픈AI 호환 API URL 
)

# Chat Completions
response = client.chat.completions.create(
    model="HCX-005",  # CLOVA Studio 지원 모델명
    messages=[
        {"role": "system", "content": "당신은 유능한 AI 어시스턴트입니다."},
        {"role": "user", "content": "인공지능에 대해 설명해 주세요."}
    ]
)

print(response.choices[0].message.content)

# Embeddings
embedding = client.embeddings.create(
    model="bge-m3", # CLOVA Studio 지원 모델명 (임베딩)
    input="클로바 스튜디오를 이용해주셔서 감사합니다.",
    encoding_format="float" # 오픈AI Python SDK로 임베딩을 이용하는 경우 필수 (`base64` 미지원)
    )
```

          유의사항

          

OpenAI 공식 Python 라이브러리로 임베딩을 이용하고자 하는 경우, `encoding_format="float"` 설정이 필수입니다.

### TypeScript/JavaScript (Node.js)

TypeScript/JavaScript (Node.js)로 작성한 예제는 다음과 같습니다.

```
import OpenAI from "openai";

const openai = new OpenAI({
    baseURL: "https://clovastudio.stream.gov-ntruss.com/v1/openai", // CLOVA Studio 오픈AI 호환 API URL
    apiKey: "YOUR_API_KEY",
    }); // CLOVA Studio API 키

// Chat Completions
const completion = await openai.chat.completions.create({
    model: "HCX-005",   // CLOVA Studio 지원 모델명
    messages: [
        {"role": "system", "content": "당신은 유능한 AI 어시스턴트입니다."},
        {"role": "user", "content": "인공지능에 대해 설명해 주세요."}
    ]
});

console.log(completion.choices[0].message);

// Embedding
const embedding = await openai.chat.completions.create({
    model: "bge-m3",   // CLOVA Studio 지원 모델명 (임베딩)
    input: "클로바 스튜디오를 이용해주셔서 감사합니다."    
});

console.log(embedding.data[0].embedding);
```

          참고

          

이외 다양한 언어의 OpenAI 공식 SDK 및 호환 API로 구현된 오픈소스 프레임워크를 통해 CLOVA Studio를 이용할 수 있습니다.

## 호환 정보

오픈AI API와 호환되는 API별 상세 호환 정보를 안내합니다. 지원 필드와 CLOVA Studio 전용 필드의 입력 형식 및 범위는 해당 API 가이드를 확인해 주십시오.

### Chat Completions/Chat Completions v3

Chat Completions API, Chat Completions v3 API의 오픈AI 호환 정보는 다음과 같습니다.

| 지원 필드 | 미지원 필드 | CLOVA Studio 전용 필드 |
| --- | --- | --- |
| - `model` - `messages` - `stream` - `tools` - `tool_choice` - `temperature` - `max_tokens` (기본값: 512) - `max_completion_tokens` (기본값: 512) - `top_p` - `stop` - `seed` | - `frequency_penalty` - `presence_penalty` - `response_format` - `store` - `reasoning_effort` - `metadata` - `logit_bias` - `logprobs` - `top_logprobs` - `n` - `modalities` - `prediction` - `audio` - `service_tier` - `stream_options` - `parallel_tool_calls` - `user` | - `top_k` - `repeat_penalty` - `repetition_penalty` |

### 임베딩/임베딩 v2

임베딩 API, 임베딩 v2 API의 오픈AI 호환 정보는 다음과 같습니다.

| 지원 필드 | 미지원 필드 | CLOVA Studio 전용 필드 |
| --- | --- | --- |
| - `input` - `model` | - `dimensions` - `encoding_format` - `user` | - |