OpenAI Chat Completions 호환 모드

/v1/chat/completions은 LLM 업계의 사실상 표준 인터페이스입니다. 사실상 모든 프레임워크, 클라이언트, SDK가 별도 설정 없이 이를 지원합니다. APIYI를 통해 이 단일 엔드포인트는 OpenAI, Claude, Gemini, DeepSeek를 비롯한 총 400개 이상의 모델에 도달하며, 모델 전환은 문자열만 바꾸면 됩니다.

어떤 엔드포인트를 선택할지: 기존 프레임워크/클라이언트를 사용하거나 여러 벤더에 걸쳐 하나의 코드베이스를 원한다면 → 호환 모드(이 페이지); 내장 도구(웹 검색, 코드 인터프리터)나 Pro 시리즈 모델이 필요하다면 → 네이티브 호출 (/v1/responses). OpenAI의 Chat Completions에 대한 공식 입장: 장기적으로 지원되지만, 새 프로젝트에는 Responses가 권장됩니다. 두 엔드포인트 모두 대화 기록을 직접 유지해야 합니다 — 멀티 턴 대화 가이드를 참조하십시오.

빠른 시작

curl https://api.apiyi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {"role": "user", "content": "Introduce yourself in one sentence"}
    ]
  }'

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Introduce yourself in one sentence"}]
)

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

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.apiyi.com/v1'
});

const response = await openai.chat.completions.create({
  model: 'gpt-5.4',
  messages: [{ role: 'user', content: 'Introduce yourself in one sentence' }]
});

console.log(response.choices[0].message.content);

하나의 인터페이스, 모든 공급자

호환 모드의 가장 큰 이점은 이것입니다: 모델을 바꾸는 것은 코드 한 줄이 아니라 문자열 하나를 바꾸는 것입니다.

def ask(message: str, model: str) -> str:
    response = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": message}]
    )
    return response.choices[0].message.content

print(ask("Explain quantum entanglement", "gpt-5.4"))               # OpenAI
print(ask("Explain quantum entanglement", "claude-sonnet-4-6"))      # Anthropic
print(ask("Explain quantum entanglement", "gemini-3-pro-preview"))   # Google
print(ask("Explain quantum entanglement", "deepseek-chat"))          # DeepSeek

전체 모델 이름과 가격: 모델 및 가격. 참고: 호환 형식으로 Claude를 호출하면 Claude의 Prompt Cache 할인이 적용되지 않습니다 — Claude를 많이 사용하는 경우 Claude 네이티브 호출을 사용하십시오.

언어별 SDK 설정

모든 공식 SDK는 사용자 지정 base_url을 지원합니다 — 한 번 설정하면 바로 사용할 수 있습니다.

Python

pip install openai

from openai import OpenAI, AsyncOpenAI

# Synchronous client
client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

# Async client
async_client = AsyncOpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

아니면 코드 내 설정 없이 사용하려면 환경 변수를 사용하십시오:

export OPENAI_API_KEY="YOUR_API_KEY"
export OPENAI_BASE_URL="https://api.apiyi.com/v1"

from openai import OpenAI
client = OpenAI()  # reads the environment automatically

Node.js / TypeScript

npm install openai

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: 'https://api.apiyi.com/v1'
});

const response = await openai.chat.completions.create({
  model: 'gpt-5.4-mini',
  messages: [{ role: 'user', content: 'Hello!' }],
  temperature: 0.7
});

.NET

dotnet add package OpenAI

using OpenAI;
using OpenAI.Chat;

var client = new OpenAIClient(
    new System.ClientModel.ApiKeyCredential("YOUR_API_KEY"),
    new OpenAIClientOptions { Endpoint = new Uri("https://api.apiyi.com/v1") }
);

var chatClient = client.GetChatClient("gpt-5.4");
var response = await chatClient.CompleteChatAsync("Hello!");
Console.WriteLine(response.Value.Content[0].Text);

Go

공식 OpenAI Go SDK(github.com/openai/openai-go)를 사용하십시오:

go get github.com/openai/openai-go

package main

import (
    "context"
    "fmt"

    "github.com/openai/openai-go"
    "github.com/openai/openai-go/option"
)

func main() {
    client := openai.NewClient(
        option.WithAPIKey("YOUR_API_KEY"),
        option.WithBaseURL("https://api.apiyi.com/v1"),
    )

    completion, err := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{
        Model: "gpt-5.4",
        Messages: []openai.ChatCompletionMessageParamUnion{
            openai.UserMessage("Hello!"),
        },
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(completion.Choices[0].Message.Content)
}

Java

공식 OpenAI Java SDK(com.openai:openai-java)를 사용하십시오:

<dependency>
    <groupId>com.openai</groupId>
    <artifactId>openai-java</artifactId>
    <version>LATEST</version>
</dependency>

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.builder()
    .apiKey("YOUR_API_KEY")
    .baseUrl("https://api.apiyi.com/v1")
    .build();

ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .model("gpt-5.4")
    .addUserMessage("Hello!")
    .build();

ChatCompletion completion = client.chat().completions().create(params);
System.out.println(completion.choices().get(0).message().content().orElse(""));

서드파티 라이브러리 기반의 레거시 프로젝트(Go의 sashabaranov/go-openai, Java의 theokanning 패키지)는 base_url을 변경한 뒤에도 계속 동작하지만, 위의 공식 SDK로 마이그레이션하는 것을 권장합니다 — 서드파티 라이브러리는 reasoning_effort와 같은 새 매개변수에 뒤처지는 경우가 있습니다.

공통 기능

스트리밍

stream = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Write a short poem about autumn"}],
    stream=True
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

추론 제어

Chat Completions에서는 Responses의 중첩 형식과 다른 최상위 reasoning_effort 매개변수를 사용합니다:

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Prove that the square root of 2 is irrational"}],
    reasoning_effort="high"  # none / low / medium / high / xhigh
)

