OpenAI Responses

Official docs: Create a model response · Text generation · Streaming responses

POST /v1/responses is the Responses API shaped text entrypoint and the recommended starting point for new projects. It carries single-turn and multi-turn content in input and returns a structured output array.

Item	Value
Endpoint	`POST /v1/responses`
Base URL (OpenAI SDK)	`https://api.modelgo.ai/v1`
Authentication	`Authorization: Bearer $MODELGO_API_KEY`
Protocol value	`openai_responses`

Request examples

bash

curl https://api.modelgo.ai/v1/responses \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "input": "Introduce ModelGo in three sentences.",
    "max_output_tokens": 256
  }'

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MODELGO_API_KEY"],
    base_url="https://api.modelgo.ai/v1",
)

resp = client.responses.create(
    model="<model>",
    input="Introduce ModelGo in three sentences.",
)
print(resp.output_text)

Common fields

Field	Description
`model`	Platform logical model name
`input`	A string (single turn), or an array of items (messages, `function_call`, `function_call_output`, ...)
`instructions`	System prompt; the equivalent of a `system` message in Chat Completions
`max_output_tokens`	Output cap, minimum 16; values below 16 are lifted to 16 by the gateway (which can only generate more, never less)
`tools` / `tool_choice`	Function tools and selection policy
`text.format`	Structured output format (such as `json_schema`)
`reasoning.effort`	Reasoning effort; accepted values depend on the model
`stream`	`true` returns a typed SSE event stream

Upstream translation boundaries

The gateway resolves the model and decides the protocol at ingress, then picks how to deliver the request based on the selected upstream's capabilities:

When the upstream natively serves Responses, the request is forwarded with Responses semantics, preserving Responses-only features such as previous_response_id and reasoning summaries.
When the upstream only serves Chat Completions, the gateway translates the request into chat completions and maps the result back into Responses shape. That path drops — and records — capabilities a chat upstream cannot express (for example hosted tools and include=reasoning.encrypted_content).
Context behind previous_response_id can be restored within 24 hours; outside that window, or when the upstream does not support it, the call is treated as a fresh request.

Clients therefore always see the Responses shape and never need to know which supplier served the call.

Responses and streaming

Non-streaming responses carry object: "response"; output is an array that may contain both reasoning and message items, the text is readable from output_text, and usage is in usage.

Streaming returns typed SSE: it starts with response.created, text deltas arrive as response.output_text.delta, and the stream ends with response.completed carrying the final usage. The gateway also forces usage reporting on the inner upstream so streaming calls are billed on actual usage.

Key conventions

When a logical model does not declare openai_responses, this entrypoint answers HTTP 400 with error_class=model_protocol_not_offered (app_error_id=4005).
The error envelope is OpenAI-shaped ({"error":{...}}) with a top-level trace_id.
Request bodies are capped at 10 MiB.
Gateway-private fields in the client body are stripped before forwarding so they never pollute the upstream request.

See the text generation overview for the trade-off against Chat Completions: the two overlap heavily and differ mainly in input shape, event stream, and Responses-only features. Existing chat-completion clients have no reason to migrate for its own sake.