NNexithDocs
StatusDashboard ↗
Overview & quickstartModel catalogGuidesAPI referenceIntegrationsOAuth2 / OIDC

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 / an input message array) → internally translated into Chat Completions for execution, then the result is translated back into the object: "response" shape.
  • Plain text shape (input is a string) → returns the OpenAI chat.completion shape (identical to /v1/chat/completions), so non-Codex callers can reuse it conveniently.

Request#

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

Body (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, when max_output_tokens is reached).
  • Tool calls are output as function_call items.

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_tokens includes hidden reasoning. For reasoning models, ≥ 512 is recommended; too small a value produces status: "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.