AI 주요 서비스와 도구 (2)#

이 장에서는 OpenAI에서 제공하는 API들에 대해 각각의 간단한 설명과 예시 코드를 소개합니다. 개발자가 아니더라도 API의 개념만 알고 있다면, OpenAI에서 제공하는 API들을 이용해 내 서비스를 만들고자 할 때 “내가 무엇을 할 수 있는지”를 이해하고 방향을 잡는 데 도움이 되지 않을까 싶습니다.


OpenAI에서 제공하는 API에 대하여#

OpenAI를 비롯한 AI 서비스 제공자들은 직접 ChatGPT와 같은 사용자향 서비스를 제공하기도 하지만, 외부 개발사에게 API를 제공하여 AI 서비스 생태계를 확장합니다. 직접 AI 모델을 구축하는 대신 API를 이용하여 빠르게 뛰어난 품질의 AI 서비스를 제공할 수 있기 때문에, 스타트업에게는 매우 합리적인 선택이죠.

그리고 (좀 다른 이야기이긴 합니다만) 개발자가 아닌 분들이 프로그래밍에 대한 학습의 시작점에 대해 문의해 주실 때, 필자는 대체로 쉽고 눈에 보이는 결과물이 있는 것을 추천했습니다. HTML과 Javascript로 동적인 페이지를 만들어 보거나, Python으로 웹페이지를 스크래핑하여 필요한 정보를 추출하는 등의 작은 목표를 세워서 학습하기를 추천했었는데요, OpenAI 및 구글 Gemini의 API를 연동해 보면서 추천 순위가 바뀌었습니다. AI 서비스에 대한 API를 연동해 보는 것이, 쉽고, 재미 있고, 동기 부여가 된다는 측면에서 가장 추천할 만하다고 생각합니다.

아래에 OpenAI의 API가 어떤 것들이 있고 무엇을 할 수 있는가에 대해서 간단하게 소개하겠습니다. 자세한 내용은 공식 문서를 참고해 주세요. 그리고 샘플 코드들이 길지 않고 상당히 직관적이라 문서에 같이 담았습니다.

Text generation#

기본적으로, 텍스트 데이터를 입력하여 텍스트 응답을 생성하는 API가 제공됩니다. 2026년 1월 기준 OpenAI Python SDK에서는 Responses API(client.responses.create)를 중심으로 사용하는 편이 일반적입니다. instructions는 “상황 설정(시스템 지침)”에 해당하고, input은 사용자 입력(또는 대화 히스토리)을 의미합니다.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
  model="gpt-5-mini",
  instructions="You are a helpful assistant.",
  input=[
    {"role": "user", "content": "Who won the world series in 2020?"},
    {"role": "assistant", "content": "The Los Angeles Dodgers won the World Series in 2020."},
    {"role": "user", "content": "Where was it played?"},
  ],
)

print(response.output_text)

여기서 눈여겨 볼 것은 role입니다. roleuser이면 “사용자가 한 말”, roleassistant이면 “모델이 이전에 했던 답변(대화 기록)”을 의미합니다.
그리고 흔히 말하는 **system instructions(시스템 지침)**은 대화를 시작하기 전에 AI에게 미리 주는 공통 지침(예: 역할 / 말투 / 금지사항 / 출력 형식)인데, 이 예시에서는 그 지침을 instructions에 넣어 따로 관리하고 있습니다.

Function calling#

RAG와 GPTs를 설명할 때 언급했던 바와 같이, LLM은 기본적으로 “학습된 정보”를 바탕으로 답하기 때문에 최신 정보나 내부 문서처럼 모델이 원래 모르던 정보를 다룰 때 한계가 생깁니다. 이 한계를 보완하기 위해 Fine-tune, RAG, Function calling(요즘은 “tool calling”이라고도 부릅니다) 같은 기술이 사용됩니다. GPTs에서 내 GPT를 만들 때 외부 API 호출을 위해 작업(Actions)을 추가하는 것은, 서버 입장에서 보면 “모델이 필요할 때 호출할 수 있는 도구(함수)를 정의해 주는 것”과 같은 개념입니다.

