API v1Updated 2026-09-16

Responses API

OpenAI-compatible POST /v1/responses endpoint with native response.* event schemas for streaming.

POST /v1/responses is a drop-in replacement for the OpenAI Responses API — the modern protocol built around response objects and structured response.* events. Existing Responses-API code runs against the gateway with a base-URL change only.

Endpoint#

POST/v1/responses

Auth: api-key

Create a response. Non-streaming responses return a full response object; streaming emits native response.* events and ends with response.completed.

Parameters

modelstringbodyrequired

The model identifier (`<public-name>`). See [Model Catalog](/en/docs/api-reference/models).

inputstring | arraybodyrequired

The prompt, either as a plain string or as an array of content parts.

streambooleanbodyoptionaldefault: false

Set `true` to receive Server-Sent Events. See [Streaming & SSE](/en/docs/api-reference/streaming).

Request Example

curl -X POST "https://api.zrouter.dev/v1/responses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<public-name>",
    "input": "Say hello!"
  }'

Responses

200Successful response.

{
  "id": "resp_...",
  "object": "response",
  "created_at": 1720000000,
  "model": "<public-name>",
  "output": [
    {
      "type": "message",
      "content": [{ "type": "output_text", "text": "Hello!" }]
    }
  ],
  "usage": { "input_tokens": 8, "output_tokens": 3, "total_tokens": 11 }
}

400`invalid_request` — malformed or invalid body.

401`invalid_api_key` — missing key, wrong key, or two headers with different values.

402`insufficient_balance` — Token Plan and PAYG balance cannot cover the request.

404`model_not_found` — the model identifier does not exist or is hidden.

429`technical_limit` — passthrough of an upstream 429, not a zrouter rate limit.

502`upstream_error` — the upstream provider failed to process the request.

503`overloaded` or `circuit_open` — capacity shed or an open circuit breaker.

Streaming#

With "stream": true the gateway relays the native response.* event stream from the upstream unchanged. The terminal response.completed event carries the complete output (including the final usage block). Full examples are in Streaming & SSE.