Visão Geral da Responses API¶

O endpoint POST /v1/responses é o núcleo da API Nodexa. Ele aceita uma mensagem (ou um histórico completo de conversa) e retorna uma resposta do assistente configurado, com a opção de fazer streaming de tokens em tempo real.

Endpoint¶

POST /v1/responses

URL Base: https://seu-admin.exemplo.com

Headers da Request¶

Header	Obrigatório	Descrição
`x-api-key`	Sim (ou `Authorization`)	Sua API key Nodexa (`nxk_...`)
`Authorization`	Sim (ou `x-api-key`)	`Bearer nxk_...` — alternativa ao `x-api-key`
`Content-Type`	Sim	Deve ser `application/json`
`x-user-id`	Não	Identificador do usuário final — habilita a busca de memória
`x-user-tokens`	Não	Objeto JSON de `{"provider_id": "oauth_token"}` para OAuth de tools

Corpo da Request¶

{
  "model": "asst_01234567-89ab-cdef-0123-456789abcdef",
  "input": "string ou InputMessage[]",
  "stream": false,
  "previous_response_id": "resp_01234567-89ab-cdef-0123-456789abcdef",
  "instructions": "Override opcional do prompt de sistema",
  "tools": []
}

Campos¶

`model` (obrigatório)¶

Tipo: string

O UUID do assistente Nodexa a ser invocado. Corresponde a um assistente configurado na sua plataforma. Exemplo:

"model": "asst_01234567-89ab-cdef-0123-456789abcdef"

`input` (obrigatório)¶

Tipo: string | InputMessage[]

A mensagem do usuário ou um array completo de mensagens da conversa.

String simples:

"input": "Como está o tempo hoje?"

Array de mensagens:

"input": [
  { "role": "user", "content": "Meu nome é Alice." },
  { "role": "assistant", "content": "Olá Alice! Como posso ajudá-la?" },
  { "role": "user", "content": "Qual é o meu nome?" }
]

Retornando resultados de tools:

"input": [
  {
    "type": "function_call_output",
    "call_id": "call_abc123",
    "output": "{\"temperatura\": 22, \"unidade\": \"celsius\"}"
  }
]

Veja Tipos de InputMessage abaixo para a referência completa de tipos.

`stream` (opcional)¶

Tipo: boolean Padrão: false

Defina como true para receber um stream de Server-Sent Events. Confira Streaming para a referência completa de eventos SSE.

`previous_response_id` (opcional)¶

Tipo: string

O id de uma resposta anterior na mesma conversa. Quando fornecido, a plataforma automaticamente carrega o histórico da conversa, evitando que você precise incluí-lo em input. Exemplo:

"previous_response_id": "resp_01234567-89ab-cdef-0123-456789abcdef"

Confira Continuidade de Conversas para mais detalhes.

`instructions` (opcional)¶

Tipo: string

Uma instrução de nível de sistema que substitui ou complementa o prompt de sistema padrão do assistente apenas para esta request. Útil para injetar contexto por request como a data atual, idioma do usuário ou estado da aplicação.

"instructions": "O usuário está acessando a seção de faturamento. Hoje é 2024-11-15. Responda em português formal."

`tools` (opcional)¶

Tipo: Tool[]

Um array de definições de tools disponíveis para o assistente nesta request. Passar um array explícito de tools (mesmo um vazio) substitui as tools configuradas no assistente. Omita o campo completamente para usar as tools configuradas do assistente sem alterações.

Confira Tools para todos os tipos de tools suportados.

Tipos de InputMessage¶

Mensagem baseada em papel¶

{
  "role": "user" | "assistant" | "system",
  "content": "string"
}

Campo	Tipo	Descrição
`role`	`"user" \\| "assistant" \\| "system"`	O autor desta mensagem
`content`	`string`	O conteúdo textual da mensagem

Saída de function call¶

Usada para retornar o resultado de uma chamada de tool do lado do cliente para o assistente:

{
  "type": "function_call_output",
  "call_id": "call_abc123",
  "output": "string (resultado codificado em JSON)"
}

Campo	Tipo	Descrição
`type`	`"function_call_output"`	Identifica isto como um resultado de tool
`call_id`	`string`	O `call_id` do evento `function_call_arguments.done`
`output`	`string`	O valor de retorno da tool, codificado em JSON como string

Confira Function Calling para o fluxo completo.

Corpo da Response (sem streaming)¶

