---
title: "오픈AI 호환성"
slug: "clovastudio-openaicompatibility"
updated: 2026-09-17T09:15:56Z
published: 2026-09-17T09:15:56Z
canonical: "api.ncloud-docs.com/clovastudio-openaicompatibility"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.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 URL

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

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

#### 모델

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

#### 명명 규칙

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

          참고

          

CLOVA Studio의 Chat Completions (V3 포함), 임베딩 API 필드 명명 규칙이 카멜 표기법(camelCase)을 따르는 것과 상이한 점에 유의하시기 바랍니다. 지원/미지원 필드 목록은 [호환 정보](/docs/clovastudio-openaicompatibility#%ED%98%B8%ED%99%98%EC%A0%95%EB%B3%B4)를 참고해주세요.

### 응답

오픈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.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 미지원)
    )
    
print(embedding.data[0].embedding)
```

          유의사항

          

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.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 전용 필드 |
| --- | --- | --- |
| - `messages` - `messages[].name` - `model` - `stream` - `max_completion_tokens` (기본값: 512) - `max_tokens` (기본값: 512) - `n` - `temperature` - `tools` - `tool_choice` - `parallel_tool_calls` - `reasoning_effort` \| `reasoning.effort` - `response_format` - `top_p` - `stop` - `seed` | - `audio` - `frequency_penalty` - `logit_bias` - `logprobs` - `metadata` - `modalities` - `prediction` - `presence_penalty` - `prompt_cache_key` - `safety_identifier` - `service_tier` - `store` - `stream_options` - `top_logprobs` - `user` - `web_search_options` | - `top_k` - `repeat_penalty` - `repetition_penalty` |

          참고

          

아래 필드는 CLOVA Studio에서 지원하는 범위 내에서 호환성을 제공합니다.

- `n`: `1` (유효값, 기본값)
- `tool_choice`: `auto` (기본값) | `none` | object (특정 도구 호출)
- `parallel_tool_calls`: `true` (유효값, 기본값)
- `reasoning_effort` (또는 `reasoning.effort`): `none` | `low` | `medium` | `high`
- `response_format.type`: `json_schema` (유효값)
- `response_format.json_schema.name`: Optional 지원 (입력값 미인식)
- `response_format.json_schema.strict`: Optional 지원 (입력값 미인식)

### 임베딩/임베딩 v2

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

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

          참고

          

아래 필드는 CLOVA Studio에서 지원하는 범위 내에서 호환성을 제공합니다.

- `dimensions`: `1024` (유효값, 기본값)
- `encoding_format`: `float` (유효값, 기본값)