Responses API

Responses API

Responses API는 OpenAI의 Responses API와 완전 호환되는 인터페이스예요. 텍스트와 이미지 입력을 모두 받아 텍스트 출력을 만들고, 함수 호출로 외부 시스템을 연결할 수 있는 더 진보된 응답 생성 방식이에요. 현재 베타 단계예요. 상태를 유지하는 대화와 내장 도구(코드 실행, 웹 검색)를 함께 쓰는 에이전트형 애플리케이션을 만들 때 유용해요.

출처: GroqCloud — Responses API

OpenAI 클라이언트로 시작하기

Groq의 Responses API는 OpenAI 클라이언트 라이브러리와 호환되므로, API 키와 base URL만 바꾸면 바로 쓸 수 있어요.

import openai

client = openai.OpenAI(
    api_key="your-groq-api-key",
    base_url="https://api.groq.com/openai/v1"
)

response = client.responses.create(
    model="llama-3.3-70b-versatile",
    input="Tell me a fun fact about the moon in one sentence.",
)

print(response.output_text)

base_url은 https://api.groq.com/openai/v1로 지정하면 돼요. API 키는 콘솔의 키 페이지에서 발급받아요.

멀티턴 대화

Groq의 Responses API는 아직 상태를 유지하는 대화(stateful conversations)를 지원하지 않아요. 대화 기록을 직접 관리해서 매 요청마다 전달해야 해요.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("GROQ_API_KEY"),
    base_url="https://api.groq.com/openai/v1",
)

messages = []

def main():
    while True:
        user_input = input("You: ")
        if user_input.lower().strip() == "stop":
            print("Goodbye!")
            break
        messages.append({"role": "user", "content": user_input})
        response = client.responses.create(
            model="openai/gpt-oss-20b",
            input=messages,
        )
        assistant_message = response.output_text
        messages.extend(response.output)
        print(f"Assistant: {assistant_message}")

if __name__ == "__main__":
    main()

모델의 응답(response.output)을 다시 input에 이어 붙이는 방식으로 대화 맥락을 유지해요.

이미지 입력

Responses API는 비전 지원 모델과 함께라면 이미지 입력도 받아요. 입력 콘텐츠 배열에 input_image 타입 항목으로 이미지 URL을 넘기면 돼요.

response = client.responses.create(
    model="qwen/qwen3.6-27b",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What are the main colors in this image?"},
                {"type": "input_image", "detail": "auto", "image_url": "https://example.com/og_cloud.png"},
            ]
        }
    ],
)
print(response.output_text)

내장 도구

Responses API는 모델의 일반적인 도구 사용 외에도 여러 내장 도구를 지원해요. 다만 모든 모델이 이 내장 도구를 지원하는 건 아니에요.

  • 코드 실행 — 모델이 Python 코드를 직접 작성·실행해 계산·데이터 분석·문제 해결을 할 수 있어요. tool_choice="required"와 함께 tools에 "type": "code_interpreter"를 넘기면 돼요.
  • 웹 검색 — 실시간 웹 콘텐츠에 접근해 최신 정보를 얻을 수 있어요. tools에 "type": "browser_search"를 넘기면 돼요.
response = client.responses.create(
    model="openai/gpt-oss-20b",
    input="What is 1312 X 3333? Output only the final answer.",
    tool_choice="required",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
)
print(response.output_text)

구조화된 출력

text.format에 json_schema 타입을 지정하면 모델 응답이 특정 JSON 스키마를 따르게 할 수 있어요. 구조화된 데이터 추출, 일관된 응답 형식, 다운스트림 시스템 연동에 유용해요. 스키마 정의는 Pydantic·Zod 같은 라이브러리로 하면 타입 안전성이 더 좋아져요.

response = client.responses.parse(
    model="openai/gpt-oss-20b",
    input=[{"role": "system", "content": "Create a recipe."},
           {"role": "user", "content": "Healthy chocolate coconut cake"}],
    text_format=Recipe,
)
recipe = response.output_parsed

추론 (Reasoning)

reasoning 파라미터로 모델이 응답 전에 내부 추론 사슬(chain of thought)을 만들게 할 수 있어요. 복잡한 문제 해결, 멀티스텝 에이전트 워크플로 계획, 과학적 분석에 유용해요. 추론 궤적은 응답의 output 배열에서 "type": "reasoning" 항목으로 확인할 수 있어요.

response = client.responses.create(
    model="openai/gpt-oss-20b",
    input="How are AI models trained? Be brief.",
    reasoning={"effort": "low"},
)
print(response.output_text)

Model Context Protocol (MCP)

Responses API는 MCP(Model Context Protocol)도 지원해요. 이는 AI 애플리케이션이 데이터베이스·API·도구 같은 외부 시스템에 연결되게 하는 오픈소스 표준이에요. GitHub를 통한 코드베이스 접근, 자연어 DB 쿼리, 실시간 웹 검색, Slack·Notion·Google Calendar 같은 API 기반 서비스 연결이 모두 가능해요. tools에 "type": "mcp" 항목으로 서버를 지정하면 돼요.

미지원 기능

Groq의 Responses API는 OpenAI와 대부분 호환되지만, 다음 기능은 아직 지원하지 않아요.

  • previous_response_id
  • store
  • truncation
  • include
  • safety_identifier
  • prompt_cache_key
  • prompt (재사용 프롬프트)

상세 사용량 지표

요청별 상세 지표(정확한 추론 시간 등)를 받으려면 헤더를 설정하면 돼요. 응답 본문의 metadata 필드에 다음 키가 포함돼요.

  • completion_time: 출력 생성에 걸린 초
  • prompt_time: 입력 프롬프트 처리에 걸린 초
  • queue_time: 처리 전 대기열에 있던 초
  • total_time: 요청 처리 총 초

usage 필드와 metadata 필드를 조합하면 초당 출력 토큰을 계산할 수 있어요.

더 알아보기