API de IA em Node JS: streaming, ferramentas e erros no Express
Este tutorial de API de IA em node js leva você de uma pasta vazia a uma rota Express que faz streaming de respostas de chat, chama uma ferramenta e trata erros de limite de requisições. Você só altera a URL base e a chave no pacote oficial OpenAI, depois envia o modelo uncensored.
AtualizadoUnfiltered AI

Pontos principais
- Instale o pacote openai e defina baseURL para https://api.unfilteredaiapi.com/v1.
- Faça streaming com stream: true e encaminhe pedaços para o navegador como eventos enviados pelo servidor.
- Chamadas de ferramenta chegam como tool_calls; retorne resultados com role tool.
- 429 significa rate_limited, concorrência ou sobrecarga temporária; tente novamente após o atraso Retry-After.
Configuração: instale e envie a primeira requisição
Você precisa do Node 18 ou mais recente. Crie um projeto, instale o SDK e o Express, e mude para módulos ES.
mkdir ai-node && cd ai-node
npm init -y
npm pkg set type=module
npm install openai express
# base URL: https://api.unfilteredaiapi.com/v1 model: uncensored
export AI_API_KEY="YOUR_KEY"
Obtenha uma chave na página de chave de API. Contas novas podem reivindicar $0,50 de crédito de teste grátis com um clique, válido por 7 dias. Depois, crie client.js:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.unfilteredaiapi.com/v1",
apiKey: process.env.AI_API_KEY,
});
const res = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Give me three names for a tavern keeper." }],
});
console.log(res.choices[0].message.content);
Execute com node client.js. Cada snippet abaixo redefine o cliente para que ele execute de forma independente. Essa é toda a migração se você já usa o pacote OpenAI: um baseURL diferente, sua chave e o ID do modelo. O serviço é compatível com OpenAI e só aceita texto, com uma janela de contexto de 100.000 tokens. Consulte a documentação para ver todos os métodos suportados.
Faça streaming da resposta
O streaming envia tokens conforme são produzidos, então os usuários veem texto imediatamente. Defina stream: true e itere sobre os chunks:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.unfilteredaiapi.com/v1",
apiKey: process.env.AI_API_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Describe a rainy harbor town." }],
stream: true,
stream_options: { include_usage: true },
});
for await (const chunk of stream) {
const delta = chunk.choices[0]?.delta?.content;
if (delta) process.stdout.write(delta);
if (chunk.usage) console.log("\nusage:", chunk.usage);
}
O uso aparece no último chunk, o que permite registrar a contagem real de tokens por requisição. Tenha em mente um fato: uma requisição em streaming ocupa sua slot de concorrência até o fim do stream. Se o cliente desconectar, aborte a chamada upstream para que o slot seja liberado rapidamente.
Uma rota Express que faz streaming para o navegador
Aqui está um pequeno servidor com a rota POST /chat. Ele encaminha o stream como eventos enviados pelo servidor e cancela a requisição upstream quando o navegador fecha a conexão.
import express from "express";
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.unfilteredaiapi.com/v1",
apiKey: process.env.AI_API_KEY,
});
const app = express();
app.use(express.json({ limit: "1mb" }));
app.post("/chat", async (req, res) => {
const { messages } = req.body;
if (Array.isArray(messages) === false) return res.status(400).json({ error: "messages required" });
res.set({
"Content-Type": "text/event-stream",
"Cache-Control": "no-cache",
Connection: "keep-alive",
});
const controller = new AbortController();
req.on("close", () => controller.abort());
try {
const stream = await client.chat.completions.create(
{ model: "uncensored", messages, stream: true },
{ signal: controller.signal }
);
for await (const chunk of stream) {
const delta = chunk.choices[0]?.delta?.content;
if (delta) res.write("data: " + JSON.stringify({ delta }) + "\n\n");
}
res.write("data: [DONE]\n\n");
} catch (err) {
res.write("data: " + JSON.stringify({ error: err.status || 500 }) + "\n\n");
} finally {
res.end();
}
});
app.listen(3000, () => console.log("listening on 3000"));
Nunca coloque a chave no código do navegador. A rota acima mantém a chave no servidor, onde ela deve estar. O mesmo padrão é mostrado em Python no artigo backend de chatbot FastAPI.
Chamar uma ferramenta
A chamada de funções segue o formato da OpenAI: você descreve funções em tools, o modelo responde com tool_calls, você executa a função e envia o resultado de volta como uma mensagem com role: "tool".
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.unfilteredaiapi.com/v1",
apiKey: process.env.AI_API_KEY,
});
const tools = [{
type: "function",
function: {
name: "roll_dice",
description: "Roll a die with the given number of sides",
parameters: {
type: "object",
properties: { sides: { type: "integer" } },
required: ["sides"],
},
},
}];
const messages = [{ role: "user", content: "Roll a d20 for my attack." }];
const first = await client.chat.completions.create({
model: "uncensored", messages, tools, tool_choice: "auto",
});
const msg = first.choices[0].message;
if (msg.tool_calls) {
messages.push(msg);
for (const call of msg.tool_calls) {
const { sides } = JSON.parse(call.function.arguments);
const result = 1 + Math.floor(Math.random() * sides);
messages.push({ role: "tool", tool_call_id: call.id, content: String(result) });
}
const second = await client.chat.completions.create({ model: "uncensored", messages, tools });
console.log(second.choices[0].message.content);
}
Sempre analise arguments dentro de um bloco try no código real, já que os modelos podem retornar JSON malformado de vez em quando. Para saída estruturada sem ferramentas, defina response_format: { type: "json_object" } e mencione JSON no seu prompt. Cenas de jogos que chamam funções de dados ou inventário são cobertas em construindo NPCs de jogos e ficção interativa.
Tratar erros e limites de taxa
A API retorna HTTP 429 em três situações. O código de erro rate_limited significa muitas requisições por minuto: 300 para uma chave completa, 60 para uma chave de teste. O código concurrency significa muitas requisições simultâneas: 8 para uma chave completa, 2 para uma chave de teste. Em sobrecarga temporária, você também recebe 429 com o cabeçalho Retry-After: 5. O SDK expõe o status no erro lançado, então um pequeno wrapper lida com os três:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.unfilteredaiapi.com/v1",
apiKey: process.env.AI_API_KEY,
});
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
export async function chatWithRetry(params, tries = 4) {
for (let i = 0; i < tries; i++) {
try {
return await client.chat.completions.create({ model: "uncensored", ...params });
} catch (err) {
if (err.status === 429 && i < tries - 1) {
const wait = Number(err.headers?.["retry-after"]) || 2 ** i;
await sleep(wait * 1000);
continue;
}
throw err;
}
}
}
O wrapper aguarda o atraso solicitado pelo servidor e recorre ao backoff exponencial. Observe que o pacote OpenAI também retenta alguns erros por conta própria; defina maxRetries no cliente se quiser controlar isso. Outros status, como 401 para uma chave inválida, não devem ser retentados. Uma análise mais detalhada dos limites está na FAQ.
Executar e testar a rota
Inicie o servidor com node server.js e teste-o de um segundo terminal. A flag -N desativa o buffering do curl para que você veja os eventos chegando um por um:
# the server calls https://api.unfilteredaiapi.com/v1 with model uncensored
curl -N http://localhost:3000/chat -H "Content-Type: application/json" -d '{"messages":[{"role":"user","content":"Write a two-line riddle."}]}'
No navegador, leia o stream com fetch e um reader, ou com uma pequena biblioteca auxiliar SSE. Como a rota é POST, o objeto nativo EventSource não se encaixa, então use fetch e decodifique os chunks você mesmo.
Hábitos de produção
- Mantenha a chave em uma variável de ambiente ou loja de segredos, nunca no repositório.
- Limite o corpo da requisição. A API aceita até 8 MB, mas sua própria rota deve aceitar muito menos.
- Limite o histórico enviado. Remova turnos antigos antes que custem dinheiro ou preencham a janela de 100.000 tokens.
- Fila ou rejeite trabalho extra quando você já tiver 8 streams abertos, em vez de deixar a API responder 429 para seus usuários.
- Registre o cabeçalho de resposta
X-Request-Id, para que o suporte possa rastrear uma única requisição.
Verificar seu saldo e custo
Toda resposta carrega o cabeçalho X-Balance-USD, e GET /v1/balance retorna o saldo diretamente. O preço é $0,15 por 1M de tokens de entrada e $0,50 por 1M de tokens de saída, cobrados do crédito pré-pago, e requisições falhas ou recusadas são gratuitas. Uma rodada de chat com 800 tokens de entrada e 250 de saída custa $0,000245, então 10.000 rodadas custam $2,45. Registre usage de cada resposta e você pode prever sua conta com margem de alguns centavos. A página de preços lista recargas de $20 a $500.
Mais guias
Perguntas e respostas
Qual pacote npm devo usar?
O pacote openai oficial funciona. Defina baseURL para https://api.unfilteredaiapi.com/v1, passe sua chave e use o ID do modelo uncensored.
Posso fazer streaming de respostas no Node?
Sim. Passe stream: true e itere com for await. Adicione stream_options com include_usage para obter contagens de tokens no último chunk.
A API suporta chamada de funções?
Sim. Envie tools e tool_choice, leia tool_calls na resposta e retorne os resultados como mensagens com role tool.
O que meu servidor deve fazer ao receber HTTP 429?
Aguarde o valor Retry-After se presente; caso contrário, use backoff exponencial e tente novamente algumas vezes. Reduza requisições simultâneas se o código de erro for concurrency.
Sua chave está a um formulário de distância
Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.