O que você precisa antes de começar
Uma instância do n8n (nuvem ou auto-hospedada) e uma chave de API deste serviço. Se você ainda não tem uma chave, a página chave de API orienta o processo de cadastro com Google ou e-mail e senha. Novos usuários podem resgatar $0,50 de crédito de teste com um clique na página, válido por 7 dias e sem necessidade de cartão.
Três valores são inseridos no n8n:
- URL base:
https://api.onekeyllmapi.com/v1 - Chave de API: enviada como
Authorization: Bearer <key>, o que o n8n faz para você - ID do modelo:
uncensored
O serviço é uma API LLM hospedada e apenas de texto que segue o formato de solicitação do OpenAI para /v1/chat/completions, /v1/responses e /v1/models. Não é a API oficial de nenhum fornecedor de modelo, portanto, qualquer coisa que o n8n envie para o endpoint de chat do OpenAI funciona aqui, desde que seja uma solicitação de texto.
Etapa 1: Criar a credencial
No n8n, abra Credenciais, escolha Criar credencial e pesquise por OpenAI API. Preencha assim:
- Cole sua chave no campo Chave de API.
- Deixe ID da Organização vazio.
- Substitua a URL base padrão por
https://api.onekeyllmapi.com/v1. Mantenha o/v1no final e não adicione/chat/completions. - Salve. O n8n executa uma pequena chamada de teste ao salvar; se falhar, vá para a seção de solução de problemas abaixo.
Mantenha uma credencial por ambiente. Se você executar um n8n de staging e um de produção, forneça uma chave diferente para cada um para poder ver os gastos separadamente e revogar uma sem tocar na outra.
Passo 2: Construir um fluxo de trabalho de chat simples
Comece com a menor coisa que prove a conexão: um gatilho manual e uma chamada de modelo.
- Adicione um nó Gatilho Manual.
- Adicione um nó OpenAI (ou o sub-nó OpenAI Chat Model dentro de uma Basic LLM Chain, dependendo da sua versão do n8n) e selecione a credencial do passo 1.
- Para o modelo, procure uma maneira de inserir um ID manualmente. Versões recentes do n8n oferecem um modo Por ID ao lado da lista. Digite
uncensoredali. A lista pode estar vazia ou mostrar apenas nomes do OpenAI, pois o n8n filtra do lado dele. - Adicione um prompt como Resuma este chamado de suporte em duas frases e execute o nó.
Se a sua versão do n8n insistir em escolher de uma lista, use a abordagem Requisição HTTP na próxima seção. Ela sempre funciona porque você controla toda a solicitação.
Chamando a API com o nó de Requisição HTTP
O nó Requisição HTTP é a maneira mais previsível de chamar esta API no n8n, e expõe cada parâmetro que a API aceita, incluindo seed, stop, top_p e tools. Configure-o assim:
- Método:
POST - URL:
https://api.onekeyllmapi.com/v1/chat/completions - Autenticação: Tipo de Credencial Genérica com Autenticação de Cabeçalho, nome
Authorization, valorBearer YOUR_KEY - Enviar Corpo: on, tipo de conteúdo JSON
Corpo (altere o campo para Expressão se quiser inserir dados de nós anteriores):
{
"model": "uncensored",
"messages": [
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Summarize this support ticket in two sentences."}
],
"temperature": 0.4
}
O texto da resposta está em choices[0].message.content. No próximo nó, você pode referenciá-lo com {{ $json.choices[0].message.content }}.
Para testar a mesma solicitação fora do n8n primeiro, execute isto em um terminal:
curl https://api.onekeyllmapi.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"Say hello in five words."}]}'
Se o curl funcionar e o n8n não, o problema está nas configurações do nó, não na sua chave ou saldo.
Modo JSON para fluxos de trabalho que analisam a saída
Os fluxos de trabalho quebram quando um modelo envolve dados em texto amigável. O modo JSON pede à API para retornar um objeto JSON válido, que você pode passar diretamente para um nó Set ou IF. Adicione response_format ao corpo:
{
"model": "uncensored",
"response_format": {"type": "json_object"},
"messages": [
{"role": "system", "content": "Reply only with a JSON object with keys sentiment and summary."},
{"role": "user", "content": "The delivery was late but support fixed it fast."}
]
}
Dois hábitos tornam isso confiável. Primeiro, diga a palavra JSON e nomeie as chaves no prompt, porque o modo JSON garante a sintaxe, não o seu esquema. Segundo, a resposta ainda chega como uma string em message.content, então adicione um nó Código ou uma expressão com JSON.parse() antes de ler os campos. No nó OpenAI, a mesma alteração aparece como uma opção Formato de Resposta nas opções do nó.
Tratamento de erros 429 e outros
O n8n executa itens em paralelo, então um lote de 50 linhas pode atingir os limites rapidamente. Uma chave completa permite 8 requisições simultâneas e 300 requisições por minuto; uma chave de teste permite 2 e 60. Quando você ultrapassa, a API responde com HTTP 429 e o código rate_limited (muitas por minuto) ou concurrency (muitas ao mesmo tempo). Em sobrecarga temporária, você recebe 429 com o cabeçalho Retry-After: 5.
Configurações práticas no n8n:
- Abra o nó, vá para Settings, ative Retry On Fail, defina Max Tries para 3 ou 4 e Wait Between Tries para 5000 ms.
- Coloque um nó Loop Over Items (tamanho do lote de 4 a 6) antes da chamada do modelo para ficar abaixo de 8 requisições simultâneas.
- Sob Settings do nó, On Error pode ser definido para continuar com uma saída de erro, para que uma linha ruim não interrompa a execução.
Para uma análise mais profunda dos dois tipos de limite, leia a documentação da API. Outros erros são simples: um 401 significa que a chave está errada ou o cabeçalho não contém a palavra Bearer, e um 404 geralmente significa que a URL base tem um erro de digitação ou um segmento de caminho extra.
Lista de verificação de solução de problemas
A maioria das falhas vem de uma lista curta de causas. Percorra-a de cima para baixo antes de suspeitar do serviço.
| Sintoma | Causa provável | Correção |
|---|---|---|
| 401 ao salvar ou executar | Chave errada ou o cabeçalho não contém Bearer | Cole a chave novamente; no Header Auth, o valor deve começar com Bearer |
| 404 | URL base com erro de digitação ou caminho extra | Use exatamente https://api.onekeyllmapi.com/v1 nas credenciais |
| Modelo não encontrado | O ID do modelo não está digitado como uncensored | Mude para Por ID ou use o nó de Requisição HTTP |
| 429 com concorrência | Mais de 8 execuções simultâneas (2 em uma chave de teste) | Lote com Loop sobre Itens e adicione tentativas |
| Erro de análise JSON na sequência | A resposta é uma string ou o prompt não nomeou as chaves | Analise com JSON.parse() e descreva as chaves no prompt do sistema |
Ao entrar em contato com o suporte, inclua o cabeçalho de resposta X-Request-Id da chamada com falha. No n8n, você pode ver os cabeçalhos ativando Incluir Cabeçalhos de Resposta e Status nas opções do nó de Requisição HTTP.
Testando sem gastar muito
Use o crédito de teste enquanto constrói. Com 2 requisições simultâneas e 60 requisições por minuto, uma chave de teste é lenta para lotes, mas suficiente para verificar uma credencial, um prompt e a lógica de análise. Alterne para uma chave completa quando mover o fluxo de trabalho para uma programação.
Custo e um design de fluxo de trabalho sensato
O preço é pagamento por uso: $0,15 por 1M de tokens de entrada e $0,50 por 1M de tokens de saída, a partir de crédito pré-pago. Um fluxo de trabalho que classifica 1.000 e-mails por dia com 600 tokens de entrada e 100 tokens de saída cada usa 0,6M de tokens de entrada ($0,09) e 0,1M de tokens de saída ($0,05), cerca de $0,14 por dia. Requisições falhas ou recusadas não são cobradas, então as tentativas de erro não duplicam a conta. Os detalhes estão na página de preços.
Mantenha os prompts curtos, envie apenas os campos que o modelo precisa e defina max_tokens quando souber que a resposta é breve. Se você também executar modelos na sua própria máquina, consulte o artigo sobre usar um LLM local através de uma API estilo OpenAI, que usa as mesmas configurações de cliente.