{
  "id": "resp_01234567-89ab-cdef-0123-456789abcdef",
  "object": "response",
  "status": "completed",
  "model": "asst_01234567-89ab-cdef-0123-456789abcdef",
  "output": [...],
  "output_text": "A resposta do assistente como texto simples",
  "created_at": 1700000000
}

Campos da Response¶

Campo	Tipo	Descrição
`id`	`string`	Identificador único da resposta — salve para continuidade de conversas
`object`	`string`	Sempre `"response"`
`status`	`string`	`"completed"` ou `"requires_action"`
`model`	`string`	O UUID do assistente que tratou a request
`output`	`OutputItem[]`	Array estruturado de itens de saída
`output_text`	`string`	Campo de conveniência — texto concatenado de todos os itens de mensagem
`created_at`	`number`	Timestamp Unix da criação da resposta

Valores de `status`¶

"completed" — O assistente terminou de processar e toda a saída está presente. Nenhuma ação adicional necessária.

"requires_action" — O assistente invocou uma ou mais function tools do lado do cliente e está aguardando os resultados. Você deve executar as funções e enviar uma request de acompanhamento. Confira Function Calling.

Tipos de Item de Saída¶

O array output contém um ou mais itens. Os tipos mais comuns:

Item de mensagem:

{
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "output_text",
      "text": "Aqui está sua resposta..."
    }
  ]
}

Item de function call (quando status é requires_action):

{
  "type": "function_call",
  "name": "get_weather",
  "call_id": "call_abc123",
  "arguments": "{\"location\": \"São Paulo\", \"unit\": \"celsius\"}"
}

Item de resumo de raciocínio (para modelos de raciocínio):

{
  "type": "reasoning",
  "summary": [
    {
      "type": "summary_text",
      "text": "O usuário está perguntando sobre..."
    }
  ]
}

Exemplo Completo de Request/Response¶

Request¶

curl https://seu-admin.exemplo.com/v1/responses \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "asst_01234567-89ab-cdef-0123-456789abcdef",
    "input": "Qual é a capital do Brasil?",
    "stream": false
  }'

Response¶

{
  "id": "resp_01234567-89ab-cdef-0123-456789abcdef",
  "object": "response",
  "status": "completed",
  "model": "asst_01234567-89ab-cdef-0123-456789abcdef",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "A capital do Brasil é Brasília."
        }
      ]
    }
  ],
  "output_text": "A capital do Brasil é Brasília.",
  "created_at": 1700000000
}

Usando o SDK da OpenAI¶

Como a Responses API do Nodexa é wire-compatible com a OpenAI, você pode usar o SDK oficial:

Node.jsPython

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://seu-admin.exemplo.com/v1',
  apiKey: 'SUA_CHAVE_DE_API',
});

// Sem streaming
const response = await client.responses.create({
  model: 'SEU_ID_DE_ASSISTENTE',
  input: 'Qual é a capital do Brasil?',
});

console.log(response.output_text);
// => "A capital do Brasil é Brasília."

console.log(response.id);
// => "resp_01234567-89ab-cdef-0123-456789abcdef"

from openai import OpenAI

client = OpenAI(
    base_url="https://seu-admin.exemplo.com/v1",
    api_key="SUA_CHAVE_DE_API",
)

response = client.responses.create(
    model="SEU_ID_DE_ASSISTENTE",
    input="Qual é a capital do Brasil?",
)

print(response.output_text)
# => "A capital do Brasil é Brasília."

Páginas Relacionadas¶

Streaming — referência de eventos SSE para requests com stream: true
Tools — tipos de tools e quando usar cada uma
Continuidade de Conversas — conversas com múltiplos turnos
Function Calling — fluxo de execução de tools no lado do cliente

Visão Geral da Responses API¶

Endpoint¶

Headers da Request¶

Corpo da Request¶

Campos¶

model (obrigatório)¶

input (obrigatório)¶

stream (opcional)¶

previous_response_id (opcional)¶

instructions (opcional)¶

tools (opcional)¶

Tipos de InputMessage¶

Mensagem baseada em papel¶

Saída de function call¶

Corpo da Response (sem streaming)¶

Campos da Response¶

Valores de status¶

Tipos de Item de Saída¶

Exemplo Completo de Request/Response¶

Request¶

Response¶

Usando o SDK da OpenAI¶

Páginas Relacionadas¶

`model` (obrigatório)¶

`input` (obrigatório)¶

`stream` (opcional)¶

`previous_response_id` (opcional)¶

`instructions` (opcional)¶

`tools` (opcional)¶

Valores de `status`¶