일지 #3 OpenAI API 사용법 (챗 컴플리션 API / 리스폰스 API)

 

오늘은 본격적으로 OpenAI와 Entropic의 API를 사용해 볼 것이다.

 

먼저 모델의 특징을 잘 이해하는 것이 중요하므로 최신 모델들의 특징을 정리해보겠다. (2026.10 기준)

 

- OpenAI

#1 추론 모델 (Reasoning Models): 복잡하고 다단계의 문제 해결, 코딩, 논리적 추론에 특화된 모델들
GPT-5 / GPT-5 pro	가장 강력한 성능을 자랑하며, 심도 있는 연구나 오류가 없어야 하는 매우 복잡한 작업에 적합함
GPT-5 mini	뛰어난 추론 능력을 더 빠르고 저렴하게 제공하여 챗봇이나 내부 도구 개발에 효율적임
GPT-5 nano	가장 빠르고 경제적인 모델로, 문서 요약이나 단순 분류 등 반복적인 논리 작업에 최적화되어 있음
o3 / o4-mini	고도의 수학적, 논리적 문제 해결 능력을 갖춘 모델

#2 다목적 일반 모델(General-purpose Models): 텍스트와 이미지 등 다양한 범위의 작업을 안정적으로 처리하는 다재다능한 모델들
GPT-4.1 (mini / nano)	비용과 성능의 균형을 맞춘 모델 시리즈

#3 특수 및 멀티모달 모델 (Specialized Models): 특정 작업에 매우 뛰어난 성능을 발휘하도록 미세 조정된 모델들
Sora 2	텍스트를 고품질 비디오로 변환해주는 모델
GPT realtime mini	음성 인식 및 음성 대 음성(Speech-to-Speech) 실시간 처리에 특화되어 있음

#4 오픈 가중치 모델 (Open-weight Models): 사용자가 직접 다운로드하여 자체 환경에서 구동하고 커스터마이징 할 수 있는 모델
gpt-oss-120b	gpt-oss-20b

 

 

 

---

# OpenAI API의 사용법

API를 사용하는 방법은 REST API와 파이썬용 SDK를 사용하는 선택지가 있지만 여기서는 pip install openai로 가볍게 설치할 수 있는 파이썬용 SDK를 사용해 볼 것이다.

 

OpenAI에는 API가 꽤 다양한 버전으로 있다. (2026년도 10월 기준)

1. Responses API
2. Decisions API
3. Realtime API
4. Agents SDK / Multi-agent

1. Responses API	텍스트, 이미지, 파일 등 다양한 입력을 전달하고 모델의 응답을 생성하는 가장 기본적이고 핵심적인 API. 웹 검색, 파일 검색, 함수 호출 같은 도구를 연결하여 기능을 확장할 수 있다.
2. Decisions API	애플리케이션의 특정 조건이나 상태에 따른 의사 결정 및 분류 워크플로우를 처리하는 API
3. Realtime API	WebRTC 또는 WebSocket을 기반으로 텍스트, 오디오, 이미지 입력을 처리하여 실시간 음성 대 음성(Speech-to-speech) AI 앱 등 지연 시간이 적은 양방향 앱을 구축할 때 사용한다.
4. Agents SDK 및 Multi-agent	사용자를 대신해 컴퓨터 제어 등 실제 '행동(Action)'을 취할 수 있는 AI 에이전트를 구축함. 서버에서 여러 에이전트 간의 워크플로우나 작업 이관(Handoff)을 제어할 수 있다.

 

 

텍스트 생성과 관련된 API의 장단점은 다음과 같다. (2026년 10월 기준)

텍스트/대화 생성 핵심 API	장점	단점
1. Responses API	가장 범용적이고 유연함. 단순 채팅부터 문서 요약, 번역 등 거의 모든 텍스트 생성 작업에 적용할 수 있으며 웹 검색, 파일 검색, 외부 함수 호출(Function calling) 등 다양한 도구를 쉽게 연결하여 기능을 확장할 수 있음.	과거의 대화 기록을 기억하지 않으므로, 대화의 문맥(Conversation state)을 개발자가 직접 데이터베이스 등에 저장하고 매 요청마다 모델에 함께 전달해야 하는 번거로움이 있음.
2. Decisions API	텍스트 입력을 분석해 다음 단계로 라우팅하거나 의도를 정확하게 분류하는 등, 구조화된 결과값이 필요한 로직에 매우 일관적이고 효율적으로 동작함.	자유로운 형태의 창의적인 텍스트 생성에는 적합하지 않으며 용도가 시스템 내부의 '판단 및 제어'로 제한적임.
3. Realtime API	텍스트 생성 속도와 반응성을 극한으로 끌어올린 초저지연(Low-latency) 통신이 가능함. 끊김 없는 실시간 번역, 실시간 음성 대 음성 AI 비서 등 즉각적인 피드백이 필수적인 서비스에 최적화 되어 있음.	HTTP 기반의 단발성 호출이 아닌 지속적인 실시간 세션을 유지해야 하므로, 네트워크 안정성 관리 및 백엔드 인프라 구현 난이도가 훨씬 높음. 일반적인 텍스트 생성 앱에서는 오버엔지니어링이 될 수 있음.
4. Agents SDK / Multi-agent	개발자가 명시적으로 지시하지 않아도 모델이 스스로 계획을 세우고 도구를 사용해 복잡한 다단계 문제를 해결함. 서버 측에서 여러 에이전트 간의 작업 이관과 워크플로우를 유기적으로 제어하기 좋음.	에이전트가 문제를 해결하기 위해 내부적으로 연쇄적인 API 호출을 발생시키므로 토큰 사용량과 비용이 예상보다 크게 증가할 수 있음. 또한 환각(Hallucination) 오류나 무한 루프에 빠질 위험이 있어 안전성(Safety) 제어가 까다로움.

 

 

 

