Responses

O dialeto Responses da OpenAI, o padrão dos SDKs mais novos da OpenAI. Este gateway implementa a parte sem estado: você envia a entrada, recebe uma resposta, e nada é guardado. Tudo o que exigiria que o servidor lembrasse ou agisse devolve 501.

POST/v1/responses#

• Auth e limite: como em chat completions: a sua chave de API e o limite de requisições /v1 compartilhado.
• Corpo: JSON, com Content-Type: application/json.

curl -s "$SHVIA_URL/v1/responses" \
  -H "Authorization: Bearer $SHVIA_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "'"$SHVIA_MODEL"'",
    "instructions": "Answer in one sentence.",
    "input": "What is a gateway?"
  }'

Requisição#

Um input em array traz mensagens com um role de user, assistant, system ou developer (os dois últimos viram sistema), e um content que é uma string ou uma lista de blocos input_text, output_text ou text. A entrada precisa conter ao menos uma mensagem do usuário, senão a chamada devolve 400.

O que devolve 501#

Estes são recusados, com o corpo mostrado abaixo, antes de o modelo ser escolhido:

{
  "error": {
    "message": "'tools' is not supported by this gateway yet (stateless slice — see docs).",
    "type": "api_error",
    "param": null,
    "code": "not_implemented"
  }
}

O nome entre aspas em message é o primeiro campo que foi recusado.

Resposta#

{
  "id": "resp_2c058e36a9f2418398cebdcd",
  "object": "response",
  "created_at": 1767225600,
  "status": "completed",
  "model": "claude-sonnet-4-6@anthropic",
  "output": [
    {
      "type": "message",
      "id": "msg_2c058e36a9f2418398cebdcd",
      "status": "completed",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "A gateway is a single entry point in front of several services.", "annotations": [] }]
    }
  ],
  "usage": {
    "input_tokens": 21,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 14,
    "output_tokens_details": { "reasoning_tokens": 0 },
    "total_tokens": 35
  },
  "store": false,
  "error": null,
  "incomplete_details": null,
  "instructions": "Answer in one sentence.",
  "metadata": {},
  "parallel_tool_calls": true,
  "tool_choice": "auto",
  "tools": []
}

• Uma resposta concluída traz exatamente um item message com uma parte output_text. Os objetos em andamento e com falha de um stream têm output vazio.
• parallel_tool_calls, tool_choice e tools são constantes.
• instructions é null quando você não enviou nenhuma, e metadata é {}.

Streaming#

Com "stream": true cada evento é event: <type> e data: {…}, e todo payload traz um sequence_number que começa em 0. Os eventos vêm nesta ordem:

1. response.created e response.in_progress, com o objeto de resposta em andamento.
2. Quando o modelo produz texto: response.output_item.added, response.content_part.added e depois um response.output_text.delta por fragmento.
3. response.output_text.done, response.content_part.done e response.output_item.done, que trazem o texto completo.
4. Um último evento: response.completed, response.incomplete ou response.failed.

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_…","output_index":0,"content_index":0,"delta":"A gateway","sequence_number":4}

event: response.output_text.done
data: {"type":"response.output_text.done","item_id":"msg_…","output_index":0,"content_index":0,"text":"A gateway is a single entry point.","sequence_number":7}

Quando o modelo para de responder no meio, a parte de texto é fechada e o stream termina com response.incomplete e incomplete_details.reason igual a read_timeout. Quando o modelo não devolve nada, ou os servidores não podem ser alcançados, ele termina com response.failed, e response.error.code é empty_response ou upstream_error.

Erros#

Os erros usam o formato da OpenAI, como em chat completions: 401 invalid_api_key, 403 permission_denied, 404 model_not_found, 400 para um corpo ruim, 501 not_implemented, e 502 ou 504 com empty_response, upstream_error ou read_timeout. Um 504 acrescenta um objeto partial, a resposta até onde chegou, e o header X-Inference-Incomplete: read_timeout. Quando todos os modelos da cadeia falham, a recusa de um provedor de modelo mantém o status do próprio provedor e o código upstream_error. Um 401 ou 403 aqui pode, portanto, vir do provedor do modelo, por exemplo um servidor de modelo que rejeita as credenciais do próprio gateway, e não da sua chave: confira a chave com GET /api/v1/auth/verify.

GET/v1/responses/{id}#

Sempre 404, porque nada é guardado:

{
  "error": {
    "message": "Response 'resp_x' was not stored: this gateway is stateless (store is not supported yet).",
    "type": "invalid_request_error",
    "param": null,
    "code": "not_found_error"
  }
}

Não há nenhuma outra rota para responses: nem delete, nem cancelamento, nem listagem de entradas.

Tratamento de dados#

Como no chat completions: nada é guardado como conversa, a chamada é medida, e identificadores comuns no texto são mascarados antes de ele ir para um modelo que não está na infraestrutura do próprio operador. Veja seus dados.