Referência da API

Responses

POST /v1/responses no formato OpenAI Responses. Sem estado: envie a conversa inteira a cada chamada.

A API Responses da OpenAI, com os mesmos modelos, chaves e cobrança dos chat completions. Use quando o seu SDK ou loop de agente (Codex, o OpenAI Agents SDK) fala Responses em vez de chat.

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

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

Requisição

Campo	Tipo	Obrigatório	Observações
`model`	string	Sim	Um ID de modelo, por exemplo `notholy-specter`
`input`	string ou array	Sim	Um prompt ou uma lista de itens `message`, `function_call` e `function_call_output`. Outros tipos de item são descartados
`instructions`	string	Não	System prompt, colocado antes de `input`
`max_output_tokens`	number	Não	Limite de saída. O padrão é o máximo do modelo, que também é o teto
`stream`	boolean	Não	`true` retorna eventos nomeados `response.*`
`tools`	array	Não	Ferramentas do tipo function. Outros tipos são descartados
`tool_choice`	string ou object	Não	Usado quando `tools` está definido
`reasoning.effort`	string	Não	Um dos `reasoning_efforts` do modelo. Qualquer outro valor retorna `400`
`temperature`, `top_p`	number	Não	Repassados ao modelo

O endpoint não guarda estado. previous_response_id retorna 400 unsupported_parameter, e store, metadata e text.format são ignorados. Envie a conversa inteira em input, incluindo os itens function_call e function_call_output anteriores.

Resposta sem 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 vem como incomplete, com incomplete_details.reason: "max_output_tokens", quando o limite de saída cortou a resposta.
Tool calls voltam como itens {"type": "function_call", "call_id": "call_…", "name": "…", "arguments": "…"}.
Um item reasoning vem primeiro quando o modelo raciocinou.

Streaming

Com "stream": true, os eventos são response.created, response.in_progress, depois, para cada item de saída, response.output_item.added, os deltas de texto ou de raciocínio, os eventos .done deles e response.output_item.done, e por fim response.completed (ou response.incomplete) com usage. Não há linha [DONE]. Uma falha no meio do stream chega como response.failed.

Exemplo

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();

Erros

Os mesmos códigos dos chat completions: 400 falta model ou input · 401 chave inválida · 402 sem créditos · 404 modelo desconhecido · 429 ocupado (respeite o retry-after) · 503 modelo indisponível. Veja Erros.