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

# Responses API

> OpenAI의 Responses API 형식으로 Venice를 사용하세요: 요청이 처리되는 방식, OpenAI 모델과 기타 모델에서 지원되는 기능, 스트리밍, 그리고 베타 endpoint의 현재 제한 사항을 알아봅니다.

`POST /responses`는 [OpenAI의 Responses API 형식](https://platform.openai.com/docs/api-reference/responses)으로 된 요청을 받아 `reasoning`, `message`, `function_call` 같은 타입이 지정된 출력 항목을 반환합니다. 모든 Venice 텍스트 모델에서 동작하며, API 키 또는 [x402 지갑 인증](/ko/guides/integrations/x402-venice-api)을 사용할 수 있습니다.

<Warning>
  **이 endpoint는 베타 버전**이며 모든 API 사용자가 사용할 수 있습니다. OpenAI 모델은 네이티브로 처리되므로 OpenAI 자체 Responses API와 동일하게 동작합니다. 그 외의 모든 모델은 일부 차이가 있는 변환 계층을 거칩니다. 이 endpoint를 기반으로 개발하기 전에 [요청이 처리되는 방식](#요청이-처리되는-방식)과 [제한 사항](#제한-사항)을 읽어 보세요.
</Warning>

## 사용 시점

클라이언트가 이미 Responses 형식을 사용하고 있다면 `/responses`를 사용하세요. 예를 들어 OpenAI의 `responses.create`를 기반으로 만든 코딩 에이전트와 SDK가 이에 해당합니다. Venice를 통해 OpenAI 모델에서 Codex 스타일 에이전트를 실행하는 가장 좋은 방법입니다.

OpenAI가 아닌 모델의 경우 여전히 [`/chat/completions`](/ko/api-reference/endpoint/chat/completions)가 가장 완전한 옵션입니다. 이 endpoint는 모든 모델에서 구조화된 출력, 파일 입력, E2EE 모델 및 모든 [`venice_parameters`](/ko/api-reference/endpoint/chat/completions#body-venice-parameters) 옵션을 지원합니다.

## 빠른 시작

<CodeGroup>
  ```bash cURL theme={"system"}
  curl https://api.venice.ai/api/v1/responses \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "venice-uncensored",
      "input": "Explain why the sky is blue in one sentence.",
      "venice_parameters": { "include_venice_system_prompt": false }
    }'
  ```

  ```python Python theme={"system"}
  from openai import OpenAI

  client = OpenAI(base_url="https://api.venice.ai/api/v1", api_key="YOUR_VENICE_API_KEY")

  response = client.responses.create(
      model="venice-uncensored",
      input="Explain why the sky is blue in one sentence.",
      extra_body={"venice_parameters": {"include_venice_system_prompt": False}},
  )
  print(response.output_text)
  ```

  ```javascript JavaScript theme={"system"}
  import OpenAI from "openai";

  const client = new OpenAI({ baseURL: "https://api.venice.ai/api/v1", apiKey: process.env.VENICE_API_KEY });

  const response = await client.responses.create({
    model: "venice-uncensored",
    input: "Explain why the sky is blue in one sentence.",
    venice_parameters: { include_venice_system_prompt: false },
  });
  console.log(response.output_text);
  ```
</CodeGroup>

응답에는 타입이 지정된 항목으로 구성된 `output` 배열과 `usage` 객체가 포함됩니다:

```json theme={"system"}
{
  "id": "resp_...",
  "object": "response",
  "model": "venice-uncensored-1-2",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "id": "msg_...",
      "role": "assistant",
      "status": "completed",
      "content": [{ "type": "output_text", "text": "Sunlight scatters off air molecules...", "annotations": [] }]
    }
  ],
  "usage": { "input_tokens": 18, "output_tokens": 21, "total_tokens": 39 }
}
```

## 요청이 처리되는 방식

Venice는 각 요청을 두 가지 모드 중 하나로 처리합니다.

* **네이티브.** OpenAI 모델에 대한 요청은 변환 없이 OpenAI의 Responses API로 전달됩니다. `openai-gpt-oss-120b`를 제외한 모든 `openai-*` 모델이 여기에 해당합니다. 응답 항목, ID, 추론, 스트림 이벤트는 OpenAI가 반환하는 그대로 돌아옵니다.
* **변환.** 그 외의 모든 모델과 `openai-gpt-oss-120b`는 변환 계층을 거칩니다. Venice가 요청을 [Chat Completions](/ko/api-reference/endpoint/chat/completions) 요청으로 변환하여 실행한 뒤 결과를 다시 변환합니다. Chat Completions 형식으로 표현할 수 없는 항목은 무시되거나 거부됩니다. [제한 사항](#제한-사항)을 참조하세요.

Venice 전용 기능을 사용하는 OpenAI 모델 요청은 해당 기능이 계속 동작하도록 변환 모드로 처리됩니다. 여기에는 Venice 웹 검색(`web_search` 도구, `web_search: true` 또는 `venice_parameters.enable_web_search`), `x_search`, `venice_parameters.character_slug`, `venice_parameters.enable_web_scraping`이 포함됩니다. [네이티브 모드](#네이티브-모드)에 나열된, 네이티브 모드에서 처리할 수 없는 필드가 포함된 요청도 같은 방식으로 대체됩니다.

헤더로 모드를 제어하고 확인할 수 있습니다:

| Header | Direction | Values |
| - | - | - |
| `x-venice-responses-mode` | 요청 | `auto`(기본값)는 위에서 설명한 대로 모드를 선택합니다. `native`는 네이티브 모드를 요구하며, 요청을 네이티브로 처리할 수 없으면 **400**을 반환합니다. `compat`는 항상 변환 모드를 사용합니다. |
| `x-venice-responses-lane` | 응답 | `native` 또는 `compat`: 요청을 처리한 모드입니다. |
| `x-venice-responses-compat-reason` | 응답 | OpenAI 모델 요청이 변환 모드로 대체된 경우, 그 원인이 된 필드입니다. 예: `tools[0]` 또는 `previous_response_id`. |

## 대화는 상태를 저장하지 않음

Venice는 어느 모드에서도 응답을 저장하지 않습니다. 매 요청마다 이전 `output` 항목과 도구 결과를 덧붙여 전체 대화를 `input`에 담아 보내세요.

```python theme={"system"}
history = [{"role": "user", "content": "What is the weather in Paris? Use the tool."}]
tools = [{
    "type": "function",
    "name": "get_weather",
    "description": "Get the current weather for a city",
    "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
}]

first = client.responses.create(model="venice-uncensored", input=history, tools=tools)
call = next(item for item in first.output if item.type == "function_call")

history += first.output
history.append({"type": "function_call_output", "call_id": call.call_id, "output": '{"temp_c": 18}'})

second = client.responses.create(model="venice-uncensored", input=history, tools=tools)
print(second.output_text)
```

`store`는 항상 `false`로 처리됩니다. 아무것도 저장되지 않으므로 `previous_response_id`와 `conversation`은 확인할 수 없습니다. 기본 `auto` 모드에서는 이러한 요청이 변환 모드로 처리되며, 해당 필드는 무시됩니다. `x-venice-responses-mode: native`를 사용하면 **400**을 반환합니다.

## 네이티브 모드

네이티브 모드는 OpenAI 자체 endpoint가 지원하는 Responses 기능을 지원하며, 다음을 포함합니다:

* `instructions`는 작성한 그대로 적용됩니다.
* `text.format`을 사용한 구조화된 출력. OpenAI는 스키마를 엄격하게 검증하므로 잘못된 스키마는 **400**을 반환합니다. 예를 들어 `strict: true`에는 `additionalProperties: false`가 필요하고, `json_object`에는 입력 어딘가에 "json"이라는 단어가 있어야 합니다.
* OpenAI의 Responses 형태 `{"type": "function", "name": "..."}`로 된 함수 도구와 `tool_choice`, 그리고 병렬 도구 호출.
* 클라이언트에서 실행되는 도구: `custom`(자유 형식 입력), `namespace`, `tool_search`, `apply_patch`, 로컬 환경을 사용하는 `shell` 및 `local_shell`, 그리고 컴퓨터 사용.
* 추론 요약(기본적으로 켜져 있음). 추론 모델은 추론 항목에 항상 `encrypted_content`를 반환합니다. 모델의 추론 컨텍스트를 유지하려면 다음 턴에서 이 항목들을 `input`에 담아 다시 보내세요.
* `prompt_cache_key`를 사용한 프롬프트 캐싱. Venice는 키를 사용자 계정 범위로 지정하므로 다른 사용자와 캐시를 공유하지 않으며, 응답에는 원래의 키를 반환합니다.
* `detail: "original"`을 포함한 이미지 입력, 그리고 인라인 `file_data`를 사용하는 `input_file`.
* Pro 모델(`*-pro`)은 OpenAI의 Pro 추론 모드를 자동으로 실행합니다.

네이티브 모드에서는 Venice 시스템 프롬프트가 기본적으로 **꺼져** 있으므로 `instructions`가 변경 없이 적용됩니다. 추가하려면 `venice_parameters.include_venice_system_prompt: true`를 설정하세요.

다음 기능은 서버 측 저장소나 제공업체가 호스팅하는 리소스가 필요하므로 네이티브로 사용할 수 없습니다:

| Not available natively | Use instead |
| - | - |
| `previous_response_id`, `conversation`, 저장된 `prompt` 템플릿, `background`, `item_reference` | 전체 대화를 `input`에 담아 보내고, `background` 대신 `stream: true`를 사용하세요. |
| `file_id` 참조 및 원격 `input_file.file_url` | `file_data`로 파일을 인라인으로 보내세요. |
| 호스팅 도구: `code_interpreter`, `file_search`, `image_generation`, 원격 `mcp`, 로컬 환경이 없는 `shell` | 애플리케이션에서 도구를 실행하고 `function`, `custom` 또는 로컬 `shell` 도구로 노출하세요. 이미지에는 [`/image/generate`](/ko/api-reference/endpoint/image/generate)를 사용하세요. |
| `auto` 또는 `default` 이외의 `service_tier` | 생략하세요. |

이러한 제한은 대화 후반에 `additional_tools` 또는 `tool_search_output` 항목을 통해 로드되는 도구에도 적용됩니다. 그곳에 선언된 Venice 검색 도구 역시 요청을 변환 모드로 라우팅합니다.

인식되지 않는 요청 필드도 같은 방식으로 처리됩니다. `auto`에서는 요청이 변환 모드로 처리되고, `native`에서는 **400**을 반환합니다.

## 스트리밍

서버 전송 이벤트(SSE)를 받으려면 `stream: true`를 설정하세요. 두 모드 모두 `data: [DONE]`으로 스트림을 종료합니다.

네이티브 모드에서는 이벤트가 OpenAI의 것과 정확히 동일하며, 추론 요약을 위한 `response.reasoning_summary_text.delta`와 도구 인수를 위한 `response.function_call_arguments.delta`를 포함합니다.

변환 모드에서의 이벤트는 `response.created`, `response.output_item.added`, `response.content_part.added`, `response.output_text.delta`, `response.function_call_arguments.delta`, `response.content_part.done`, `response.output_item.done`이며, 마지막으로 `response.completed`, `response.incomplete` 또는 `response.failed`가 옵니다. 두 가지 이벤트는 OpenAI와 다릅니다:

* 추론 텍스트는 OpenAI의 추론 요약 이벤트가 아닌 `response.reasoning.delta`로 스트리밍됩니다.
* 웹 검색이 실행되면 답변이 스트리밍되기 전에 `response.web_search.done` 이벤트가 검색 결과를 전달합니다.

## 변환 모드 파라미터

| Parameter | Notes |
| - | - |
| `model`, `input` | `input`은 문자열 또는 메시지와 항목의 배열일 수 있습니다. 메시지 콘텐츠는 `input_text`와 `input_image`를 지원합니다. |
| `stream` | 위에서 설명한 서버 전송 이벤트입니다. |
| `max_output_tokens`, `temperature`, `top_p` | Chat Completions에 매핑됩니다. OpenAI 추론 모델은 샘플링 파라미터를 무시합니다. |
| `reasoning.effort`, `reasoning.enabled` | `enabled: false`는 이를 허용하는 모델에서 사고(thinking)를 비활성화합니다. |
| `include: ["reasoning.encrypted_content"]` | 추론 항목에 암호화된 추론을 반환합니다. |
| `tools` | 평면적인 Responses 형태 또는 중첩된 Chat 형태의 함수 도구, `custom` 도구, `namespace` 도구, 그리고 `defer_loading` 도구와 함께 클라이언트에서 실행되는 `tool_search`. `web_search`는 Venice 웹 검색을 실행하고, `x_search`는 [지원되는 모델](/ko/models/text)에서 xAI 네이티브 검색을 실행합니다. |
| `tool_choice` | `auto`, `none`, `required`, OpenAI의 Responses 형태 `{"type": "function", "name": "..."}`(또는 선택적 `namespace`가 포함된 `"type": "custom"`), 또는 Chat 형태 `{"type": "function", "function": {"name": "..."}}`. |
| `web_search` | `true`로 설정하면 `web_search` 도구와 마찬가지로 Venice 웹 검색이 켜집니다. |
| `anon_user_id` | 자체 사용자를 위한 선택적 최종 사용자 식별자입니다. |
| `venice_parameters` | `character_slug`, `enable_web_search`, `enable_web_scraping`, `enable_web_citations`, `include_venice_system_prompt`, `include_search_results_in_stream`, `enable_e2ee`. |

웹 검색은 `/chat/completions`와 마찬가지로 검색 증강으로 과금됩니다.

미리 고려해야 할 변환 모드의 몇 가지 동작:

* `instructions`는 시스템 메시지로 적용됩니다.
* 커스텀 도구는 원시 `input`이 담긴 `custom_tool_call` 항목을 반환합니다. 모델이 잘못된 형식의 커스텀 도구 인수를 반환하거나 요청에 선언되지 않은 도구를 호출하면, 해당 호출은 원래 인수를 가진 일반 `function_call`로 반환되므로 클라이언트가 도구 오류를 보고하고 계속 진행할 수 있습니다.
* 커스텀 도구의 입력이 스트리밍되는 동안, 해당 호출 항목과 이후 항목은 입력이 완료된 후에야 도착할 수 있습니다. 대기하는 동안 스트림은 SSE keep-alive 주석을 보냅니다.
* 이미지 `detail: "original"`은 이를 지원하지 않는 제공업체에는 `high`로 전송됩니다.

## 제한 사항

다음 차이점은 변환 모드, 즉 OpenAI가 아닌 모든 모델, `openai-gpt-oss-120b`, 그리고 Venice 전용 기능을 사용하는 OpenAI 모델 요청에 적용됩니다. 별도로 명시되지 않은 한 요청은 성공하며 해당 필드는 무시됩니다.

| Area | Current behavior | What to do instead |
| - | - | - |
| Venice 시스템 프롬프트 | `/chat/completions` 및 네이티브 모드와 달리 기본적으로 추가됩니다. 모든 요청에 입력 토큰을 추가하며, 모델이 프롬프트의 언어로 답변하도록 지시합니다. | `venice_parameters.include_venice_system_prompt`를 `false`로 설정하세요. |
| 저장된 상태 | `previous_response_id`, `store`, `conversation`은 무시됩니다. | 전체 대화를 `input`에 담아 보내세요. |
| 구조화된 출력 | `text.format`은 무시됩니다. | [`/chat/completions`](/ko/guides/features/structured-responses)에서 `response_format`을 사용하세요. |
| 추론 재전송 | `input`에 담아 다시 보낸 추론 항목은 모델에 전달되지 않습니다. `reasoning.summary`는 무시됩니다. | 별도 조치가 필요 없습니다. 모델은 매 턴마다 새로 추론합니다. |
| 호스팅 도구 | `code_interpreter`, `file_search`, `computer_use_preview` 및 기타 제공업체 호스팅 도구는 무시됩니다. 호스팅 `tool_search`는 **400**을 반환합니다. | 해당 도구를 애플리케이션에서 실행하고 `function` 도구로 노출하며, 클라이언트에서 실행되는 `tool_search`를 사용하세요. |
| 파일 입력 | `input_file` 콘텐츠 파트는 **400**을 반환합니다. | [`/chat/completions`](/ko/guides/features/file-inputs)를 통해 파일을 보내세요. |
| E2EE 모델 | `venice_parameters.enable_e2ee`가 `false`가 아니면 **400**을 반환합니다. | E2EE 헤더와 함께 [`/chat/completions`](/ko/guides/features/tee-e2ee-models)를 사용하세요. |

## 관련 문서

* [`POST /responses` API 레퍼런스](/ko/api-reference/endpoint/responses/create)
* [함수 호출](/ko/guides/features/function-calling)
* [추론 모델](/ko/guides/features/reasoning-models)
* [OpenAI 마이그레이션 가이드](/ko/guides/getting-started/openai-migration)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.