# OpenAI Responses API

> POST /v1/responses on sference: the OpenAI Responses shape with background execution, streams, the 24h window, and the events API.

Source: https://sference.com/docs/api/responses

`POST https://api.sference.com/v1/responses` is the OpenAI Responses shape, and it is the surface with the most sference-specific capability: **background execution**, the **24h completion window**, and the **events API**.

Inference is modeled as a **response** resource: you create it, observe status, and read structured **output** (text, optional reasoning, errors). A response is either **realtime** (blocking, returns when inference finishes) or **background** (`background: true`, polled or streamed to completion).

```bash
curl https://api.sference.com/v1/responses \
  -H "Authorization: Bearer $SFERENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zai-org/GLM-5.3",
    "input": "Summarize the case for prefix caching."
  }'
```

> **Where to read schemas**
>
> Open **API Reference** in the sidebar → **Inference** for `POST/GET /v1/responses` and `/v1/responses/events`. Everything is generated from the same OpenAPI document as production.

## Mental model

1. **`POST /v1/responses`** — create the work (`model`, `input`, optional sampling knobs, `metadata`).
2. **`GET /v1/responses/{id}`** — poll `status`, `output`, and `error` until terminal.
3. **`GET /v1/responses/events`** — cursor through completion events instead of re-reading the full document.
4. **Streams** — group related responses under one `stream_id` with a cost rollup and a resumable cursor. See [Streams](https://sference.com/docs/guides/streams).

## Request fields

| Field | Notes |
| --- | --- |
| `model` | Catalog id |
| `input` | A string (shorthand for one user message) or a list of input items |
| `instructions` | Developer/system instructions |
| `max_output_tokens` | Output cap. On reasoning models this covers hidden reasoning too |
| `temperature`, `top_p` | Sampling |
| `tools`, `tool_choice` | OpenAI tool shape |
| `text.format` | Structured output — see [Structured outputs](https://sference.com/docs/guides/structured-outputs) |
| `reasoning`, `include_reasoning`, `enable_thinking` | Reasoning controls |
| `include` | Accepted; server-side tools (web search, file search, computer use) are not available |
| `stream` | SSE stream |
| `background` | Run on the 24h window and return immediately |
| `metadata.completion_window` | `"24h"` — the only supported value; requires `background: true` |
| `metadata.stream_id` | Attach the response to a [stream](https://sference.com/docs/guides/streams) |
| `metadata.completion_webhook`, `metadata.webhook_token` | Callback delivery — see [Webhooks](https://sference.com/docs/guides/webhooks) |
| `prompt_cache_key` | Pins the worker for prefix-cache hits — see [Prompt caching](https://sference.com/docs/guides/prompt-caching) |
| `service_tier` | `"flex"` for 0.7 × list |
| `max_queue_wait_s` | 5–300s admission bound |

## Background execution

Set `background: true` and the call returns a response id immediately instead of blocking. Collect it later by polling or by webhook.

```python
response = client.responses.create(
    model="zai-org/GLM-5.3",
    input="Summarize this 200-page filing.",
    background=True,
    metadata={"completion_window": "24h"},
)
print(response.id)   # collect later
```

```python
# Later
r = client.responses.retrieve(response.id)
if r.status == "completed":
    print(r.output_text)
```

Background responses bill at **0.5 ×** list. This is the surface to use for long-horizon agent steps, overnight jobs, and anything nobody is waiting on.

> **Collect on the finish reason, not on status alone**
>
> On a reasoning model, `max_output_tokens` covers hidden reasoning as well as the answer. A response can settle `incomplete` with a perfectly good answer attached. Check the incomplete detail and use the output if it is there rather than discarding it.

## Streaming

```python
with client.responses.stream(
    model="zai-org/GLM-5.3",
    input="Write a haiku about GPUs.",
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
```

## The events API

`GET /v1/responses/events` returns completions in order with a cursor, so a consumer can resume where it stopped. Pass `stream_id` for one stream's feed, or omit it for the account-wide feed of every background response.

| Parameter | Meaning |
| --- | --- |
| `stream_id` | One stream's events; omit for the account-wide feed |
| `limit` | Page size |
| `starting_after` / `ending_before` | Cursor by completion id |
| `wait_ms` | Long-poll: hold the request open for new events |

```python
from sference_sdk import SferenceClient

client = SferenceClient()
for event in client.iter_responses_events(consumer_name="worker-1"):
    process(event)
```

The SDK's checkpoint helpers persist the cursor per consumer, so a restarted worker resumes rather than replaying. See [Streams](https://sference.com/docs/guides/streams).

## Processing modes

| Mode | How | Price |
| --- | --- | --- |
| **realtime** | blocking `POST /v1/responses` (no `background`) | list |
| **flex** | `service_tier: "flex"` | 0.7 × list |
| **batch** | `background: true` + `metadata.completion_window: "24h"` | 0.5 × list |

All three share the same models and request shape; only scheduling priority and price differ. Responses echo the tier actually served in `service_tier`. For large static backfills prefer the [Batch API](https://sference.com/docs/guides/batches) — cheaper, simpler to retry, easier to reconcile.

## Statelessness

Every request is answered from the content you send. `previous_response_id` and `conversation` are **removed rather than rejected**, so your request still runs — it just does not see the turn they name. Send the full conversation in `input` on every turn; every OpenAI-compatible SDK does this by default. See [API compatibility](https://sference.com/docs/compatibility).

- [OpenAI Chat API](https://sference.com/docs/api/chat-completions): The OpenAI surface most clients already speak.
- [Messages](https://sference.com/docs/api/messages): The Anthropic-compatible surface.
- [Streams](https://sference.com/docs/guides/streams): Group responses, roll up cost, consume with a cursor.
- [Batch API](https://sference.com/docs/guides/batches): JSONL jobs on the same 24h window.