> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI 네이티브 형식(Responses)

## 소개

Responses API는 OpenAI의 차세대 대화 인터페이스로, GPT-5 시리즈 및 고급 기능을 위해 설계되었습니다. 기존 Chat Completions API와 비교하여 더 세밀한 추론 제어, 내장 도구 지원, 멀티모달 입력 기능을 제공합니다.

## 사용 사례

* **추론 집약적 작업**: GPT-5.5, GPT-5.4, GPT-5.4 Pro 등 심층 추론 모델 활용
* **웹 검색 요구사항**: 내장 Web Search Preview 도구
* **고급 도구 호출**: Function Call 및 Custom Tool Call 지원
* **다중 턴 대화 이어가기**: `previous_response_id`를 통한 대화 기록 관리

## 인증

<ParamField header="Authorization" type="string" required>
  Bearer Token, 예: `Bearer sk-xxxxxxxxxx`
</ParamField>

## 요청 매개변수

<ParamField body="model" type="string" required>
  모델 식별자, 지원 모델:

  * GPT-5 시리즈: `gpt-5.5`, `gpt-5.4`, `gpt-5.4-pro`, `gpt-5.4-mini`, `gpt-5.4-nano` 등
  * GPT-4 시리즈: `gpt-4o`, `gpt-4.1`, `gpt-4o-mini` 등
</ParamField>

<ParamField body="input" type="array" required>
  입력 메시지 목록, 여러 형식 지원:

  * **간소화 형식**: `[{"role": "user", "content": "text"}]` (Chat Completions와 유사)
  * **표준 형식**: `[{"type": "input_text", "text": "text"}]`
  * **멀티모달**: `input_image`, `input_file` 유형 지원
</ParamField>

<ParamField body="instructions" type="string">
  시스템 지시, Chat Completions의 system 메시지와 동일
</ParamField>

<ParamField body="max_output_tokens" type="number">
  최대 출력 토큰 수, 응답 길이 제어
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  스트리밍 출력 활성화 여부, SSE 형식 청크 데이터 반환
</ParamField>

<ParamField body="temperature" type="number" default="1.0">
  무작위성 제어, 0-2, 값이 높을수록 응답이 더 무작위적
</ParamField>

<ParamField body="top_p" type="number" default="0.98">
  Nucleus 샘플링 매개변수, 0-1, 생성 다양성 제어
</ParamField>

<ParamField body="reasoning" type="object">
  추론 모델 동작 제어 설정:

  * `effort`: 추론 강도, 옵션: `"none"`, `"low"`, `"medium"`, `"high"`
  * `summary`: 추론 요약, 옵션: `"auto"`, `"none"`, `"detailed"`
</ParamField>

<ParamField body="tools" type="array">
  도구 목록, 세 가지 유형 지원:

  * **내장 Web Search**: `{"type": "web_search_preview", "search_context_size": "medium"}`
  * **내장 File Search**: `{"type": "file_search"}`
  * **커스텀 함수**: 표준 OpenAI Function Call 형식
</ParamField>

<ParamField body="tool_choice" type="string|object" default="auto">
  도구 선택 전략:

  * `"auto"`: 모델이 도구 호출 여부를 자동 결정
  * `"none"`: 도구 호출 비활성화
  * `{"type": "function", "function": {"name": "function_name"}}`: 특정 함수 강제 호출
</ParamField>

<ParamField body="parallel_tool_calls" type="boolean" default="true">
  병렬 다중 도구 호출 허용 여부
</ParamField>

<ParamField body="max_tool_calls" type="number">
  최대 도구 호출 제한
</ParamField>

<ParamField body="previous_response_id" type="string">
  대화 이어가기를 위한 이전 응답 ID
</ParamField>

<ParamField body="truncation" type="string" default="disabled">
  잘림 전략: `"auto"` 또는 `"disabled"`
</ParamField>

<ParamField body="metadata" type="object">
  추적 및 디버깅용 요청 메타데이터
</ParamField>

<ParamField body="user" type="string">
  사용자 식별자
</ParamField>

## 기본 예시

