NNexithDocs
상태대시보드 ↗
개요 및 빠른 시작모델 카탈로그가이드API 레퍼런스연동OAuth2 / OIDC

Responses

POST /v1/responses · OpenAI Responses 호환(요청 형태에 따라 분기)

/v1/responses는 주로 Codex처럼 Responses API만 사용하는 클라이언트를 위한 것입니다. 게이트웨이는 요청 형태로 출처를 판단합니다:

  • Codex 형태(instructions / tools / reasoning / input 메시지 배열 포함) → 내부적으로 Chat Completions로 번역해 실행한 뒤, 결과를 다시 object: "response" 형태로 번역합니다.
  • 일반 텍스트 형태(input이 문자열) → OpenAI chat.completion 형태로 반환합니다 (/v1/chat/completions와 동일). Codex가 아닌 호출자가 재사용하기 쉽습니다.

요청#

POST /v1/responses
Authorization: Bearer nx-...
Content-Type: application/json

Body(공통)#

필드 유형 필수 설명
model string — 기본값 nexith(nexith-core로 매핑)
input string | array ✅ 문자열, 또는 Responses input item 배열
stream bool — 기본값 false
max_output_tokens integer — 추론 + 본문의 총 예산; 너무 작으면 본문이 비게 됩니다
previous_messages array — 선택적 다중 턴 기록(Nexith 확장, Chat 형태)

Codex 형태의 추가 필드#

필드 설명
instructions 최상위 지시문으로, system 메시지로 번역됩니다
tools Responses 도구 정의({type:"function", name, parameters}), Chat tools로 번역됩니다
tool_choice auto / none / required / 지정 함수
reasoning {effort: ...}, reasoning_effort로 번역됩니다

input items#

[
  {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "hello"}]},
  {"type": "message", "role": "user", "content": [{"type": "input_image", "image_url": "https://…"}]},
  {"type": "function_call_output", "call_id": "call_1", "output": "42"}
]

input_text, input_image, message, function_call, function_call_output을 지원합니다.


응답(Codex 형태)#

{
  "id": "resp_nx0000000000000001",
  "object": "response",
  "created_at": 1795055384,
  "model": "nexith-core",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "id": "msg_nx0000000000000000",
      "role": "assistant",
      "status": "completed",
      "content": [{"type": "output_text", "text": "ok", "annotations": []}]
    }
  ],
  "usage": {"input_tokens": 324, "output_tokens": 32, "total_tokens": 356}
}
  • status: completed / incomplete(예: max_output_tokens 도달).
  • 도구 호출 출력은 function_call item입니다.

응답(일반 텍스트 형태)#

Chat Completions와 완전히 동일합니다(object: "chat.completion").


스트리밍#

stream=true이면 SSE를 반환합니다. Codex 형태의 스트림은 Responses 이벤트를 출력하고, 텍스트 형태의 스트림은 chat.completion.chunk입니다. 프레임 세부 사항은 스트리밍 프로토콜을 참고하세요.


예시#

curl https://api.nexith.ai/v1/responses \
  -H "Authorization: Bearer $NEXITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nexith-core",
    "instructions": "You are a helpful coding agent.",
    "input": [{"type":"message","role":"user","content":[{"type":"input_text","text":"say ok"}]}],
    "max_output_tokens": 256
  }'

max_output_tokens에는 숨은 추론이 포함됩니다. 추론 모델에서는 ≥ 512를 권장하며, 너무 작게 설정하면 status: "incomplete"와 함께 본문이 비게 됩니다.


클라이언트 구성#

Codex CLI#

# ~/.codex/config.toml
[model_providers.nexith]
name = "Nexith"
base_url = "https://api.nexith.ai/v1"
env_key = "NEXITH_API_KEY"
wire_api = "responses"

자세한 내용은 Codex 연동을 참고하세요.