POST /v1/responses

Request

curl https://api.model-gate.com/v1/responses \
  -H "Authorization: Bearer mg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": [
      {
        "role": "user",
        "content": [{"type": "input_text", "text": "Summarize the release."}]
      }
    ],
    "stream": false
  }'

Response

{
  "id": "resp_example",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.4",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "The release adds synchronized documentation and model aliases."}]
    }
  ],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 14,
    "total_tokens": 32
  }
}

Hosted web search

Add:

{
  "tools": [{"type": "web_search"}],
  "tool_choice": "required",
  "include": ["web_search_call.action.sources"]
}

There is no separate supported /v1/web-search contract. Use the Responses API tool.

Async

"async": true is supported only with "stream": false.

The Responses image_generation tool, when actually supported by the configured provider, is not the dedicated Images API. Its output items do not create /v1/images/operations, scoped Images download resources or the Images idempotency/dispatch guarantee. Confirm the provider-specific tool and accounting contract separately; use Images operations for the persistent generation/edit workflow.

Session ID

Use a stable JSON session_id or X-Session-ID header for every turn of this conversation. Priority is session_id → X-Session-ID → recognized session in metadata.user_id → prompt_cache_key → opening conversation content. The identity layer is independent of provider type. Keeping the same ID does not guarantee a cache hit or disable eligible failover. See conversation identity and sticky routing for automatic fallback, scope, limits and the difference from idempotency and stored context.

The same identity is retained for streaming and for asynchronous submission where this endpoint supports it. Do not send a new paid POST merely to test a session after a timeout; check the existing request first.

For a continuation using previous_response_id, reuse your explicit conversation ID. A stored response ID and a Session ID serve different purposes; do not substitute one for the other.

An existing recognized metadata session is used without a mismatch error; an ordinary metadata.user_id is preserved, not treated as a conversation. Higher-priority explicit fields win. See the linked identity reference for formats and upstream transport limits.

A recognized metadata session takes precedence over a cache hint. Automatic identity ignores known cache_control decorations and equivalent single-text wrappers without changing the model request. A separately configured, compatible upstream session-header transport does not occupy ordinary metadata.user_id; this capability is configured by the operator, not selected by the client.