Responses

OpenAI Responses 형식으로 모델 응답을 생성합니다. 게이트웨이는 요청 본문과 스트림 이벤트를 변경 없이 모델 서버와 주고받으며 토큰을 계측합니다. 게이트웨이는 응답을 저장하지 않으므로 요청마다 전체 대화를 input에 담아 보내야 합니다.

Codex CLI는 이 엔드포인트로 Kiln과 통신합니다. provider 블록은 연동 페이지의 Codex CLI 항목에 있습니다.

POST/responses

URL

https://api.bricksum.com/v1/responses

요청

bash

curl https://api.bricksum.com/v1/responses \
  -H "Authorization: Bearer $KILN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-32b",
    "instructions": "Answer briefly.",
    "input": "Hello!"
  }'

python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.bricksum.com/v1",
    api_key=os.environ["KILN_API_KEY"],
)

resp = client.responses.create(
    model="qwen3-32b",
    instructions="Answer briefly.",
    input="Hello!",
)
print(resp.output_text)
print(resp.usage)

javascript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.bricksum.com/v1",
  apiKey: process.env.KILN_API_KEY,
});

const resp = await client.responses.create({
  model: "qwen3-32b",
  instructions: "Answer briefly.",
  input: "Hello!",
});
console.log(resp.output_text);
console.log(resp.usage);

응답

200 OK

{
  "id": "resp_...",
  "object": "response",
  "created_at": 1710000000,
  "model": "qwen3-32b",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Hello! How can I help?" }]
    }
  ],
  "usage": {
    "input_tokens": 9,
    "output_tokens": 12,
    "total_tokens": 21,
    "cost": 0.000001155
  }
}

200 OK · text/event-stream

