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

# 응답 생성

> OpenAI Responses API 형식을 사용하여 응답을 생성합니다

The Responses API는 OpenAI의 최신 상태 유지 대화 API입니다. TokenLab는 호환 모델에 대해 고급 선택 경로로 이 형식을 지원합니다; Responses 고유의 동작이 명시적으로 필요한 경우가 아니면 기본적으로 OpenAI 호환 경로인 `POST /v1/chat/completions`를 사용하세요.

## 요청 본문

<ParamField body="model" type="string" required>
  사용할 모델의 ID입니다. 사용 가능한 옵션은 [Models](https://tokenlab.sh/ko/models)을 참조하세요.
</ParamField>

<ParamField body="input" type="array" required>
  대화를 구성하는 입력 항목들의 목록입니다.

  각 항목은 다음 중 하나일 수 있습니다:

  * `message`: 역할과 내용을 가진 대화 메시지
  * `function_call`: 함수 호출 요청
  * `function_call_output`: 함수 호출의 출력

  멀티모달 입력의 경우, `message.content`는 일반 문자열이거나 콘텐츠 블록의 배열일 수 있습니다. GPT-5.4 계열과 같이 이미지 지원 모델의 경우, URL이나 Base64 문자열을 일반 텍스트에 직접 포함시키지 말고 이미지를 `input_image` 블록으로 전달하세요.

  예시 콘텐츠 블록:

  * `{ "type": "input_text", "text": "Describe this image" }`
  * `{ "type": "input_image", "image_url": "https://example.com/image.jpg" }`
  * `{ "type": "input_image", "image_url": "data:image/png;base64,..." }`
</ParamField>

<ParamField body="instructions" type="string">
  모델에 대한 시스템 지침(시스템 메시지와 동일).
</ParamField>

<ParamField body="max_output_tokens" type="integer">
  생성할 최대 토큰 수입니다.
</ParamField>

<ParamField body="temperature" type="number" default="1">
  샘플링 온도 (0에서 2 사이).
</ParamField>

<ParamField body="tools" type="array">
  모델이 호출할 수 있는 도구들의 목록입니다.

  기본 이미지 도구 모델을 사용하거나 명시적으로 `model: "gpt-image-2"`를 설정한 hosted `image_generation` 도구의 경우, GPT Image 2가 이미지 입력을 이미 high fidelity로 처리하므로 TokenLab는 지원되지 않는 `input_fidelity`를 upstream으로 전달하기 전에 제거합니다. 이 도구에는 `background: "transparent"`를 보내지 마세요. 출력 의미가 달라지므로 TokenLab는 이를 조용히 제거하지 않습니다.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  true이면 이벤트 스트림을 반환합니다.
</ParamField>

<ParamField body="previous_response_id" type="string">
  대화를 이어갈 이전 응답의 ID입니다.
</ParamField>

<ParamField body="store" type="boolean" default="true">
  나중에 검색하기 위해 응답을 저장할지 여부입니다.
</ParamField>

<ParamField body="metadata" type="object">
  추적 목적으로 응답에 첨부할 메타데이터입니다.
</ParamField>

<ParamField body="text" type="object">
  텍스트 생성 구성 옵션입니다. `text.format`의 동작은 선택한 모델 및 라우팅된 경로에 따라 달라지며, 모든 모델에서 동일하게 보장되지 않습니다.
</ParamField>

<ParamField body="parallel_tool_calls" type="boolean" default="true">
  여러 도구 호출을 병렬로 허용할지 여부입니다.
</ParamField>

<ParamField body="top_p" type="number">
  Nucleus 샘플링 매개변수 (0-1).
</ParamField>

<ParamField body="reasoning" type="object">
  GPT-5 계열과 같은 추론 지원 모델을 위한 추론 구성입니다.

  * `effort` (string): 추론 노력 수준 (`low`, `medium`, `high`)
</ParamField>

## 응답

<ResponseField name="id" type="string">
  응답의 고유 식별자입니다.
</ResponseField>

<ResponseField name="object" type="string">
  항상 `response`입니다.
</ResponseField>

<ResponseField name="created" type="integer">
  응답이 생성된 Unix 타임스탬프입니다.
</ResponseField>

<ResponseField name="output" type="array">
  모델이 생성한 출력 항목들의 목록입니다.
</ResponseField>

<ResponseField name="usage" type="object">
  토큰 사용 통계입니다.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.tokenlab.sh/v1/responses" \
    -H "Authorization: Bearer sk-your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "input": [
        {"type": "message", "role": "user", "content": "Hello!"}
      ],
      "max_output_tokens": 1000
    }'
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-your-api-key",
      base_url="https://api.tokenlab.sh/v1"
  )

  response = client.responses.create(
      model="gpt-4o",
      input=[
          {"type": "message", "role": "user", "content": "Hello!"}
      ],
      max_output_tokens=1000
  )

  print(response.output)
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    apiKey: 'sk-your-api-key',
    baseURL: 'https://api.tokenlab.sh/v1'
  });

  const response = await client.responses.create({
    model: 'gpt-4o',
    input: [
      { type: 'message', role: 'user', content: 'Hello!' }
    ],
    max_output_tokens: 1000
  });

  console.log(response.output);
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      payload := map[string]interface{}{
          "model": "gpt-4o",
          "input": []map[string]interface{}{
              {"type": "message", "role": "user", "content": "Hello!"},
          },
          "max_output_tokens": 1000,
      }
      body, _ := json.Marshal(payload)

      req, _ := http.NewRequest("POST", "https://api.tokenlab.sh/v1/responses", bytes.NewBuffer(body))
      req.Header.Set("Authorization", "Bearer sk-your-api-key")
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      var result map[string]interface{}
      json.NewDecoder(resp.Body).Decode(&result)
      fmt.Println(result["output"])
  }
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.tokenlab.sh/v1/responses');

  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Content-Type: application/json',
          'Authorization: Bearer sk-your-api-key'
      ],
      CURLOPT_POSTFIELDS => json_encode([
          'model' => 'gpt-4o',
          'input' => [
              ['type' => 'message', 'role' => 'user', 'content' => 'Hello!']
          ],
          'max_output_tokens' => 1000
      ])
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  print_r($data['output']);
  ```

  ## 비전 입력 예시

  이미지 지원 모델을 사용하려면 이미지를 `message.content` 안에 `input_image` 블록으로 넣으세요. `image_url` 값은 공개 URL이거나 Base64 데이터 URL일 수 있습니다.

  ```json theme={null}
  {
    "model": "gpt-5.4",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Please describe this image."
          },
          {
            "type": "input_image",
            "image_url": "https://example.com/demo.jpg"
          }
        ]
      }
    ]
  }
  ```

  ```json theme={null}
  {
    "model": "gpt-5.4",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Please describe this image."
          },
          {
            "type": "input_image",
            "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
          }
        ]
      }
    ]
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "resp_abc123",
    "object": "response",
    "created": 1706000000,
    "model": "gpt-4o",
    "output": [
      {
        "type": "message",
        "role": "assistant",
        "content": [
          {"type": "text", "text": "Hello! How can I help you today?"}
        ]
      }
    ],
    "usage": {
      "input_tokens": 10,
      "output_tokens": 12,
      "total_tokens": 22
    }
  }
  ```
</ResponseExample>