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

# Responses protocol

> Use GPT text models with OpenAI-compatible input, output items, streaming, and function tools.

Create a response from text or an ordered list of input items. SnapGen's GPT-5.6
and GPT-6 tier models support Responses and Chat Completions. Use the format your
client expects; SnapGen forwards the selected protocol to a native route.

<ParamField body="model" type="string" required>
  Use an exact model ID returned by [`GET /v1/models`](/api-reference/list-models),
  such as `gpt-6.1-sol`.
</ParamField>

<ParamField body="input" type="string | array" required>
  A text prompt or ordered message and tool items. Message items include a `role`
  and `content`. Send conversation history when your application needs it.
</ParamField>

<ParamField body="instructions" type="string">
  Instructions for this response, such as the desired style or task constraints.
</ParamField>

<ParamField body="max_output_tokens" type="integer">
  Caps generated output, including reasoning tokens. Chat Completions uses
  `max_completion_tokens` instead.
</ParamField>

<ParamField body="reasoning" type="object">
  Set GPT reasoning effort with `{ "effort": "medium" }`. Supported effort
  levels vary by model.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  Set to `true` to receive named server-sent events.
</ParamField>

<ParamField body="tools" type="array">
  Function tool definitions use `type`, `name`, `description`, and `parameters`
  at the same level. This differs from Chat Completions' nested `function` format.
  Your application executes the functions and submits their results.
</ParamField>

## Send a request

<RequestExample>
  ```bash Curl theme={null}
  curl https://api.snapgen.org/v1/responses \
    -H "Authorization: Bearer $SNAPGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-6.1-sol",
      "input": "What is an API gateway?",
      "instructions": "Answer in one concise sentence.",
      "reasoning": {"effort": "medium"},
      "max_output_tokens": 2048
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "resp_01HXYZ",
    "object": "response",
    "model": "gpt-6.1-sol",
    "status": "completed",
    "output": [
      {
        "id": "msg_01HXYZ",
        "type": "message",
        "role": "assistant",
        "status": "completed",
        "content": [
          {
            "type": "output_text",
            "text": "An API gateway provides one interface for routing requests to backend APIs.",
            "annotations": []
          }
        ]
      }
    ],
    "usage": {
      "input_tokens": 25,
      "input_tokens_details": {"cached_tokens": 0},
      "output_tokens": 19,
      "output_tokens_details": {"reasoning_tokens": 0},
      "total_tokens": 44
    }
  }
  ```
</ResponseExample>

The example shows the fields needed to read text and usage. Responses can also
contain reasoning or function-call items. Iterate over message items in `output`
and read content items with `type: "output_text"`; do not assume the first output
item contains text. The OpenAI SDKs expose an `output_text` helper.

## Stream text

Add `"stream": true` to the request and read SSE events until a terminal response
event. For example:

```text theme={null}
event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"Hello"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":" from SnapGen"}
```

Append the `delta` field from `response.output_text.delta` events. On
`response.completed`, read the final `response`, including its `usage`. Handle
`response.incomplete`, `response.failed`, and error events as terminal outcomes
instead of assuming every stream completed successfully.

## Function tools

Define tools with the Responses format:

```json theme={null}
{
  "model": "gpt-6.1-sol",
  "input": "What is the weather in Paris?",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Return the current weather for a city.",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
        "additionalProperties": false
      },
      "strict": true
    }
  ]
}
```

When the response includes an `output` item with `type: "function_call"`, parse
its JSON `arguments`, validate the request, and execute the named function in
your application. Continue by sending the original input, relevant response
output items, and a result item in the next request's `input`:

```json theme={null}
{
  "type": "function_call_output",
  "call_id": "call_01HXYZ",
  "output": "{\"city\":\"Paris\",\"temperature_c\":18}"
}
```

Use the `call_id` from the function-call item. Keep reasoning and tool items
needed for that turn in the conversation history. SnapGen forwards tool requests;
it does not execute your functions or provide built-in hosted tools.

## Billing

Billing uses the input, output, and cached-token counts reported in `usage`.
Reasoning tokens count as output. GPT-5.6 and GPT-6 prompts over 272,000 tokens
use the selected model's long-context rate. Check [live GPT-5 pricing](https://snapgen.org/models/gpt-5)
or [live GPT-6 pricing](https://snapgen.org/models/gpt-6) before estimating costs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.