event: response.created
data: {"type":"response.created","response":{"id":"resp_...","status":"in_progress","usage":null}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"Hello"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_...","status":"completed","usage":{"input_tokens":9,"output_tokens":12,"total_tokens":21}}}

400 Bad Request

{
  "error": {
    "message": "'previous_response_id' is not supported: responses are not stored on this gateway. Send the full conversation in 'input'.",
    "type": "invalid_request_error",
    "param": "previous_response_id",
    "code": "unsupported_parameter"
  }
}

이 예시의 토큰 수와 cost는 gpt-oss-120b에서 측정한 예시 값이며, qwen3-32b의 값이 아닙니다.

인증

게이트웨이가 처리하는 엔드포인트의 인증 방식은 모두 같으며, API 레퍼런스 페이지에서 설명합니다.

요청 본문

지원 상태

지원: 게이트웨이가 처리하거나, 공개된 실측에서 동작이 확인된 항목입니다.
전달만 함: 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
무시됨: 200으로 수락되지만 적용되지 않습니다. 응답의 나머지는 정상입니다.
미지원: 에러로 거부되거나, 설명에 적힌 모델에서 동작하지 않습니다.

공통 파라미터

아래 파라미터의 정의는 API 레퍼런스 페이지에 한 번만 정리했습니다. 여기에는 이 엔드포인트에서 다른 점만 적었습니다.

modelstring필수지원
공통 정의와 같습니다.
전체 정의 보기
streamboolean지원
true이면 응답이 server-sent events 스트림이 됩니다. 게이트웨이는 문자열 "true"와 숫자 1도 true로 읽으며, 전달하기 전에 이 필드를 boolean으로 다시 씁니다. Responses 요청에는 stream_options를 추가하지 않습니다.
기본값
false
전체 정의 보기
toolsarray전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
전체 정의 보기
tool_choicestring | object전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. qwen3-32b에서는 강제 툴 선택이 명확한 에러 없이 실패합니다(2026-09-26 실측). tool_choice를 "required"로 보내면 본문이 평문 "Internal Server Error"인 HTTP 500이 오고, 함수를 지정하면 arguments가 빈 200(finish_reason "stop")이 옵니다. 둘 다 4xx가 아니므로 재시도로 해결되지 않습니다. tool_choice는 "auto"만 보내세요.
전체 정의 보기

이 엔드포인트에만 있는 파라미터

inputstring | array필수지원
텍스트 프롬프트 또는 입력 항목 배열(메시지, 함수 호출, 함수 호출 결과)입니다. 매번 전체 대화를 보내세요. 게이트웨이는 값을 변경 없이 전달하며 검증하지 않습니다.
previous_response_idstring미지원
모델에 도달하기 전에 400(unsupported_parameter)으로 거부되며 과금되지 않습니다. 게이트웨이는 응답을 저장하지 않으므로 이어 갈 이전 응답이 없습니다. null 값은 수락됩니다.
storeboolean전달만 함
보낸 값 그대로 모델 서버로 전달됩니다. 값과 관계없이 Kiln을 통해 응답을 다시 조회할 수 없습니다. GET /responses/{id}, DELETE /responses/{id}, GET /responses/{id}/input_items는 404(not_found)로 응답합니다.
instructionsstring전달만 함
이 요청에 적용할 시스템 수준 지시문입니다. 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
max_output_tokensinteger전달만 함
생성할 최대 토큰 수입니다. 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. 모델 서버가 생성을 중간에 끝내면 response.incomplete로 종료되며, 사용한 토큰은 과금됩니다.
parallel_tool_callsboolean전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. qwen3-32b에서는 parallel_tool_calls 설정이 적용되지 않습니다. 이는 응답에 툴 호출이 하나만 온다는 뜻이 아닙니다. parallel_tool_calls: false를 보내도 한 응답에 툴 호출이 여러 건 올 수 있습니다. tool_calls의 모든 항목에 각각 tool 메시지로 답하세요.
reasoningobject전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
textobject전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
temperaturenumber전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
범위
0–2
top_pnumber전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
범위
0–1
truncationstring전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
includearray전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
metadataobject전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
userstring전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.

여기에 없는 OpenAI Responses 파라미터도 같은 방식으로 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않은 항목입니다.

응답 본문

필드	타입	설명
id	string	response의 ID입니다. 이 ID로 나중에 응답을 조회할 수는 없습니다.
object	string	"response"입니다.
status	string	"completed"이며, 생성이 중간에 끝나면 "incomplete"입니다.
output	array	모델 서버가 보낸 출력 항목입니다. output_text 파트를 가진 메시지와 함수 호출이 담깁니다. 변경 없이 전달됩니다.
usage.input_tokens	integer	입력 토큰 수입니다.
usage.output_tokens	integer	출력 토큰 수입니다.
usage.total_tokens	integer	입력과 출력 토큰의 합계입니다.
usage.input_tokens_details.cached_tokens	integer	프리픽스 캐시에서 처리된 입력 토큰 수입니다. 모델 서버가 보고할 때만 포함됩니다.
usage.cost	number	이 요청으로 크레딧에서 차감되는 금액(USD)입니다. 게이트웨이가 비스트리밍 응답에만 추가합니다.
X-Neocloud-Generation-Id	header	이 요청의 usage 이벤트 ID를 담은 응답 헤더입니다. 스트리밍 응답에도 포함됩니다. 로그와 함께 저장하세요.

스트림 이벤트

stream: true이면 모델 서버가 타입이 있는 이벤트를 보냅니다. event: 줄에 타입이 오고, 이어지는 data: 줄의 JSON에도 같은 값이 type으로 담깁니다. 게이트웨이는 모든 이벤트를 변경 없이 전달하고 마지막 이벤트에서 토큰 수를 읽습니다. 스트리밍 이벤트에서는 usage가 response 안에 있으므로 게이트웨이가 usage.cost를 추가하지 않습니다. 스트리밍 요청의 비용은 response.usage와 모델 단가로 계산하거나 콘솔 → 사용량에서 확인하세요.

keepalive 주석과 연결 끊김은 스트리밍 페이지에서 설명합니다.

이벤트	설명
response.created	모델 서버가 보낸 그대로 전달됩니다.
response.output_text.delta	모델 서버가 보낸 그대로 전달됩니다. delta에 새로 생성된 텍스트가 담깁니다.
response.completed	정상 종료된 생성의 마지막 이벤트입니다. response.usage에 과금되는 토큰 수가 담깁니다.
response.incomplete	max_output_tokens 등으로 중간에 끝난 생성의 마지막 이벤트입니다. response.usage에 토큰 수가 담기며 과금됩니다.
response.failed	생성이 실패했습니다. 이벤트에 usage가 있어도 요청은 과금되지 않습니다.
error	모델 서버가 보낸 에러 이벤트입니다. 요청은 과금되지 않습니다.

필드	타입	설명
type	string	이벤트 타입입니다. 위 값 중 하나입니다. 모델 서버가 다른 response.* 이벤트를 보낼 수 있으며, 변경 없이 전달됩니다.
delta	string	response.output_text.delta에서 새로 생성된 텍스트입니다.
response	object	response.created와 마지막 이벤트에 담기는 response 객체입니다. usage는 마지막 이벤트 전까지 null입니다.
response.usage	object	response.completed와 response.incomplete에 담깁니다. input_tokens, output_tokens, total_tokens를 포함합니다. 게이트웨이는 이 객체를 제거하지 않으며 cost 필드도 추가하지 않습니다.

에러

메시지 문구가 아니라 HTTP 상태와 error.code로 분기하세요. error.code 칸이 비어 있으면 본문에 code가 없다는 뜻입니다. 전체 상태 코드는 에러 페이지에 있습니다.

상태 · error.code	원인	조치
400unsupported_parameter	요청에 previous_response_id가 있습니다.	이 필드를 제거하고 전체 대화를 input에 담아 보내세요.
400	모델 서버가 요청을 거부했습니다. JSON 형식 에러, 잘못된 파라미터, 모델 페이지에 나오는 모델별 컨텍스트 길이를 넘는 컨텍스트가 원인입니다.	요청 본문을 수정하세요. 그대로 재시도하지 마세요.
404model_not_found	모델 ID가 카탈로그에 없습니다.	GET /models로 ID를 확인하세요.
404not_found	GET /responses/{id}, DELETE /responses/{id}, GET /responses/{id}/input_items 중 하나를 호출했습니다. 게이트웨이는 응답을 저장하지 않습니다.	대화는 클라이언트에 보관하고 input에 담아 보내세요.
429rate_limit_exceeded	조직에서 이미 8개의 요청이 처리 중입니다. 레이트 리밋 헤더는 포함되지 않습니다.	지수 백오프로 재시도하세요.
502	모델 백엔드가 에러를 반환했거나 연결할 수 없습니다. 본문은 일반 텍스트입니다.	지수 백오프로 재시도하세요.
503	서비스가 점검 중이거나 사용 가능한 모델 백엔드가 없습니다.	점검 중에는 Retry-After 시각까지 기다리세요. 그 밖에는 지수 백오프로 재시도하세요.

401, 402, 403, 429는 요청이 이 엔드포인트에 도달하기 전에 게이트웨이가 반환합니다. 이 에러들은 API 레퍼런스 페이지에 한 번만 정리했습니다.

제한

컨텍스트 길이, 요청 본문 크기, 타임아웃, 조직별 레이트 리밋도 여기에 그대로 적용되며, API 레퍼런스 페이지에 한 번만 정리했습니다.

429의 헤더와 재시도 방법은 레이트 리밋 페이지에 있습니다.