GPT-5.4 및 이후 버전(gpt-5.6 시리즈 포함)에서는 이 엔드포인트에서 tools와 reasoning_effort를 함께 사용할 수 없습니다: tools를 포함하면서 reasoning_effort가 none이 아니면 400 오류로 실패합니다 — Function tools with reasoning_effort are not supported for ... in /v1/chat/completions. 매개변수를 생략해도 기본값이 medium이므로 도움이 되지 않습니다. 이는 공식 OpenAI 제한입니다. 추론과 도구 호출을 함께 사용하려면 Responses 엔드포인트로 전환하거나, reasoning_effort="none"를 명시적으로 설정하십시오.

gpt-5 시리즈 추론 모델도 이 엔드포인트에서 temperature / top_p를 지원하지 않습니다. 전달하면 오류가 발생합니다.

이미지 입력

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What's in this image?"},
                {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
            ]
        }
    ]
)

임베딩

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Text to embed"
)
embedding = response.data[0].embedding

오류 처리 및 재시도

공식 SDK는 자동으로 재시도합니다(기본값으로 2회 시도, 429 / 5xx / 연결 오류 시) — 직접 작성한 루프보다 이를 사용하는 것이 좋습니다:

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1",
    max_retries=3,   # built-in exponential backoff
    timeout=60.0
)

더 세밀하게 제어하려면 예외 유형별로 catch하십시오:

from openai import (
    APIError,
    APIConnectionError,
    RateLimitError,
    InternalServerError,
)

try:
    response = client.chat.completions.create(
        model="gpt-5.4",
        messages=[{"role": "user", "content": "Hello"}]
    )
except RateLimitError:
    print("Rate limited — retry later")
except APIConnectionError:
    print("Connection error — check network/proxy")
except InternalServerError:
    print("Upstream error — worth retrying")
except APIError as e:
    print(f"API error: {e}")

호환 모드의 기능 경계

기능	호환 모드	비고
채팅 / 스트리밍 / 다중 모달 입력	✅	완전히 지원됩니다
Function calling (FC)	✅	Function Calling 참조
Prompt cache 할인	✅	OpenAI 모델에는 자동 적용됩니다 — Cache Billing 참조
내장 도구(web search, code interpreter, …)	❌	Native Calls만 해당됩니다
멀티턴 대화	✅	`messages` 기록을 직접 유지해야 합니다(네이티브 Responses도 직접 관리하는 기록이 필요합니다 — Multi-Turn Guide 참조)
`verbosity` 출력 제어	❌	네이티브 전용
Pro 시리즈 모델 (gpt-5.4-pro, …)	❌	실제로는 네이티브 호출만 가능합니다

OpenAI Direct에서 마이그레이션

OpenAI의 공식 서비스를 이미 사용 중이신가요? 마이그레이션은 코드 변경 없이 두 단계로 완료됩니다.

base_url과 키를 변경합니다

# Before
client = OpenAI(api_key="sk-...")

# After
client = OpenAI(
    api_key="YOUR_APIYI_KEY",
    base_url="https://api.apiyi.com/v1"
)

환경 변수만 변경합니다 (코드는 그대로 유지)

export OPENAI_API_KEY="YOUR_APIYI_KEY"
export OPENAI_BASE_URL="https://api.apiyi.com/v1"

메서드 호출, 매개변수 형식, 응답 구조는 모두 동일하게 유지됩니다.

기초

기본 API

이미지 API (공식)

동영상 API (공식)

멀티모달 이해 API

텍스트 API

OpenAI Chat Completions 호환 모드

빠른 시작

하나의 인터페이스, 모든 공급자

언어별 SDK 설정

Python

Node.js / TypeScript

.NET

Go

Java

공통 기능

스트리밍

추론 제어

이미지 입력

임베딩

오류 처리 및 재시도

호환 모드의 기능 경계

OpenAI Direct에서 마이그레이션

관련 링크

​빠른 시작

​하나의 인터페이스, 모든 공급자

​언어별 SDK 설정

​Python

​Node.js / TypeScript

​.NET

​Go

​Java

​공통 기능

​스트리밍

​추론 제어

​이미지 입력

​임베딩

​오류 처리 및 재시도

​호환 모드의 기능 경계

​OpenAI Direct에서 마이그레이션

​관련 링크

빠른 시작

하나의 인터페이스, 모든 공급자

언어별 SDK 설정

Python

Node.js / TypeScript

.NET

Go

Java

공통 기능

스트리밍

추론 제어

이미지 입력

임베딩

오류 처리 및 재시도

호환 모드의 기능 경계

OpenAI Direct에서 마이그레이션

관련 링크