<Tabs>
  <Tab title="Simple Conversation (Non-streaming)">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/responses" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gpt-5.2",
        "max_output_tokens": 2048,
        "input": [
          {"role": "system", "content": "You are a helpful assistant"},
          {"role": "user", "content": "Explain artificial intelligence briefly"}
        ]
      }'
    ```
  </Tab>

  <Tab title="Simple Conversation (Streaming)">
    ```bash theme={null}
    curl -N -X POST "https://api.gravitex.ai/v1/responses" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gpt-5.2",
        "stream": true,
        "max_output_tokens": 2048,
        "input": [
          {"role": "user", "content": "Explain artificial intelligence briefly"}
        ]
      }'
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        api_key="sk-xxxxxxxxxx",
        base_url="https://api.gravitex.ai/v1"
    )

    # Using Responses API
    response = client.responses.create(
        model="gpt-5.2",
        max_output_tokens=2048,
        input=[
            {"role": "user", "content": "Explain artificial intelligence briefly"}
        ]
    )

    print(response.output[0].content[0].text)
    ```
  </Tab>
</Tabs>

## 응답 형식

### 비스트리밍 응답

```json theme={null}
{
  "id": "resp_xxx",
  "object": "response",
  "created_at": 1768271369,
  "model": "gpt-5.2",
  "status": "completed",
  "output": [
    {
      "id": "msg_xxx",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Artificial Intelligence (AI) is a branch of computer science...",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 25,
    "output_tokens": 150,
    "total_tokens": 175,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens_details": {
      "reasoning_tokens": 50
    }
  }
}
```

### 스트리밍 응답(SSE 이벤트)

스트리밍 응답은 Server-Sent Events 형식을 사용하며 다음 이벤트 유형이 있습니다:

| Event Type                   | Description         |
| ---------------------------- | ------------------- |
| `response.created`           | 응답 생성됨              |
| `response.in_progress`       | 응답 진행 중             |
| `response.output_item.added` | 출력 항목 추가됨(도구 호출 시작) |
| `response.output_text.delta` | 텍스트 델타              |
| `response.output_text.done`  | 텍스트 완료              |
| `response.output_item.done`  | 출력 항목 완료            |
| `response.completed`         | 응답 완료               |

**SSE 출력 예시**:

```
event: response.created
data: {"type":"response.created","response":{"id":"resp_xxx","status":"in_progress"}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"Artificial","sequence_number":1}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":" Intelligence","sequence_number":2}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_xxx","status":"completed","usage":{...}}}
```

## 고급 기능

### 1. Web Search

내장 Web Search 도구를 활성화하여 실시간 인터넷 정보를 검색합니다.

<Tabs>
  <Tab title="Basic Example">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/responses" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gpt-5.2",
        "stream": true,
        "max_output_tokens": 2048,
        "input": [
          {"role": "user", "content": "What are today'\''s news headlines?"}
        ],
        "tools": [
          {
            "type": "web_search_preview",
            "search_context_size": "medium"
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="Advanced Configuration">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/responses" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gpt-5.2",
        "stream": true,
        "input": [
          {"role": "user", "content": "What'\''s the weather in New York today?"}
        ],
        "tools": [
          {
            "type": "web_search_preview",
            "search_context_size": "high",
            "user_location": {
              "type": "approximate",
              "country": "US",
              "region": "NY",
              "city": "New York",
              "timezone": "America/New_York"
            }
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

**Web Search 매개변수**:

* **`search_context_size`**: 검색 컨텍스트 크기
  * `"low"`: 낮은 컨텍스트, 빠르지만 결과 적음
  * `"medium"`: 중간 컨텍스트(기본값)
  * `"high"`: 높은 컨텍스트, 검색 결과 많지만 느림

* **`user_location`** (선택): 사용자 위치 정보
  * `country`: 국가 코드(예: "US", "CN")
  * `region`: 주/도
  * `city`: 도시
  * `timezone`: 시간대

### 2. 추론 제어

추론 모델의 추론 깊이와 출력 형식을 제어합니다.

<Tabs>
  <Tab title="Auto Reasoning Summary">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/responses" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gpt-5.5",
        "stream": true,
        "reasoning": {
          "summary": "auto"
        },
        "max_output_tokens": 8192,
        "input": [
          {"role": "user", "content": "What is the formula for Tower of Hanoi?"}
        ]
      }'
    ```
  </Tab>

  <Tab title="Detailed Reasoning">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/responses" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gpt-5.5",
        "stream": true,
        "reasoning": {
          "effort": "high",
          "summary": "detailed"
        },
        "max_output_tokens": 16384,
        "input": [
          {"role": "user", "content": "Prove Fermat'\''s Last Theorem"}
        ]
      }'
    ```
  </Tab>
</Tabs>

**추론 매개변수**:

* **`effort`**: 추론 강도 수준
  * `"none"`: 추론 없음
  * `"low"`: 가벼운 추론
  * `"medium"`: 중간 추론(기본값)
  * `"high"`: 심층 추론

* **`summary`**: 추론 요약
  * `"none"`: 추론 요약 없음
  * `"auto"`: 요약 출력 여부 자동 결정
  * `"detailed"`: 상세 추론 과정 출력

### 3. 커스텀 Function Calling

표준 OpenAI Function Calling 형식을 지원합니다.

```bash theme={null}
curl -X POST "https://api.gravitex.ai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.2",
    "stream": true,
    "input": [
      {"role": "user", "content": "What'\''s the weather in Shanghai?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get weather information for a city",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "description": "City name"
              }
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'
```

**Function Call 응답 형식**:

```json theme={null}
{
  "output": [
    {
      "id": "call_xxx",
      "type": "function_call",
      "status": "completed",
      "name": "get_weather",
      "call_id": "call_xxx",
      "arguments": "{\"city\":\"Shanghai\"}"
    }
  ]
}
```

### 4. 멀티모달 입력

텍스트, 이미지, 파일 등 다양한 입력 유형을 지원합니다.

<Tabs>
  <Tab title="Image Input">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/responses" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gpt-5.2",
        "input": [
          {
            "type": "input_text",
            "text": "What'\''s in this image?"
          },
          {
            "type": "input_image",
            "image_url": "https://example.com/image.jpg",
            "detail": "high"
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="File Input">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/responses" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gpt-5.2",
        "input": [
          {
            "type": "input_text",
            "text": "Please analyze the content of this PDF document"
          },
          {
            "type": "input_file",
            "file_url": "https://example.com/document.pdf"
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

### 5. 대화 이어가기

`previous_response_id`를 사용하여 이전 대화를 이어갑니다.

```bash theme={null}
# First conversation
curl -X POST "https://api.gravitex.ai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.2",
    "input": [
      {"role": "user", "content": "What is quantum computing?"}
    ]
  }'

