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

# Create a response

OpenAI Responses API 형식을 사용하여 스트리밍 또는 비스트리밍 응답을 생성합니다.

## 인증

<ParamField header="Authorization" type="string" required>
  Bearer 토큰. API 키를 Authorization 헤더의 Bearer 토큰으로 사용하세요.

  Format: `Bearer <SUNRA_KEY>`
</ParamField>

## 요청

이 엔드포인트는 JSON 객체를 받습니다.

<ParamField body="model" type="string" required>
  응답 생성에 사용할 모델 ID. 사용 가능한 모델은 [sunra.ai/models](https://sunra.ai/models)에서 확인하세요.
</ParamField>

<ParamField body="input" type="string | object[]">
  응답 요청의 입력. 문자열 또는 입력 항목의 배열을 지정할 수 있습니다.

  <Expandable title="속성(배열인 경우)">
    <ParamField body="type" type="string">
      입력 항목의 유형. 지원되는 값: `message`, `item_reference`.
    </ParamField>

    <ParamField body="role" type="string">
      메시지 작성자의 역할. 지원되는 값: `user`, `assistant`, `system`.
    </ParamField>

    <ParamField body="content" type="string | object[]">
      입력 메시지의 내용. 문자열 또는 콘텐츠 파트 배열을 지정할 수 있습니다.
    </ParamField>

    <ParamField body="id" type="string">
      항목의 ID. 대화 기록의 `assistant` 메시지에 필수입니다.
    </ParamField>

    <ParamField body="status" type="string">
      항목의 상태. 대화 기록의 `assistant` 메시지에 필수입니다.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="instructions" type="string | null">
  모델의 컨텍스트에서 첫 번째 항목으로 시스템(또는 개발자) 메시지를 삽입합니다. `input`과 함께 사용하면 입력의 시작 부분에 지침이 삽입됩니다.
</ParamField>

<ParamField body="stream" type="boolean" default={false}>
  `true`로 설정하면 서버 전송 이벤트(SSE)를 사용하여 응답이 스트리밍됩니다.
</ParamField>

<ParamField body="max_output_tokens" type="integer">
  가시적 출력 토큰과 추론 토큰을 포함한 출력 토큰 수의 상한.
</ParamField>

<ParamField body="temperature" type="number" default={1}>
  0에서 2 사이의 샘플링 온도. 값이 높을수록 무작위성이 증가합니다.
</ParamField>

<ParamField body="top_p" type="number" default={1}>
  핵 샘플링 매개변수. temperature 샘플링의 대안입니다.
</ParamField>

<ParamField body="frequency_penalty" type="number" default={0}>
  -2.0에서 2.0 사이의 숫자. 양수 값은 텍스트에서의 기존 빈도를 기반으로 새 토큰에 페널티를 부과합니다.
</ParamField>

<ParamField body="presence_penalty" type="number" default={0}>
  -2.0에서 2.0 사이의 숫자. 양수 값은 텍스트에 이미 나타났는지 여부를 기반으로 새 토큰에 페널티를 부과합니다.
</ParamField>

<ParamField body="tools" type="object[]">
  모델이 호출할 수 있는 도구 배열.

  <Expandable title="속성">
    <ParamField body="type" type="string" required>
      도구의 유형. 지원되는 값: `function`, `web_search_preview`.
    </ParamField>

    <ParamField body="name" type="string">
      함수의 이름. type이 `function`인 경우 필수입니다.
    </ParamField>

    <ParamField body="description" type="string">
      함수에 대한 설명.
    </ParamField>

    <ParamField body="parameters" type="object">
      함수 매개변수를 정의하는 JSON Schema 객체.
    </ParamField>

    <ParamField body="strict" type="boolean" default={false}>
      엄격한 스키마 준수가 활성화되어 있는지 여부.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tool_choice" type="string | object">
  도구 선택 동작을 제어합니다. 지원되는 문자열 값: `none`, `auto`, `required`. 특정 함수를 지정할 수도 있습니다.
</ParamField>

<ParamField body="parallel_tool_calls" type="boolean" default={true}>
  모델이 도구 호출을 병렬로 실행할 수 있도록 허용할지 여부.
</ParamField>

<ParamField body="text" type="object">
  텍스트 응답 형식 구성.

  <Expandable title="속성">
    <ParamField body="format" type="object">
      텍스트 형식 구성.

      <Expandable title="속성">
        <ParamField body="type" type="string" required>
          형식 유형. 지원되는 값: `text`, `json_object`, `json_schema`.
        </ParamField>

        <ParamField body="name" type="string">
          응답 형식의 이름. type이 `json_schema`인 경우 필수입니다.
        </ParamField>

        <ParamField body="schema" type="object">
          JSON 스키마. type이 `json_schema`인 경우 필수입니다.
        </ParamField>

        <ParamField body="strict" type="boolean">
          엄격한 스키마 준수가 활성화되어 있는지 여부.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="reasoning" type="object">
  추론 출력 구성.

  <Expandable title="속성">
    <ParamField body="effort" type="string">
      추론에 대한 노력을 제한합니다. 지원되는 값: `low`, `medium`, `high`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="store" type="boolean" default={true}>
  생성된 응답을 나중에 검색할 수 있도록 저장할지 여부.
</ParamField>

<ParamField body="metadata" type="object">
  응답에 첨부할 수 있는 16개의 키-값 쌍 세트. 키는 최대 64자의 문자열이며, 값은 최대 512자의 문자열입니다.
</ParamField>

<ParamField body="user" type="string">
  최종 사용자를 나타내는 고유 식별자. 최대 128자.
</ParamField>

## 응답

성공 응답 객체.

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

<ResponseField name="object" type="string">
  객체 유형. 항상 `response`.
</ResponseField>

<ResponseField name="created_at" type="number">
  응답이 생성된 시점의 Unix 타임스탬프(초 단위).
</ResponseField>

<ResponseField name="status" type="string">
  응답의 상태. 가능한 값: `completed`, `failed`, `in_progress`, `cancelled`.
</ResponseField>

<ResponseField name="model" type="string">
  응답 생성에 사용된 모델.
</ResponseField>

<ResponseField name="output" type="object[]">
  모델이 생성한 콘텐츠 항목 배열.

  <Expandable title="속성">
    <ResponseField name="type" type="string">
      출력 항목의 유형. 예: `message`.
    </ResponseField>

    <ResponseField name="id" type="string">
      출력 항목의 고유 ID.
    </ResponseField>

    <ResponseField name="role" type="string">
      역할. 항상 `assistant`.
    </ResponseField>

    <ResponseField name="status" type="string">
      메시지의 상태. 예: `completed`.
    </ResponseField>

    <ResponseField name="content" type="object[]">
      출력 메시지의 내용.

      <Expandable title="속성">
        <ResponseField name="type" type="string">
          콘텐츠 유형. 예: `output_text`.
        </ResponseField>

        <ResponseField name="text" type="string">
          생성된 텍스트 콘텐츠.
        </ResponseField>

        <ResponseField name="annotations" type="object[]">
          콘텐츠에 대한 주석(예: 웹 검색의 인용).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  응답의 토큰 사용량 통계.

  <Expandable title="속성">
    <ResponseField name="input_tokens" type="integer">
      입력 토큰 수.
    </ResponseField>

    <ResponseField name="output_tokens" type="integer">
      출력 토큰 수.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      총 토큰 수.
    </ResponseField>

    <ResponseField name="input_tokens_details" type="object">
      입력 토큰 세부 내역.

      <Expandable title="속성">
        <ResponseField name="cached_tokens" type="integer">
          캐시된 토큰 수.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="output_tokens_details" type="object">
      출력 토큰 세부 내역.

      <Expandable title="속성">
        <ResponseField name="reasoning_tokens" type="integer">
          추론 토큰 수.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="temperature" type="number">
  사용된 샘플링 온도.
</ResponseField>

<ResponseField name="top_p" type="number">
  사용된 핵 샘플링 값.
</ResponseField>

<ResponseField name="max_output_tokens" type="integer | null">
  사용된 최대 출력 토큰 설정.
</ResponseField>

<ResponseField name="error" type="object | null">
  생성이 실패한 경우의 오류 객체.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api-llm.sunra.ai/v1/responses \
    -H "Authorization: Bearer <SUNRA_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-4o",
      "input": [
        {
          "type": "message",
          "role": "user",
          "content": "Hello, how are you?"
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api-llm.sunra.ai/v1/responses",
      headers={
          "Authorization": "Bearer <SUNRA_KEY>",
          "Content-Type": "application/json"
      },
      json={
          "model": "openai/gpt-4o",
          "input": [
              {
                  "type": "message",
                  "role": "user",
                  "content": "Hello, how are you?"
              }
          ]
      }
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api-llm.sunra.ai/v1/responses", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <SUNRA_KEY>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "openai/gpt-4o",
      input: [
        {
          type: "message",
          role: "user",
          content: "Hello, how are you?"
        }
      ]
    })
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "resp-abc123",
    "object": "response",
    "created_at": 1704067200,
    "status": "completed",
    "model": "openai/gpt-4o",
    "output": [
      {
        "type": "message",
        "id": "msg_abc123",
        "role": "assistant",
        "status": "completed",
        "content": [
          {
            "type": "output_text",
            "text": "Hello! I'm doing well, thank you for asking. How can I help you today?",
            "annotations": []
          }
        ]
      }
    ],
    "temperature": 1.0,
    "top_p": 1.0,
    "max_output_tokens": null,
    "usage": {
      "input_tokens": 15,
      "output_tokens": 18,
      "total_tokens": 33,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens_details": {
        "reasoning_tokens": 0
      }
    },
    "error": null
  }
  ```
</ResponseExample>