Responses | Guida di Userbot

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 è 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

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, che le accetta.

La risposta

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?"
  }'

{
  "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:

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, Limiti e quote e Costi, budget e analytics.