Function calling의 동작 흐름을 요약해 보면 아래와 같습니다.

  1. [사용자(클라이언트) ↔ 서버 ↔ 모델(GPT)] 구조를 가정하고 설명하겠습니다.
  2. 사용자가 질의한 내용을 서버가 받아서 모델에게 전달할 때, 함수(function)의 이름, 설명, 매개변수 등을 같이 전달합니다.(함수는 여러 개일 수 있고, 모두 서버에 구현되어 있습니다.)
  3. 모델이 입력을 받아서 응답을 생성할 때, 함수 호출이 필요한 상황인 경우 해당 함수가 무엇인지를 응답에 포함하여 서버에게 전달합니다.
  4. 함수 호출이 필요한 경우, 서버가 해당 함수를 호출합니다. 함수에는 필요한 알고리즘과 외부 API 호출 로직 등이 구현되어 있습니다.
  5. 서버가 함수의 실행 결과를 다시 모델에게 전달하면, 모델이 비로소 최종 응답을 생성하게 되고, 이것을 서버가 받아서 사용자에게 전달해 줍니다.

Function calling과 RAG는 “필요한 시점에 외부 정보를 가져와 입력을 보강한다”는 점에서는 비슷하지만 목적과 구현이 다릅니다. RAG는 보통 문서 / 지식 베이스에서 관련 내용을 검색해 컨텍스트로 붙이는 방식(질문 답변의 근거를 문서로 고정)이고, Function calling은 외부 시스템(API / DB / 업무 시스템 등)을 호출해 실제 데이터를 조회하거나 작업을 수행한 뒤 그 결과를 다시 모델 입력으로 넣어 최종 답변을 완성하는 방식입니다.

Image generation#

텍스트(프롬프트)를 입력하여 이미지를 생성하는 API가 제공됩니다. 이미지 생성은 텍스트 생성 모델(gpt-5-mini)과는 별개의 전용 이미지 모델을 사용합니다(예: gpt-image-1.5, dall-e-3 등). 생성된 이미지는 URL 또는 Base64로 받을 수 있는데, URL은 유효기간이 짧을 수 있으니 서비스에서 쓸 때는 다운로드해 보관하는 편이 안전합니다.

from openai import OpenAI

client = OpenAI()

response = client.images.generate(
  model="gpt-image-1.5",
  prompt="a white siamese cat",
  size="1024x1024",
  quality="standard",
  n=1,
)

image_url = response.data[0].url
print(image_url)
[응답 예시]
[
  Image(
    b64_json=None,
    revised_prompt="A Siamese cat with a pr..(생략)",
    url="https://oaidalleapiprodscus.blob.core..(생략)",
  )
]

위 코드를 실행하면 생성된 이미지의 URL을 얻을 수 있습니다. (원하는 디테일을 얻기 위해서는 프롬프트 엔지니어링이 중요합니다.)

위의 샘플 코드에서처럼, 텍스트 프롬프트를 제공하여 이미지를 생성하는 것 외에도(client.images.generate()), 기존 이미지와 마스킹 영역을 제공하여 해당 영역을 편집한 이미지를 생성할 수도 있고(client.images.edit()), 주어진 이미지와 비슷하지만 다르게 변형된 이미지를 생성할 수도 있습니다. (client.images.create_variation())

Vision#

이미지 데이터와 그에 대한 요청사항(텍스트 프롬프트)을 함께 입력해 텍스트 응답을 생성할 수 있습니다. 이미지에 대한 설명을 작성하거나, 이미지 안에 특정 객체가 있는지를 판별하거나, 여러 개의 이미지를 서로 비교하는 등의 요청을 할 수 있습니다.

from openai import OpenAI

client = OpenAI()

