> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.userbot.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.userbot.ai/_mcp/server.

# Responses

`POST /responses` fa lo stesso lavoro di `/chat/completions`, ma con la forma
dell'API Responses di OpenAI. Serve se il tuo codice, o la libreria che usi, è
già scritto su quel formato. Se parti da zero, [Completamenti chat](/api-chat) è
la scelta più semplice e copre più casi.

Serve una chiave con il permesso **Completion**, come per i completamenti.

## La richiesta

| Campo                  | Obbligatorio | Cosa fa                                                                                          |
| ---------------------- | ------------ | ------------------------------------------------------------------------------------------------ |
| `model`                | Sì           | L'id del modello, nella forma `fornitore/modello`                                                |
| `input`                | Sì           | Una stringa, oppure una lista di messaggi e di elementi `function_call` / `function_call_output` |
| `instructions`         | No           | Le istruzioni di sistema                                                                         |
| `stream`               | No           | `true` per ricevere la risposta come flusso di eventi                                            |
| `tools`, `tool_choice` | No           | Le funzioni che il modello può chiederti di eseguire, al massimo 128                             |
| `temperature`, `top_p` | No           | Da 0 a 2 e da 0 a 1                                                                              |
| `max_output_tokens`    | No           | Tetto alla lunghezza della risposta. Senza, il tetto è 16.384 token                              |
| `reasoning_effort`     | No           | `none`, `minimal`, `low`, `medium`, `high` o `xhigh`                                             |
| `seed`, `user`         | No           | Come in Chat Completions                                                                         |

> **Info**
>
> Qui le regole sono più strette che su `/chat/completions`: un campo che non è
> in tabella non viene ignorato, viene rifiutato con `400` e il messaggio
> `Unsupported field "…"`. Fanno eccezione `parallel_tool_calls` e
> `service_tier`, che vengono tolti senza errore. Per il ragionamento usa
> `reasoning_effort`: l'oggetto `reasoning` del formato OpenAI non è accettato.

Fra i campi che ricevono `400` ci sono quelli che conservano lo stato sul server,
come `store` e `previous_response_id`, e il formato di output strutturato
`text`. Userbot non tiene memoria delle risposte: per continuare un dialogo
rimandi in `input` i messaggi precedenti, come in Chat Completions.

Nei messaggi di `input` vengono letti solo i pezzi di testo. Le immagini passate
qui vengono scartate senza errore: se ti servono, usa
[Completamenti chat](/api-chat), che le accetta.

## La risposta

```bash
curl https://api.userbot.ai/api/eu/v1/responses \
  -H "Authorization: Bearer $USERBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "instructions": "Rispondi in italiano, in una frase.",
    "input": "Cosa contiene un preventivo?"
  }'
```

```json
{
  "id": "resp_4c1e0b9a7d2f63e8a51b0c94",
  "object": "response",
  "created_at": 1790841600,
  "status": "completed",
  "error": null,
  "model": "openai/gpt-5.4-mini",
  "output": [
    {
      "type": "message",
      "id": "msg_8a2d4f1c9b7e05a3d6c2e1f0",
      "status": "completed",
      "role": "assistant",
      "content": [
        { "type": "output_text", "text": "Un preventivo elenca le voci di lavoro, i prezzi e la validità dell'offerta." }
      ]
    }
  ],
  "usage": { "input_tokens": 24, "output_tokens": 19, "total_tokens": 43 }
}
```

Il testo è nell'elemento `message` di `output`. Con l'SDK OpenAI per Python lo
leggi direttamente da `response.output_text`:

```python
response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Cosa contiene un preventivo?",
)
print(response.output_text)
```

## Strumenti

Gli strumenti hanno la forma piatta del formato Responses:
`{"type": "function", "name": "...", "parameters": {...}}`. Quando il modello
vuole chiamarne uno, in `output` trovi un elemento `function_call` con `call_id`,
`name` e `arguments`. Esegui la funzione e richiama l'endpoint aggiungendo a
`input` quell'elemento `function_call` e un elemento `function_call_output` con
lo stesso `call_id` e il risultato in `output`.

## Streaming

Con `"stream": true` arrivano gli eventi tipizzati del formato Responses:
`response.created`, poi i `response.output_text.delta` con i pezzi di testo (o
`response.function_call_arguments.delta` per gli strumenti), e infine
`response.completed` con l'oggetto completo e il conteggio dei token. Se qualcosa
si interrompe a metà, al posto del pezzo successivo arriva un evento `error`.

Errori, limiti e costi sono gli stessi di Chat Completions: vedi
[Completamenti chat](/api-chat), [Limiti e quote](/api-limiti) e
[Costi, budget e analytics](/api-costi).