> ## Documentation Index
> Fetch the complete documentation index at: https://runinfra.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses

> POST /v1/responses, a Responses-shaped compatibility adapter over RunInfra chat-completions deployments.

```http theme={"dark"}
POST https://api.runinfra.ai/v1/responses
```

RunInfra `/v1/responses` is a **chat-completions compatibility adapter** for LLM and vision-language deployments. The gateway converts supported `input` and `instructions` fields into chat messages, forwards the request through the same serving path as `/v1/chat/completions`, then wraps the result in a Responses-shaped envelope.

<Warning>
  This endpoint does not implement full OpenAI Responses state, include, reasoning, tool, conversation-item, or background-job semantics. Use `/v1/chat/completions` when your app needs tool calls today.
</Warning>

## Minimal request

<RequestExample>
  ```python Python theme={"dark"}
  import os
  from openai import OpenAI

  client = OpenAI(
      base_url=os.environ.get("RUNINFRA_BASE_URL", "https://api.runinfra.ai/v1"),
      api_key=os.environ["RUNINFRA_GATEWAY_KEY"],
  )

  response = client.responses.create(
      model=os.environ["RUNINFRA_MODEL"],
      input="Write a one-sentence deployment health check.",
  )

  print(response.output_text)
  ```

  ```javascript JavaScript theme={"dark"}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: process.env.RUNINFRA_BASE_URL ?? "https://api.runinfra.ai/v1",
    apiKey: process.env.RUNINFRA_GATEWAY_KEY,
  });

  const response = await client.responses.create({
    model: process.env.RUNINFRA_MODEL,
    input: "Write a one-sentence deployment health check.",
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={"dark"}
  curl https://api.runinfra.ai/v1/responses \
    -H "Authorization: Bearer ${RUNINFRA_GATEWAY_KEY:?Set RUNINFRA_GATEWAY_KEY}" \
    -H "Content-Type: application/json" \
    -d "{\"model\":\"${RUNINFRA_MODEL:?Set RUNINFRA_MODEL from GET /v1/models}\",\"input\":\"Write a one-sentence deployment health check.\"}"
  ```
</RequestExample>

## Streaming

Set `stream: true` to receive server-sent events. The stream uses OpenAI-shaped Responses event names for text deltas and terminal completion events when the selected deployment supports streaming.

```python theme={"dark"}
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("RUNINFRA_BASE_URL", "https://api.runinfra.ai/v1"),
    api_key=os.environ["RUNINFRA_GATEWAY_KEY"],
)

stream = client.responses.create(
    model=os.environ["RUNINFRA_MODEL"],
    input="Count to five.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
```

## Supported request fields

<ParamField body="model" type="string" required>
  Model id returned by `GET /v1/models`, or `default` for a pipeline-scoped snippet.
</ParamField>

<ParamField body="input" type="string | object[]" required>
  Prompt text, or an array of supported Responses input message objects.
</ParamField>

<ParamField body="instructions" type="string">
  System-level instruction text. The adapter maps this into a system message.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  Return a server-sent event stream instead of one JSON response.
</ParamField>

<ParamField body="max_output_tokens" type="integer">
  Maximum generated output tokens. The adapter maps this to the serving backend's chat completion token limit.
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature for compatible LLM deployments.
</ParamField>

<ParamField body="top_p" type="number">
  Nucleus sampling cutoff for compatible LLM deployments.
</ParamField>

<ParamField body="response_format" type="object">
  Structured output format passed through to the chat-completions serving path. Support depends on the selected deployment.
</ParamField>

<ParamField body="tools" type="object[]">
  OpenAI chat-completions tool definitions accepted as pass-through input for compatible deployments. This adapter does not execute hosted tools or manage a stateful tool loop.
</ParamField>

<ParamField body="tool_choice" type="string | object">
  Tool-selection preference passed through to compatible chat-completions deployments.
</ParamField>

## Not shipped on this adapter

* Stateful response retrieval or deletion.
* `include`, `reasoning`, hosted tools, conversation items, file search, web search, computer use, and background jobs.
* Stateful tool execution or hosted tool orchestration. Use [Chat completions](/docs/api-reference/chat-completions) for production tool loops.

## Retry semantics

The native RunInfra SDK treats non-streaming `responses.create()` as replay-safe only when you provide an idempotency key. Streaming Responses requests are sent once because a partial stream may already have reached your app.

## Next steps

<Columns cols={2}>
  <Card title="Chat completions" icon="messages-square" href="/docs/api-reference/chat-completions">
    The canonical endpoint for tools, structured output, and streaming chat.
  </Card>

  <Card title="RunInfra SDK" icon="shield-check" href="/docs/tools-sdks/runinfra-sdk">
    Native request IDs, typed errors, idempotency helpers, and streaming wrappers.
  </Card>
</Columns>