---

 

책에서는 레거시 모델인 챗 컴플리션(Chat Completion) API에 gpt-5-mini 모델을 사용해서 진행한다.

 

우선 오픈 AI API를 사용하려면 파이썬 SDK를 설치해야 한다.

pip install openai==1.70.0

 

 

이후 간단한 예제를 다음 코드와 같이 만들고 chapter1 폴더에 hello_openai.py 파일명으로 저장한다.

import os
from dotenv import load_dotenv
from openai import OpenAI

#1 .env 파일에서 환경 변수 로드
load_dotenv()

#2 OpenAI API 키 가져오기
api_key = os.environ.get('OPENAI_API_KEY')

#3 OpenAI 클라이언트 초기화
client = OpenAI(api_key=api_key)

def get_chat_completion(prompt, model="gpt-5-mini"):
    # OpenAI 챗 컴플리션 API를 사용하여 AI의 응답을 받는 함수

    # 챗 컴플리션 API 호출
    response = client.chat.completions.reate(
        model=model,
        messages=[
            {"role": "system", "content": "당신은 친절하고 도움이 되는 AI 비서입니다."}, 
            {"role": "user", "content": prompt}
        ]
    )

    #5 응답 텍스트 반환
    return response.choices[0].message.content

if __name__ == "__main__":
    
    #6 사용자 입력받기
    user_prompt = input("AI에게 물어볼 질문을 입력하세요:")

    #7 AI 응답받기
    response = get_chat_completion(user_prompt)
    print("\nAI 응답:")
    print(response)

 

 

 

VSCode에서 프로젝트 디렉토리에 .env 라는 파일을 만들고 API key를 추가해준다.

OpenAI_API_KEY = 발급받은_키

 

 

이제 이전에 만들었던 .venv 환경을 활성화시키고 파이썬 스크립트를 실행시킨다.

 

그럼 이런 식으로 질문을 입력하라고 터미널에 뜨게 되고 질문을 입력하면 답변이 출력된다.

(API 크레딧을 구매해야 사용할 수 있다...)

 

 

이렇게 챗 컴플리션 AI는 단발성 질문을 할 때 편리하다.

코딩을 통해서 다양한 기능을 추가할 수 있고 편의 기능이 필요할 때 OpenAI에서 준비해둔 리스폰스 API를 사용하면 편하게 구현할 수 있어서, 새로 만드는 고생을 할 수 없다. 

 

다음으로는 리스폰스 API에 대해서 알아보자.

 

 

---

 

리스폰스 API는 챗 컴플리션 API와 사용하는 방법이 거의 비슷하지만 기능이 더 많다.

간단한 요청은 챗 컴플리션 API를 사용하면 되고, 새로 만드는 API는 리스폰스 API를 사용하는 것이 좋다.

 

눈여겨 볼 특징은 LLM이 도구를 사용할 수 있다는 것이다. 기본 내장된 도구는 웹 검색, 파일 검색이 있다.

이번 예제로는 웹 검색을 해서 글을 요약해 볼 것이다.

 

아래와 같이 코드를 작성하고 chapter1 폴더에 hello_openai_responses.py라고 저장한다.

from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()
client = OpenAI()   # OpenAI 클라이언트 초기화


def get_responses(prompt, model='gpt-5-mini'):
    #1 입력된 프롬프트에 대한 AI 응답을 받아오는 함수
    response = client.responses.create(
        model=model,    # 사용할 모델 지정
        tools=[{"type": "web_search_preview"}],   #2 웹 검색 도구 활성화
        input=prompt    # 사용자 입력 전달
    )

    return response.output_text    # 텍스트 응답만 반환


#3 스크립트가 직접 실행될 때 실행
if __name__ == '__main__':
    prompt = """
https://platform.openai.com/docs/api-reference/responses/create
를 읽어서 리스폰스 API에 대해 요약 정리해주세요.
"""

    output = get_responses(prompt)   
    print(output)   # 결과 출력

 

 

 

해당 코드를 실행하면 아래와 같이 문서를 정리해준다.

 

 

 

 

오늘은 여기까지만 하고 다음 시간엔 앤트로픽 API 사용해볼란다...

이제 곧 수업 들으러 가야함..

 

그럼 이만 안녕~~!

 

 

 

 

 

 

---

[이전 글]

2026.10.18 - [무한도전!!/Agent-ai 마스터하기!!] - 일지 #2 깃 환경 초기화 / 로컬 저장소와 원격 저장소(GitHub) 연결하기 / LLM과 랭체인(LangChain) 개발

일지 #2 깃 환경 초기화 / 로컬 저장소와 원격 저장소(GitHub) 연결하기 / LLM과 랭체인(LangChain) 개발

 

[참고 도서]  "요즘 ai 에이전트 개발 LLM RAG ADK MCP LangChain A2A LangGraph (박승규)"