img_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"

response = client.responses.create(
  model="gpt-5-mini",
  input=[
    {
      "role": "user",
      "content": [
        {"type": "input_text", "text": "What's in this image?"},
        {"type": "input_image", "image_url": img_url},
      ],
    }
  ],
)
print(response.output_text)
[응답 예시]
This image depicts a picturesque scene of a wooden boardwalk path stretching through a grassy field. The sky is blue with some scattered clouds, and the surrounding vegetation is lush and green, suggesting a summer or late spring setting. Trees and shrubs can be seen in the background, adding to the serene and natural atmosphere of the landscape.

Text to speech#

텍스트 데이터를 입력하여, 그에 대한 음성 파일을 생성하는 API를 제공합니다. 이 기능은 텍스트 생성 모델이 아니라 TTS 전용 모델(tts-1, tts-1-hd)을 사용합니다. 여러 개의 미리 설정된 목소리(alloy, echo, fable, onyx, nova, shimmer) 중 하나를 선택할 수 있고, 여러 개의 음성 파일 포맷(MP3(기본값), Opus, AAC, FLAC, WAV, PCM) 중 하나를 선택할 수 있으며, 다양한 언어를 지원합니다. 그리고 긴 글의 경우 파일 생성이 완료되는 데에 시간이 꽤 오래 걸릴 수 있기 때문에, 사용자에게 빠르게 응답할 수 있도록 스트리밍 기능도 지원합니다.

from pathlib import Path
from openai import OpenAI

client = OpenAI()

speech_file_path = Path(__file__).parent / "6_text_to_speech_result.mp3"
with client.audio.speech.with_streaming_response.create(
  model="tts-1",
  voice="alloy",
  input="Today is a wonderful day to build something people love!",
) as response:
  response.stream_to_file(speech_file_path)

Speech to text#

음성 데이터를 입력하면, 그에 대한 텍스트 데이터를 생성하는 API를 제공하며, Text to speech와 마찬가지로 다양한 언어를 지원합니다. 이 기능은 전사 전용 모델(예: whisper-1)을 사용합니다.

from pathlib import Path
from openai import OpenAI

client = OpenAI()

audio_file = Path("6_text_to_speech_result.mp3")
transcription = client.audio.transcriptions.create(
  model="whisper-1",
  file=audio_file,
)

print(transcription.text)
[응답 예시]
Today is a wonderful day to build something people love.

그리고, 각 단어가 노출되는 시간 정보(Timestamp)를 같이 제공 받을 수 있어서, 음성 파일의 특정 위치에 대해 텍스트의 위치도 바로 찾을 수 있습니다. 또한 음성 파일과 함께 텍스트 프롬프트를 제공하여, 텍스트 변환시 더 완성도를 높일 수 있습니다. 동음이의어 등의 문제로 음성을 텍스트로 변환시 애매한 문제들이 많이 발생할 수 있기 때문인데요, 예를 들면, “달리"라는 음성에 대해 AI 모델(Whisper 모델) 입장에서는 “DALI”라고 해야할지 “DALL-E”라고 해야할지 명확하지 않겠죠. 그래서 “이 음성이 인공지능에 대한 발언이고, DALL-E, GPT 모델 등에 대해 이야기하고 있다"는 식의 텍스트 프롬프트를 제공하여 모델의 실수를 최소화 할 수 있다는 것입니다.

Moderation#

텍스트 데이터를 입력하여, 유해한 내용이 있는지를 검사하는 API를 제공합니다. 성적인 내용이 있는지, 혐오스러운 내용이 있는지 등에 대하여 카테고리를 구분하여 점수를 산출하고 그 결과 데이터를 전달해 줍니다.

from openai import OpenAI

client = OpenAI()

response = client.moderations.create(
  input="Hello world!!",
)
print(response)
[응답 예시]
ModerationCreateResponse(
  id="modr-...",
  model="...",
  results=[...],
)

