OpenAI의 차세대 「단일 턴 입력 + 스트리밍 출력」 API로, Codex CLI와 최신 OpenAI SDK에서 사용합니다.
/v1/chat/completions 또는 /v1/messages만 쓴다면 이 API를 알 필요는 없습니다.
엔드포인트
POST https://relay.4aicode.com/v1/responses
chat/completions와의 차이
| 항목 | /v1/chat/completions | /v1/responses |
|---|---|---|
| 입력 | messages 배열 | input 배열(이벤트 스트림에 가까움) |
| 도구 호출 | tool_calls / tool_messages | 내장 function_call / function_call_output 이벤트 |
| 스트리밍 이벤트 | data: {...} 청크 | response.output_text.delta 등 명명된 이벤트 |
| 용도 | 채팅 애플리케이션 | Codex CLI 및 agent 프레임워크 |
요청
POST /v1/responses HTTP/1.1
Host: relay.4aicode.com
Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx
content-type: application/json
{
"model": "gpt-5.6-terra",
"input": [
{ "role": "user", "content": "Refactor main.go" }
],
"stream": true
}
지원 모델
/v1/chat/completions와 동일: gpt-6-astra, gpt-6-sol, gpt-6.1-sol, gpt-6.1-terra, gpt-6-luna, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex. 업스트림에서 미지원이면 릴레이가 명시적 400을 반환합니다.
스트리밍 응답
event: response.created
data: {"response": {"id": "resp_...", ...}}
event: response.output_text.delta
data: {"delta": "package main\n"}
event: response.output_text.done
data: {}
event: response.completed
data: {"response": {...}, "usage": {...}}
비스트리밍 요청은 단일 { response, usage } 객체를 반환합니다.
Function Calling / Tools
tools 필드는 공식 API와 동일하게 전달됩니다.
event: response.output_item.added
data: {"item": {"type": "function_call", "name": "...", "arguments": "..."}}
공식 프로토콜에 따라 tool 결과는 function_call_output로 보냅니다.
오류
| HTTP | 의미 |
|---|---|
| 400 | 잘못된 input 형식 / model이 허용 목록에 없음 |
| 401 | 잘못된 토큰 |
| 403 | 팀 정지 |
| 429 | 속도 제한 또는 할당량 초과 |
| 502 | 업스트림 OpenAI 불안정 |
| 503 | 업스트림 서비스 일시 불가; 서비스 쿨다운 및 재시도 참고 |
사용 시점
- ✅ Codex CLI 사용(공식적으로 이 API 사용)
- ✅ 최신 OpenAI Agents SDK 사용
- ❌ 챗봇 구축 →
/v1/chat/completions사용