Responses API (Codex 호환)
Codex(OpenAI Responses API 호환)
OpenAI Responses API 와이어 포맷과 호환되는 엔드포인트입니다. Codex(wire_api=responses)가 보내는 input·instructions·tools(flat) 형태를 그대로 받아, 카탈로그의 어떤 텍스트 모델로도 호출할 수 있습니다. 무상태(stateless) 엔드포인트로 previous_response_id·store는 지원하지 않습니다.
엔드포인트
/api/v1/responsesAuthorization: Bearer YOUR_API_KEY 헤더로 인증합니다. x-api-key 헤더도 허용됩니다.
Codex 연결 설정
Codex가 빌링AI Responses API를 사용하도록 사용자 전역 설정 파일인 ~/.codex/config.toml에 아래 custom provider를 등록하세요. 설정의 모델 ID는 빌링AI 모델 카탈로그에 있는 텍스트 모델로 바꿀 수 있습니다.
# ~/.codex/config.toml model = "gpt-5-4" model_provider = "billingai" [model_providers.billingai] name = "빌링AI" base_url = "https://billing-ai.doublezero.kr/api/v1" env_key = "BILLINGAI_API_KEY" wire_api = "responses"
대시보드에서 발급한 API 키를 환경변수로 지정하고, 같은 셸에서 Codex를 실행합니다.
export BILLINGAI_API_KEY="sk-proj-..." codex
자주 겪는 오류: 401 invalid_api_key
- •오류에 표시된 요청 주소가
api.openai.com이면 빌링AI provider가 적용되지 않은 상태입니다. Codex는 프로젝트의.codex/config.toml에 있는 model_provider와 model_providers 설정을 사용하지 않습니다. 설정이 사용자 전역~/.codex/config.toml에 있는지 확인하고, 위 예시의 model_provider와 base_url을 다시 확인하세요. - •요청 주소가
billing-ai.doublezero.kr이면 라우팅은 적용된 상태입니다. Codex를 실행한 환경에BILLINGAI_API_KEY가 설정되어 있는지, 해당 키가 대시보드에서 발급한 유효한 빌링AI 키인지 확인하세요.
요청 파라미터
| 이름 | 타입 | 필수 | 설명 | 기본값 |
|---|---|---|---|---|
model* | string | * 필수 | 사용할 모델 ID. 카탈로그의 모든 텍스트 모델을 사용할 수 있습니다. | - |
input* | string | array | * 필수 | 입력. 문자열 또는 입력 아이템 배열(message · function_call · function_call_output)입니다. | - |
instructions | string | 선택 | 시스템 지시문. 내부적으로 system 메시지로 매핑됩니다. | - |
stream | boolean | 선택 | SSE 스트리밍 여부. true로 설정하면 이벤트 단위로 실시간 전송합니다. | false |
max_output_tokens | number | 선택 | 최대 출력 토큰 수(1~200000). 내부적으로 max_tokens로 매핑됩니다. | - |
temperature | number | 선택 | 생성 온도(0~2). 높을수록 다양한 응답을 생성합니다. | - |
top_p | number | 선택 | 누적 확률 샘플링. | - |
tools | array | 선택 | function 도구 목록. flat 형태 {type:"function", name, description, parameters}로 전달합니다. | - |
tool_choice | string | object | 선택 | 도구 선택 방식. "auto" · "none" · "required" 또는 {type:"function", name}. autononerequired | - |
parallel_tool_calls | boolean | 선택 | 병렬 도구 호출 허용 여부. | - |
text | object | 선택 | 출력 형식. text.format.type은 text · json_object · json_schema를 지원합니다. | - |
user | string | 선택 | 최종 사용자 식별자. | - |
metadata | object | 선택 | 부가 메타데이터(16KB 이하). | - |
응답 필드
| 이름 | 타입 | 필수 | 설명 | 기본값 |
|---|---|---|---|---|
id* | string | * 필수 | 응답 ID(resp_...). | - |
object* | string | * 필수 | "response" 고정값. | - |
created_at* | number | * 필수 | 생성 타임스탬프(Unix epoch). | - |
status* | string | * 필수 | "completed" 고정값. | - |
model* | string | * 필수 | 요청한 모델 ID를 그대로 반환합니다. | - |
output* | array | * 필수 | 출력 아이템 배열. message(output_text) 및 function_call 아이템을 포함합니다. | - |
usage* | object | * 필수 | 토큰 사용량. input_tokens, output_tokens, total_tokens(+input_tokens_details.cached_tokens). | - |
parallel_tool_calls* | boolean | * 필수 | 병렬 도구 호출 설정값. | - |
코드 예제
curl -X POST https://billing-ai.doublezero.kr/api/v1/responses \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5-6-sol",
"instructions": "당신은 도움이 되는 코딩 어시스턴트입니다.",
"input": "피보나치 수열을 구하는 함수를 작성해 주세요."
}'응답 예시
{
"id": "resp_abc123",
"object": "response",
"created_at": 1711234567,
"status": "completed",
"model": "gpt-5-6-sol",
"output": [
{
"type": "message",
"id": "msg_0",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "다음은 피보나치 수열을 구하는 함수입니다...",
"annotations": []
}
]
}
],
"usage": {
"input_tokens": 24,
"output_tokens": 88,
"total_tokens": 112
},
"parallel_tool_calls": true
}스트리밍
stream: true로 설정하면 text/event-stream(SSE)으로 응답합니다. 이벤트 순서는 response.created → response.in_progress → output_item.added/content_part.added/output_text.delta → response.completed 이며, 마지막에 data: [DONE]로 종료됩니다.
참고사항
- •무상태 엔드포인트입니다. previous_response_id 또는 store: true를 보내면 400(stateless_endpoint)으로 거부됩니다.
- •tools에는 function 도구만 사용할 수 있습니다. 내장 도구(web_search 등)는 무시됩니다.
- •오디오·파일 입력은 지원하지 않습니다. 텍스트와 이미지(input_image의 image_url)만 입력할 수 있습니다.