IA com Node.js e TypeScript
Esta página mostra exemplos práticos para chamar a API de IA da Zenifra em aplicações Node.js e TypeScript usando clientes OpenAI-compatible.
Pré-requisitos
- uma chave criada em Modelos de IA no console
- quota diária e mensal configurada para a chave, se quiser limitar o gasto
- modelo habilitado para essa chave
- Node.js 18+ ou runtime compatível com
fetch
Guarde a chave em variável de ambiente:
export ZENIFRA_AI_API_KEY="sua-chave"Permissões
A chamada de inferência usa a credencial de IA criada no console, não uma API Key da organização. Os scopes ai_key.create, ai_key.read, ai_key.update, ai_key.delete e ai_usage.read são usados para administrar a chave e consultar seu uso; eles não são enviados ao endpoint de inferência.
Exemplo com SDK da OpenAI
Instale o SDK:
npm install openaiCrie ai-example.ts:
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'https://ai.zenifra.com/v1',
apiKey: process.env.ZENIFRA_AI_API_KEY,
});
async function main() {
const response = await client.chat.completions.create({
model: 'zenifra/qwen3.8-flash',
messages: [
{
role: 'user',
content: 'Resuma em três tópicos o que é uma PaaS.',
},
],
});
console.log(response.choices[0]?.message?.content);
}
main().catch((error) => {
console.error(error);
process.exit(1);
});Troque o modelo por um ID do catálogo (GET https://ai.zenifra.com/v1/models) habilitado para sua chave.
Exemplo com curl
curl https://ai.zenifra.com/v1/chat/completions \
-H "Authorization: Bearer $ZENIFRA_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "zenifra/qwen3.8-flash",
"messages": [
{ "role": "user", "content": "Explique o que é uma API REST em uma frase." }
]
}'Tratamento de erros
Trate erros comuns antes de colocar a integração em produção.
try {
const response = await client.chat.completions.create({
model: 'zenifra/qwen3.8-flash',
messages: [{ role: 'user', content: 'Olá' }],
});
console.log(response.choices[0]?.message?.content);
} catch (error: any) {
const status = error?.status;
if (status === 401) {
throw new Error('Chave de IA inválida ou ausente.');
}
if (status === 403) {
throw new Error('Chave sem permissão para este recurso.');
}
if (status === 404) {
throw new Error('Modelo indisponível ou com nome incorreto.');
}
if (status === 429 && error?.code === 'insufficient_quota') {
throw new Error('Sem crédito na organização ou quota da chave atingida.');
}
if (status === 429) {
throw new Error('Limite de requisições excedido. Tente novamente em alguns segundos.');
}
throw error;
}Uso em produção
- use variável de ambiente para a chave
- limite cada chave com quota diária e mensal
- separe chaves por ambiente ou integração
- registre apenas IDs, status e tempos; não registre prompts sensíveis sem necessidade
- revise custos e uso por modelo no console
Próximos passos
FAQ
Posso usar JavaScript sem TypeScript?
Sim. O mesmo exemplo funciona em JavaScript removendo tipos e usando import ou require conforme seu projeto.
Preciso usar o SDK?
Não. Qualquer cliente HTTP pode chamar o endpoint OpenAI-compatible.
Onde vejo tokens e custo?
No console da Zenifra, na área de Modelos de IA.
Última atualização em