Responses
POST /v1/responses· OpenAI Responses compatible (routed by request shape)
/v1/responses primarily serves clients such as Codex that only speak the Responses API. The
gateway determines the origin from the request shape:
- Codex shape (with
instructions/tools/reasoning/ aninputmessage array) → internally translated into Chat Completions for execution, then the result is translated back into theobject: "response"shape. - Plain text shape (
inputis a string) → returns the OpenAIchat.completionshape (identical to/v1/chat/completions), so non-Codex callers can reuse it conveniently.
Request#
POST /v1/responses
Authorization: Bearer nx-...
Content-Type: application/jsonBody (common)#
| Field | Type | Required | Description |
|---|---|---|---|
model |
string | — | Defaults to nexith (mapped to nexith-core) |
input |
string | array | ✅ | A string, or an array of Responses input items |
stream |
bool | — | Defaults to false |
max_output_tokens |
integer | — | Total budget for reasoning + output; too small a value leaves the output empty |
previous_messages |
array | — | Optional multi-turn history (Nexith extension, Chat shape) |
Additional Codex-shape fields#
| Field | Description |
|---|---|
instructions |
Top-level instructions, translated into a system message |
tools |
Responses tool definitions ({type:"function", name, parameters}), translated into Chat tools |
tool_choice |
auto / none / required / a specific function |
reasoning |
{effort: ...}, translated into 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"}
]Supports input_text, input_image, message, function_call, function_call_output.
Response (Codex shape)#
{
"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(for example, whenmax_output_tokensis reached).- Tool calls are output as
function_callitems.
Response (plain text shape)#
Identical to Chat Completions (object: "chat.completion").
Streaming#
With stream=true, returns SSE. The Codex-shape stream emits Responses events; the text-shape stream
emits chat.completion.chunk. See Streaming protocol for frame details.
Example#
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_tokensincludes hidden reasoning. For reasoning models, ≥ 512 is recommended; too small a value producesstatus: "incomplete"with an empty output.
Client configuration#
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"See Codex integration for details.