Assistants#

위에서는 특정 기능들에 대한 단발성 요청을 처리하는 API를 알아봤는데요, Assistants API는 자체 앱에 ChatGPT와 같은 챗봇 기능을 구축할 수 있도록 좀더 고도화된 API입니다. 파일을 첨부하여 해당 파일을 분석하거나, 사용자의 질문에 대한 답을 해당 파일에서 찾는다거나, Python 코드를 실행하는 등의 기능을 수행할 수 있습니다. Assistants API를 사용하지 않고 위에서 설명한 API들만을 사용해서 챗봇 기능을 구현할 수도 있지만, 챗봇 구현을 위해 공통적으로 요구되는 부분들을 미리 구현하여 챗봇 구현을 더 쉽게 해주기 위해 만들어진 API라고 보시면 됩니다. 아래 코드는 간단한 형태의 챗봇을 구현한 Python 코드 예시입니다.

from openai import OpenAI
from typing_extensions import override
from openai import AssistantEventHandler

client = OpenAI()

assistant = client.beta.assistants.create(
  name="Math Tutor",
  instructions="You are a personal math tutor. Write and run code to answer math questions.",
  tools=[{"type": "code_interpreter"}],
  model="gpt-5-mini",
)

thread = client.beta.threads.create()

class EventHandler(AssistantEventHandler):
  @override
  def on_text_created(self, text) -> None:
    print("\nassistant > ", end="", flush=True)

  @override
  def on_text_delta(self, delta, snapshot):
    print(delta.value, end="", flush=True)

  def on_tool_call_created(self, tool_call):
    print(f"\nassistant > {tool_call.type}\n", flush=True)

  def on_tool_call_delta(self, delta, snapshot):
    if delta.type == "code_interpreter" and delta.code_interpreter:
      if delta.code_interpreter.input:
        print(delta.code_interpreter.input, end="", flush=True)
      if delta.code_interpreter.outputs:
        print("\n\noutput >", flush=True)
        for output in delta.code_interpreter.outputs:
          if output.type == "logs":
            print(f"\n{output.logs}", flush=True)

while True:
  user_input = input("\n\nuser > ")
  if user_input.lower() in ["exit", "quit"]:
    break

  client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content=user_input,
  )

  with client.beta.threads.runs.stream(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as Ted Kim. The user has a premium account.",
    event_handler=EventHandler(),
  ) as stream:
    stream.until_done()
[실행 로그 예시]

user > Who are you?

assistant > Hello, Ted Kim! I'm your AI assistant, here to help you with information, tasks, and any questions you might have. How can I assist you today?

user > I need to solve the equation `3x + 11 = 14`. Can you help me?

assistant > Sure, Ted Kim! Let's solve the equation (3x + 11 = 14).

1. **Subtract 11 from both sides:**
   3x + 11 - 11 = 14 - 11
   3x = 3

2. **Divide both sides by 3:**
   x = 3/3
   x = 1

So, the solution to the equation (3x + 11 = 14) is (x = 1).

user > Please run the python code. `for i in range(0,3): print('i * 2 = %d' % (i * 2))`

assistant > code_interpreter

output >
i * 2 = 0
i * 2 = 2
i * 2 = 4

user > exit

다른 AI 빅테크 기업들이 제공하는 API에 대하여#

구글(Gemini), Anthropic(Claude) 같은 다른 AI 빅테크 기업들이 제공하는 API들도, “텍스트 생성 / 이미지 / 음성 / 멀티모달 / 도구 호출”처럼 큰 틀에서는 대체로 비슷한 구성을 갖습니다. 이 장의 목적은 특정 벤더의 API 레퍼런스를 정리하는 것이 아니라, **API로 무엇을 할 수 있는지에 대한 ‘감’**을 잡는 것이기 때문에 다른 기업들의 API 소개는 여기서는 생략하겠습니다.

© 2026 Ted Kim. All Rights Reserved.