이 API는 OpenAI와 호환되지만 파라미터, 기능, 동작에 중요한 차이가 있습니다. 요청은 이 페이지에 명시된 파라미터만 처리합니다. 그 밖의 OpenAI 파라미터는 허용되지만 무시됩니다.
주요 차이점:
지원하지 않는 파라미터: previous_response_id, conversation, background, store: true와 텍스트가 아닌 콘텐츠 파트(input_image, input_file)는 거부됩니다. 이 API는 상태를 저장하지 않으며 텍스트만 지원합니다. 대화 가이드를 참고하세요.
from openai import OpenAIclient = OpenAI( api_key="UPSTAGE_API_KEY", base_url="https://api.upstage.ai/v1",)response = client.responses.create( model="solar-pro4", input="Hi, how are you?",)print(response.output_text)
오류는 OpenAI 오류 응답 형식을 사용합니다. param은 실패와 관련된 필드를 나타내고 code는 오류를 분류합니다. 둘 다 null일 수 있습니다. 일부 검증 오류는 max_tokens나 response_format처럼 대응하는 Chat Completions 필드 이름을 사용합니다.
{ "error": { "message": "the 'previous_response_id' parameter is not supported: this API is stateless and does not store responses. Send the full conversation history in 'input' instead", "type": "invalid_request_error", "param": "previous_response_id", "code": "invalid_request_body" }}
400 파라미터가 유효하지 않거나, 컨텍스트 길이를 초과했거나, 상태를 저장하지 않는 방식과 호환되지 않는 파라미터(previous_response_id, conversation, background, store: true)가 전달되었습니다. 오류에 따라 code는 invalid_request_body, context_length_exceeded, 다른 오류 코드 또는 null일 수 있습니다.
401 API 키가 없거나 유효하지 않습니다.
404model_not_found 모델이 존재하지 않거나 Responses API를 지원하지 않습니다.
모델에 보낼 대화입니다. 문자열은 하나의 user 메시지이며, 배열은 유형이 있는 항목으로 전체 대화를 전달합니다. 이 API는 상태를 저장하지 않으므로 새 메시지 앞에 이전 응답의 output 항목을 다시 보내세요(대화 가이드 참고). 텍스트가 아닌 콘텐츠 파트는 거부됩니다.
instructionsstring
대화 앞에 삽입되는 시스템 프롬프트입니다. 첫 번째 system 메시지와 같으며 요청 간에 유지되지 않습니다.
textobject
출력 형식 설정입니다. format으로 일반 텍스트 또는 구조화된 출력을 선택합니다. 적용된 값을 응답에 그대로 반환하므로 요청이 반영되었는지 확인할 수 있습니다.
{"type": "text"} — 기본값인 자유 형식 텍스트입니다.
{"type": "json_object"} — JSON 모드입니다. 대화에 JSON을 언급해야 하며, 그렇지 않으면 요청이 거부됩니다. 유효한 JSON을 보장하지만 특정 구조를 보장하지는 않습니다.
{"type": "json_schema", "name": ..., "schema": ...} — 제공한 JSON Schema를 따르는 구조화된 출력입니다. OpenAI의 엄격한 스키마와 호환되도록 모든 객체의 additionalProperties를 false로 설정하고 모든 속성을 required에 나열하는 것을 권장합니다. 값이 선택 사항이면 해당 타입에 null을 추가하세요. 자세한 내용은 구조화된 출력 가이드를 참고하세요.
Chat Completions와 달리 스키마 필드는 json_schema 키 아래에 중첩되지 않고 type 옆에 같은 수준으로 배치됩니다. verbosity는 허용되지만 무시됩니다.
format일반 텍스트 | JSON 모드 | 구조화된 출력
type
필수
string
값: "text"
toolsarray<object>
모델이 호출할 수 있는 도구 목록입니다. 함수 도구만 지원합니다.
Chat Completions와 달리 도구는 같은 수준으로 선언됩니다. name, description, parameters는 function 키 아래에 중첩되지 않고 type 옆에 배치됩니다. 자세한 내용은 도구 호출 가이드를 참고하세요.
tool_choicestring | object
모델이 어떤 도구를 호출할지 또는 도구를 호출하지 않을지 제어합니다.
none이면 도구를 호출하지 않고 메시지를 생성합니다.
auto이면 메시지 생성과 하나 이상의 도구 호출 중에서 선택합니다.
required이면 하나 이상의 도구를 반드시 호출합니다.
{"type": "function", "name": "my_function"}은 해당 도구 호출을 강제합니다. 같은 수준으로 배치된 구조에 주의하세요. Chat Completions는 이름을 function 키 아래에 중첩합니다.
도구가 없으면 기본값은 none, 도구가 있으면 auto입니다. function 이외의 객체 형식(allowed_tools, mcp, custom 등)은 거부됩니다.
parallel_tool_callsboolean
도구 사용 중 병렬 함수 호출을 허용할지 여부입니다. 활성화하면 모델이 한 응답에서 여러 도구 호출을 생성하여 독립적인 호출을 동시에 실행할 수 있습니다. 이 설정이 둘 이상의 도구 호출을 보장하지는 않습니다. output의 모든 function_call 항목을 처리하세요.
기본값: true
reasoningobject
모델이 응답 전에 수행하는 추론의 정도를 제어합니다. Solar Pro 4와 Solar Mini 4는 모든 effort 수준을 허용하며, none과 minimal은 추론을 끕니다.
추론이 실행되면 추론 텍스트가 output의 첫 번째 reasoning 항목으로 반환되고, 추론 토큰은 usage.output_tokens_details.reasoning_tokens에 집계됩니다. max_output_tokens에는 추론 토큰도 포함되므로 작은 토큰 한도는 추론만으로 모두 소진될 수 있습니다. 자세한 내용은 추론 가이드를 참고하세요.
summary는 허용되지만 무시됩니다. Solar는 요약 대신 원본 추론 텍스트를 반환합니다.
max_output_tokensinteger
이 응답에서 생성할 토큰 수의 상한입니다. 추론 토큰을 포함합니다. 최댓값은 131,072 토큰입니다. 입력 토큰 수와 이 값의 합은 모델의 컨텍스트 길이를 초과할 수 없습니다. 한도에 도달하면 응답의 status는 incomplete입니다.
최댓값: 131072
temperaturenumber
샘플링 온도를 설정하는 선택 파라미터입니다. 값은 0~2 사이여야 합니다. 0.8처럼 높은 값은 출력을 더 무작위로 만들고, 0.2처럼 낮은 값은 더 집중되고 결정적인 출력을 만듭니다.
기본값은 1.0입니다.
기본값: 1최솟값: 0최댓값: 2형식: "float"
top_pnumber
뉴클리어스 샘플링을 사용하는 선택 파라미터입니다. 누적 확률 질량이 top_p인 토큰을 고려합니다. 예를 들어 0.1이면 확률 상위 10%를 구성하는 토큰을 고려합니다.
기본값: 1최솟값: 0최댓값: 1형식: "float"
streamboolean
event: 이름과 JSON data: 페이로드가 있는 Server-Sent Events로 응답을 스트리밍할지 여부입니다. 스트림은 response.completed, response.incomplete 또는 response.failed로 끝나며, [DONE] 표식은 보내지 않습니다.
기본값: false
prompt_cache_keystring
프롬프트 식별 및 캐시에 사용할 고유 키를 지정하는 선택적 파라미터입니다. 캐시 활용도를 높이려면 대화 컨텍스트마다 다른 키를 사용하세요.
기본값: null
frequency_penaltynumber
같은 토큰이 이미 나타난 횟수에 비례하여 반복될 확률을 줄입니다. 범위는 -2.0~2.0입니다.
표준 OpenAI Responses 파라미터가 아닙니다. Python SDK는 extra_body={"frequency_penalty": 0.8}로 전달합니다. Node.js SDK와 curl은 최상위 파라미터로 보냅니다. presence_penalty는 허용되지만 효과가 없습니다.