Ir para o conteúdo

Início Rápido

Faça sua primeira chamada à API Nodexa funcionar em menos de 5 minutos.

Pré-requisitos

  • Uma API key Nodexa (formato: nxk_...) — entre em contato com o administrador da plataforma
  • O UUID de um assistente configurado em sua instância Nodexa
  • curl, Node.js 18+ ou Python 3.9+ instalado

Passo 1 — Obtenha sua API Key e ID do Assistente

Sua API key e ID do assistente são fornecidos pelo administrador da plataforma Nodexa. Você vai precisar de:

Valor Exemplo Descrição
API Key nxk_abc123... Sua chave secreta — nunca exponha no client-side
ID do Assistente asst_01234567-89ab-cdef-0123-456789abcdef UUID do assistente que você quer chamar
URL Base https://seu-admin.exemplo.com Hostname do seu deploy Nodexa

Armazene esses valores como variáveis de ambiente para não expô-los acidentalmente no código:

export NODEXA_API_KEY="nxk_sua_chave_aqui"
export NODEXA_ASSISTANT_ID="asst_01234567-89ab-cdef-0123-456789abcdef"
export NODEXA_BASE_URL="https://seu-admin.exemplo.com"

Passo 2 — Faça sua Primeira Requisição

curl "$NODEXA_BASE_URL/v1/responses" \
  -H "x-api-key: $NODEXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$NODEXA_ASSISTANT_ID\",
    \"input\": \"Olá! Com o que você pode me ajudar?\"
  }"

Instale o SDK da OpenAI se ainda não o fez:

npm install openai

Em seguida, execute:

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: `${process.env.NODEXA_BASE_URL}/v1`,
  apiKey: process.env.NODEXA_API_KEY,
});

const response = await client.responses.create({
  model: process.env.NODEXA_ASSISTANT_ID,
  input: 'Olá! Com o que você pode me ajudar?',
});

console.log(response.output_text);

Instale o SDK da OpenAI se ainda não o fez:

pip install openai

Em seguida, execute:

import os
from openai import OpenAI

client = OpenAI(
    base_url=f"{os.environ['NODEXA_BASE_URL']}/v1",
    api_key=os.environ['NODEXA_API_KEY'],
)

response = client.responses.create(
    model=os.environ['NODEXA_ASSISTANT_ID'],
    input="Olá! Com o que você pode me ajudar?",
)

print(response.output_text)

Passo 3 — Trate a Response

Uma resposta sem streaming bem-sucedida tem a seguinte estrutura:

{
  "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": "Olá! Sou seu assistente de IA. Posso ajudá-lo com..."
        }
      ]
    }
  ],
  "output_text": "Olá! Sou seu assistente de IA. Posso ajudá-lo com...",
  "created_at": 1700000000
}

Os campos mais importantes:

Campo Tipo Descrição
id string ID único da resposta — salve para continuar a conversa
status string "completed" ou "requires_action" (execução de tool necessária)
output_text string Campo de conveniência com a resposta textual do assistente
output array Saída estruturada completa incluindo mensagens e chamadas de tools

Passo 4 — Streaming da Resposta (Opcional, mas Recomendado)

Para uma melhor experiência do usuário, faça streaming da resposta token a token:

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: `${process.env.NODEXA_BASE_URL}/v1`,
  apiKey: process.env.NODEXA_API_KEY,
});

const stream = await client.responses.create({
  model: process.env.NODEXA_ASSISTANT_ID,
  input: 'Conte-me uma história curta sobre um robô.',
  stream: true,
});

for await (const event of stream) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  }
}
console.log(); // nova linha no final

import os
from openai import OpenAI

client = OpenAI(
    base_url=f"{os.environ['NODEXA_BASE_URL']}/v1",
    api_key=os.environ['NODEXA_API_KEY'],
)

with client.responses.stream(
    model=os.environ['NODEXA_ASSISTANT_ID'],
    input="Conte-me uma história curta sobre um robô.",
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
print()  # nova linha no final

curl "$NODEXA_BASE_URL/v1/responses" \
  -H "x-api-key: $NODEXA_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d "{
    \"model\": \"$NODEXA_ASSISTANT_ID\",
    \"input\": \"Conte-me uma história curta sobre um robô.\",
    \"stream\": true
  }"

Passo 5 — Continue a Conversa

Use o id da resposta anterior como previous_response_id para manter o histórico da conversa:

// Primeira mensagem
const first = await client.responses.create({
  model: process.env.NODEXA_ASSISTANT_ID,
  input: 'Meu nome é Alice.',
});

// Segunda mensagem — referencia a primeira resposta
const second = await client.responses.create({
  model: process.env.NODEXA_ASSISTANT_ID,
  input: 'Qual é o meu nome?',
  previous_response_id: first.id,
});

console.log(second.output_text); // "Seu nome é Alice."

# Primeira mensagem
FIRST_RESPONSE=$(curl -s "$NODEXA_BASE_URL/v1/responses" \
  -H "x-api-key: $NODEXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"$NODEXA_ASSISTANT_ID\", \"input\": \"Meu nome é Alice.\"}")

RESPONSE_ID=$(echo $FIRST_RESPONSE | jq -r '.id')

# Segunda mensagem
curl "$NODEXA_BASE_URL/v1/responses" \
  -H "x-api-key: $NODEXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$NODEXA_ASSISTANT_ID\",
    \"input\": \"Qual é o meu nome?\",
    \"previous_response_id\": \"$RESPONSE_ID\"
  }"

Próximos Passos