# Responses API > Generate responses using the OpenAI Responses API format via /v1/responses. Canonical: https://ai-gateway.sassmaker.com/docs/responses-api ## Endpoint ``` POST /v1/responses ``` The Responses API is an alternative to Chat Completions that uses the [OpenAI Responses format](https://platform.openai.com/docs/api-reference/responses). It accepts a flexible `input` field instead of a structured `messages` array, making it convenient for single-turn prompts and tool-augmented workflows. ## Request Body | Field | Type | Default | Description | |---|---|---|---| | `model` | string | `"auto"` | Model identifier. Use `"auto"` for health-aware round-robin, or specify a model from [`GET /v1/models`](https://ai-gateway.sassmaker.com/models). | | `input` | string \| array \| object | required | The prompt input. Can be a plain string, an array of message objects, or a structured input object. | | `stream` | boolean | `false` | When `true`, responses are streamed as server-sent events. | | `temperature` | number | — | Sampling temperature (0–2). | | `max_output_tokens` | number | — | Maximum number of tokens to generate. | | `min_reasoning_level` | string | — | Minimum reasoning tier for auto-routing. One of `"low"`, `"medium"`, `"high"`. | | `project_id` | string | required* | Project tag for analytics and rate accounting. You can also send `x-gateway-project-id`; one of the two is required. | ### Input Formats **String** — simplest form, treated as a user message: ```json { "model": "auto", "input": "What is the speed of light?" } ``` **Array** — list of message objects with `role` and `content`: ```json { "model": "auto", "input": [ { "role": "system", "content": "You are a physics tutor." }, { "role": "user", "content": "What is the speed of light?" } ] } ``` **Object with minimum reasoning** — use `min_reasoning_level` to avoid routing below a tier: ```json { "model": "auto", "input": "Explain quantum entanglement simply.", "min_reasoning_level": "medium" } ``` ## Response The response follows the OpenAI Responses format: ```json { "id": "resp_abc123", "object": "response", "created_at": 1714000000, "model": "llama-3.3-70b-versatile", "output": [ { "type": "message", "role": "assistant", "content": [ { "type": "output_text", "text": "The speed of light in a vacuum is approximately 299,792,458 metres per second." } ] } ], "usage": { "input_tokens": 12, "output_tokens": 18, "total_tokens": 30 } } ``` The same `x-gateway-*` headers present on Chat Completions are also returned here (see [Chat Completions](https://ai-gateway.sassmaker.com/chat-completions#non-streaming-response)). ## Examples ### Non-Streaming ### curl ```bash curl https://your-gateway.workers.dev/v1/responses \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "auto", "project_id": "my_project", "input": "Summarise the French Revolution in three sentences.", "temperature": 0.5, "max_output_tokens": 300 }' ``` ### JavaScript ```js const response = await fetch('https://your-gateway.workers.dev/v1/responses', { method: 'POST', headers: { 'Authorization': 'Bearer ', 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'auto', input: 'Summarise the French Revolution in three sentences.', temperature: 0.5, max_output_tokens: 300, }), }); const data = await response.json(); const text = data.output[0].content[0].text; console.log(text); ``` ### Multi-Turn Input Array ### curl ```bash curl https://your-gateway.workers.dev/v1/responses \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "auto", "project_id": "my_project", "input": [ { "role": "system", "content": "You are a concise assistant." }, { "role": "user", "content": "What is 17 * 43?" } ] }' ``` ### JavaScript ```js const response = await fetch('https://your-gateway.workers.dev/v1/responses', { method: 'POST', headers: { 'Authorization': 'Bearer ', 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'auto', input: [ { role: 'system', content: 'You are a concise assistant.' }, { role: 'user', content: 'What is 17 * 43?' }, ], }), }); const data = await response.json(); console.log(data.output[0].content[0].text); ``` ### Streaming ### curl ```bash curl https://your-gateway.workers.dev/v1/responses \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "auto", "project_id": "my_project", "input": "Write a haiku about the ocean.", "stream": true }' ``` ### JavaScript ```js const response = await fetch('https://your-gateway.workers.dev/v1/responses', { method: 'POST', headers: { 'Authorization': 'Bearer ', 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'auto', input: 'Write a haiku about the ocean.', stream: true, }), }); const reader = response.body.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const chunk = decoder.decode(value); for (const line of chunk.split('\n')) { if (!line.startsWith('data: ')) continue; const payload = line.slice(6).trim(); if (payload === '[DONE]') break; const event = JSON.parse(payload); // Delta text is in event.delta for Responses streaming if (event.delta) process.stdout.write(event.delta); } } ``` ### With Reasoning ### curl ```bash curl https://your-gateway.workers.dev/v1/responses \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "auto", "project_id": "my_project", "input": "Prove that the square root of 2 is irrational.", "min_reasoning_level": "high" }' ``` ### JavaScript ```js const response = await fetch('https://your-gateway.workers.dev/v1/responses', { method: 'POST', headers: { 'Authorization': 'Bearer ', 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'auto', input: 'Prove that the square root of 2 is irrational.', min_reasoning_level: 'high', }), }); const data = await response.json(); console.log(data.output[0].content[0].text); ```