# Responses-API

> Die Responses-API von OpenAI bei OpenCheese: POST /v1/responses mit Instructions, Eingabeelementen, Streaming-Events, Function-Tools und Reasoning-Stufe.
>
> Webseite: https://opencheese.dev/de/docs/responses/ · Alle Seiten der Doku: https://opencheese.dev/de/docs.md

`POST https://api.opencheese.dev/v1/responses` ist die Responses-API von OpenAI. Codex nutzt sie,
ebenso die `responses`-Methoden der OpenAI-SDKs.

## Eine erste Anfrage

```bash
curl https://api.opencheese.dev/v1/responses \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "instructions": "Answer in one sentence.", "input": "What is a gateway?"}'
```

`model` ist ein Pflichtfeld; `input` ist ein String oder eine Liste von Eingabeelementen, und
`instructions` wird zum System-Prompt. Der Text der Antwort steht in `output[].content[]`-Elementen
vom Typ `output_text`:

```json
{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "MODEL_ID",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "A gateway passes your requests on to the models behind it." }]
    }
  ],
  "usage": { "input_tokens": 24, "output_tokens": 13, "total_tokens": 37 }
}
```

## Parameter

| Feld | Hinweise |
| --- | --- |
| `model` | Pflichtfeld. Eine `id` aus [`/v1/models`](https://opencheese.dev/de/docs/models.md). |
| `input` | Ein String oder Elemente vom Typ `message`, `function_call` und `function_call_output`. |
| `instructions` | Der System-Prompt. |
| `stream` | `true` für Server-Sent Events. |
| `tools`, `tool_choice` | Function-Tools, sofern das Modell Tools unterstützt. |
| `reasoning.effort` | Eine Stufe aus den `supported_reasoning_levels` des Modells. |
| `temperature`, `top_p`, `max_output_tokens` | Optional. Setzt du sie nicht, gelten die Standardwerte des Modells. |

## Unterhaltungen werden vollständig gesendet

Jede Anfrage enthält in `input` die gesamte Unterhaltung: Frühere Nachrichten sendest du erneut als
`message`-Elemente mit (die des Assistenten mit `role: "assistant"`). `previous_response_id`,
`store` und `text.format` werden hier nicht unterstützt; für strukturierte Ausgabe nutzt du
[Chat Completions](https://opencheese.dev/de/docs/chat-completions.md) mit `response_format`.

```json
{
  "model": "MODEL_ID",
  "input": [
    { "type": "message", "role": "user", "content": "Name three cheeses." },
    { "type": "message", "role": "assistant", "content": "Brie, Gouda and Comté." },
    { "type": "message", "role": "user", "content": "Which one melts best?" }
  ]
}
```

## Streaming

```bash
curl -N https://api.opencheese.dev/v1/responses \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "stream": true, "input": "Count to three."}'
```

Der Stream sendet die Event-Typen der Responses-API: `response.created` und
`response.in_progress`, dann `response.output_item.added`, `response.output_text.delta` mit dem
Text, die passenden `.done`-Events und zum Schluss `response.completed` mit der vollständigen
Antwort und ihrem `usage`. Schlägt eine Anfrage fehl, nachdem der Stream begonnen hat, endet er
mit `response.failed`; dessen `response.error` enthält einen `code` und eine `message`.

```text
event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"One, two"}

event: response.completed
data: {"type":"response.completed","response":{"status":"completed","usage":{"input_tokens":12,"output_tokens":6,"total_tokens":18}}}
```

## Tools

```json
{
  "model": "MODEL_ID",
  "input": "What is the weather in Paris?",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Current weather for a city",
      "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] }
    }
  ]
}
```

Ein Tool-Aufruf kommt als Ausgabeelement vom Typ `function_call` mit `call_id`, `name` und
`arguments`. Das Ergebnis sendest du in der nächsten Anfrage als `function_call_output`-Element
mit derselben `call_id` zurück, und zwar nach dem `function_call`-Element selbst.

## Reasoning-Stufe

```bash
curl https://api.opencheese.dev/v1/responses \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "reasoning": {"effort": "high"}, "input": "Plan a three-day trip to Lyon."}'
```

Setzt du keine Stufe, gilt die Standardstufe des Modells. Eine Stufe, die das Modell nicht
anbietet, wird mit `unsupported_reasoning_effort` abgelehnt, und der Fehler nennt die Stufen, die
es anbietet. Reasoning-Zusammenfassungen kommen, sofern das Modell sie liefert, als
Ausgabeelemente vom Typ `reasoning`.

## Verbrauch

`usage` meldet `input_tokens` (mit `input_tokens_details.cached_tokens`), `output_tokens`
(mit `output_tokens_details.reasoning_tokens`) und `total_tokens`.

## Python

```python
from openai import OpenAI

client = OpenAI(base_url="https://api.opencheese.dev/v1", api_key="YOUR_OPENCHEESE_API_KEY")
response = client.responses.create(model="MODEL_ID", input="Write a haiku about cheese.")
print(response.output_text)
```

Fehler an diesem Endpunkt kommen immer als HTTP-Status mit JSON-Body, nie als Antwort des
Assistenten wie bei Chat Completions; hat der Stream schon begonnen, kommen sie als
`response.failed`. Siehe [Fehler und Ratenlimits](https://opencheese.dev/de/docs/errors.md). Füge den Header
[`opencheese-session-uuid`](https://opencheese.dev/de/docs/sessions.md) hinzu, um eine Unterhaltung zusammenzuhalten.