Riferimento API

Responses

POST /v1/responses nel formato OpenAI Responses. Senza stato, quindi invia ogni volta l'intera conversazione.

L'API OpenAI Responses sugli stessi modelli, con le stesse chiavi e la stessa fatturazione delle chat completions. Usala quando il tuo SDK o il ciclo del tuo agente (Codex, l'OpenAI Agents SDK) parla Responses invece di chat.

POSThttps://api.notholy.com/v1/responses

POST https://api.notholy.com/v1/responses

Richiesta

Campo	Tipo	Obbligatorio	Note
`model`	string	Sì	Un ID di modello, per esempio `notholy-specter`
`input`	string o array	Sì	Un prompt, o un elenco di elementi `message`, `function_call` e `function_call_output`. Gli altri tipi di elemento vengono scartati
`instructions`	string	No	Prompt di sistema, messo prima di `input`
`max_output_tokens`	number	No	Limite di output. Il predefinito è il massimo del modello, che fa anche da tetto
`stream`	boolean	No	`true` restituisce eventi `response.*` con nome
`tools`	array	No	Strumenti di tipo funzione. Gli altri tipi vengono scartati
`tool_choice`	string o object	No	Usato quando `tools` è impostato
`reasoning.effort`	string	No	Uno dei `reasoning_efforts` del modello. Qualsiasi altro valore restituisce `400`
`temperature`, `top_p`	number	No	Passati al modello

L'endpoint non conserva stato. previous_response_id restituisce 400 unsupported_parameter, e store, metadata e text.format vengono ignorati. Invia l'intera conversazione in input, compresi gli elementi function_call e function_call_output precedenti.

Risposta senza streaming

JSON

{
  "id": "resp_6mQ2x9",
  "object": "response",
  "created_at": 1793836800,
  "status": "completed",
  "model": "notholy-specter",
  "output": [
    { "type": "reasoning", "id": "rs_1", "summary": [{ "type": "summary_text", "text": "…" }] },
    {
      "type": "message",
      "id": "msg_1",
      "status": "completed",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "AV:N means the attack works over the network…", "annotations": [] }]
    }
  ],
  "usage": {
    "input_tokens": 18,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 96,
    "output_tokens_details": { "reasoning_tokens": 40 },
    "total_tokens": 114
  },
  "error": null,
  "incomplete_details": null,
  "store": false
}

status è incomplete, con incomplete_details.reason: "max_output_tokens", quando il limite di output ha tagliato la risposta.
Le chiamate di strumenti tornano come elementi {"type": "function_call", "call_id": "call_…", "name": "…", "arguments": "…"}.
Quando il modello ha ragionato, per primo arriva un elemento reasoning.

Streaming

Con "stream": true gli eventi sono response.created, response.in_progress, poi per ogni elemento di output response.output_item.added, i delta di testo o di ragionamento, i relativi eventi .done e response.output_item.done, e infine response.completed (o response.incomplete) con usage. Non c'è una riga [DONE]. Un errore a metà stream arriva come response.failed.

Esempio

curl https://api.notholy.com/v1/responses \
  -H "Authorization: Bearer $NOTHOLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "notholy-specter", "input": "Summarize what CVSS 3.1 AV:N means."}'

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.notholy.com/v1", api_key=os.environ["NOTHOLY_API_KEY"])

r = client.responses.create(model="notholy-specter", input="Summarize what CVSS 3.1 AV:N means.")
print(r.output_text)

import OpenAI from 'openai';

const client = new OpenAI({ baseURL: 'https://api.notholy.com/v1', apiKey: process.env.NOTHOLY_API_KEY });

const stream = await client.responses.create({ model: 'notholy-specter', input: 'Name two sources of EPSS data.', stream: true });
for await (const ev of stream) if (ev.type === 'response.output_text.delta') process.stdout.write(ev.delta);
console.log();

Errori

Gli stessi codici delle chat completions: 400 model o input mancante · 401 chiave non valida · 402 crediti esauriti · 404 modello sconosciuto · 429 occupato (rispetta retry-after) · 503 modello non disponibile. Vedi Errori.