Skip to main content
POST

인증

string
필수
Bearer 토큰 인증입니다. 형식: Authorization: Bearer <api-key>API Key 받기:API Key 관리 페이지에 접속하여 API Key를 받으세요.
string
대체 인증 방법으로, Authorization과 둘 중 하나를 선택합니다. 형식: x-api-key: <api-key>

요청 본문 파라미터

string
필수
사용할 모델 이름. 예: gpt-4o, gpt-5.4, gpt-5.5 등.GET /api/v1/models 를 통해 전체 모델 목록을 조회할 수 있습니다.
array
필수
입력 내용 목록입력 배열로, 각 입력 항목은 rolecontent 두 필드를 포함합니다. 다중 대화 및 다중 모달 콘텐츠(텍스트+이미지)를 지원합니다.
string
시스템 프롬프트(System Prompt). 모델의 행동 규칙, 역할 정체성 또는 컨텍스트 배경을 설정하는 데 사용됩니다.메시지 배열 내 role: "system" 메시지와 동등합니다.
boolean
기본값:"true"
스트리밍 출력 활성화 여부.
  • true(기본): SSE 이벤트 스트림 방식으로 토큰별 반환, 실시간 표시 적합
  • false: 완전한 응답 대기 후 일괄 반환, 일괄 처리 적합
integer
생성할 응답의 최대 토큰 수. 제한을 초과하면 응답 status"incomplete" 로, incomplete_details.reason"max_output_tokens" 로 설정됩니다.
number
샘플링 온도, 범위는 0 ~ 2. 값이 높을수록 출력이 더 무작위적이며, 값이 낮을수록 출력을 더 결정론적으로 만듭니다. temperaturetop_p 를 동시에 수정하는 것은 권장하지 않습니다.
number
핵심 샘플링 확률, 범위는 0 ~ 1. 모델은 누적 확률이 top_p 에 도달한 토큰들만 샘플링합니다.
array
모델이 호출할 수 있는 도구 목록. 현재는 type: "function" 유형만 지원하며, web_search, file_search, computer_use 등 내장 도구는 지원하지 않습니다.
string | object
기본값:"auto"
도구 호출 전략:
  • "auto": 모델이 자동으로 도구 호출 여부 결정
  • "none": 도구 호출 금지
  • "required": 최소 하나 이상의 도구 호출 강제
  • { "type": "function", "name": "function_name" }: 지정된 도구 호출 강제
boolean
기본값:"true"
모델이 여러 도구를 병렬로 호출할지 여부. tools 제공 시에만 유효합니다.
object
출력 형식 제어.
object
추론 모드 설정(gpt-5.2 이상 등 추론 지원 모델에 적용).

응답 필드

string
응답 고유 식별자, 형식: resp_ + 24자리 임의 문자열
string
고정값 "response"
number
응답 생성 시간, Unix 타임스탬프(초, 밀리초 정밀도 포함)
string
응답 상태:
  • "completed": 정상 완료
  • "incomplete": max_output_tokens로 인한 조기 종료
  • "in_progress": 스트리밍 출력 진행 중(스트리밍 이벤트에서만 나타남)
  • "failed": 생성 실패
string
실제 사용된 모델 이름
string
플랫폼 확장 필드. 이번 호출의 청구 작업 ID로, 결산 및 소모 조회에 사용 가능.주의:
  • 비스트리밍: task_id가 응답 JSON 최상위에 직접 위치
  • 스트리밍: task_idresponse.created(첫 이벤트) 및 response.completed(마지막 이벤트)의 response 객체 안에 중첩, 원본 SSE 이벤트를 파싱해 획득해야 하며, OpenAI SDK의 스트리밍 인터페이스는 이 필드를 자동으로 노출하지 않음
array
출력 내용 배열로, 텍스트 메시지와 도구 호출 두 가지 유형을 포함할 수 있음.
string
편리 필드, output[0].content[0].text와 동일(순수 텍스트 시나리오). 도구 호출 시에는 빈 문자열.
object
토큰 사용량 통계.
object | null
status"incomplete"일 때 null이 아님.

스트리밍 응답 이벤트

stream: true인 경우, API는 text/event-stream 형식으로 SSE 이벤트 스트림을 반환합니다. 각 이벤트 형식은 다음과 같습니다:
모든 이벤트 payload는 클라이언트가 순서대로 이벤트를 처리할 수 있도록 sequence_number 필드(0부터 증가)를 포함합니다.
task_id 얻기: 스트리밍 모드에서 과금 작업 ID를 얻으려면 첫 번째 response.created 이벤트를 수신하고 event.response.task_id를 읽으세요.

이벤트 시퀀스 (텍스트 응답)

이벤트 시퀀스 (도구 호출)

이벤트 예시


사용 예제

기본 텍스트 대화

이미지 이해

도구 호출

구조화된 출력 (JSON Schema)

추론 모드

다회차 대화

previous_response_id는 현재 작동하지 않으며, 히스토리 메시지를 input에 직접 연결해야 합니다:

주의사항

  1. 기본값은 스트리밍stream 매개변수의 기본값은 true입니다. 비스트리밍 응답이 필요할 경우 명시적으로 "stream": false를 전달해야 합니다.
  2. 포인트 부족:잔액이 부족할 경우 HTTP 402가 반환되며, 충전 후 다시 시도하시기 바랍니다.
  3. text.format 지원 제한:현재 기본 공급자는 구조화된 출력 지원이 제한적입니다 — json_object 모드에서는 모델이 여전히 순수 JSON 대신 Markdown 코드 블록을 출력할 수 있으며, json_schema 모드에서는 스키마 제약이 준수되지 않을 수 있습니다. 구조화된 출력을 원할 경우 instructions 또는 input에 원하는 형식을 명확하게 기술하시기 바랍니다.
  4. 툴 매개변수parameters 필드는 유효한 JSON Schema이어야 하며, required 배열이 필수 매개변수를 결정합니다.

오류 코드 설명