# Response contains id: "resp_abc123"

# Second conversation (continuation)
curl -X POST "https://api.gravitex.ai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.2",
    "previous_response_id": "resp_abc123",
    "input": [
      {"role": "user", "content": "What are its application scenarios?"}
    ]
  }'
```

## 중요 참고 사항

<Warning>
  * **모델 호환성**: 모든 모델이 Responses API의 모든 기능을 지원하는 것은 아닙니다
  * **Web Search**: GPT-4o, GPT-4.1, GPT-5 및 o 시리즈 모델만 지원합니다
  * **추론**: o 시리즈 및 일부 GPT-5 모델만 `reasoning` 매개변수를 지원합니다
  * **콘텐츠 난독화**: 스트리밍 응답 델타에 `obfuscation` 필드(콘텐츠 보호)가 포함될 수 있으며, 전체 평문은 `response.output_text.done` 이벤트에서 확인할 수 있습니다
</Warning>

<Tip>
  * 표준 Chat Completions 형식이 필요하면 `openai/` 모델 접두사와 함께 `/v1/chat/completions` 엔드포인트를 사용하세요
  * 시스템이 클라이언트 호환성을 위해 형식을 자동 변환합니다
</Tip>

## 비교: Responses API vs Chat Completions API

| Feature       | Responses API            | Chat Completions API |
| ------------- | ------------------------ | -------------------- |
| 추론 모델 지원      | ✅ 전체 지원                  | ⚠️ 제한적 지원            |
| 내장 Web Search | ✅ 네이티브 지원                | ❌ 미지원                |
| 추론 제어         | ✅ 세밀한 제어                 | ❌ 미지원                |
| 대화 이어가기       | ✅ `previous_response_id` | ✅ messages를 통해       |
| 스트리밍 출력       | ✅ SSE 형식                 | ✅ SSE 형식             |
| 클라이언트 호환성     | ⚠️ 적응 필요                 | ✅ 표준 형식              |
| 사용 사례         | 추론, 검색, 고급 기능            | 일반 대화                |

## 관련 리소스

<CardGroup cols={2}>
  <Card title="Chat Completions API" icon="comments" href="/ko/api-reference/endpoint/chat-openai">
    표준 대화 인터페이스 문서
  </Card>

  <Card title="Model List" icon="list" href="/ko/api-reference/models">
    지원되는 모든 모델 보기
  </Card>

  <Card title="FAQ" icon="question-circle" href="/ko/faq/chat-completions">
    Responses API FAQ
  </Card>
</CardGroup>