PT ▾
Obter chave de API

API compatível com OpenAI no n8n: Guia de configuração

Se você pesquisou por api compatível com openai n8n, a resposta curta é que você altera apenas dois valores nas credenciais do OpenAI: a URL base e a chave de API. O restante do fluxo de trabalho permanece igual ao de qualquer nó do OpenAI.

Atualizado

Fluxo de trabalho de automação isométrico com blocos conectados enviando dados para um terminal de API

Pontos principais

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:

  1. Cole sua chave no campo Chave de API.
  2. Deixe ID da Organização vazio.
  3. Substitua a URL base padrão por https://api.onekeyllmapi.com/v1. Mantenha o /v1 no final e não adicione /chat/completions.
  4. 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.

  1. Adicione um nó Gatilho Manual.
  2. 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.
  3. 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 uncensored ali. A lista pode estar vazia ou mostrar apenas nomes do OpenAI, pois o n8n filtra do lado dele.
  4. 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, valor Bearer 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.

SintomaCausa provávelCorreção
401 ao salvar ou executarChave errada ou o cabeçalho não contém BearerCole a chave novamente; no Header Auth, o valor deve começar com Bearer
404URL base com erro de digitação ou caminho extraUse exatamente https://api.onekeyllmapi.com/v1 nas credenciais
Modelo não encontradoO ID do modelo não está digitado como uncensoredMude para Por ID ou use o nó de Requisição HTTP
429 com concorrênciaMais 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ênciaA resposta é uma string ou o prompt não nomeou as chavesAnalise 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.

Perguntas e respostas

Quais nós do n8n funcionam com uma URL base personalizada?

Qualquer nó que use a credencial OpenAI pode usá-la, porque o campo URL base pertence à credencial. Se um nó não expuser um parâmetro que você precisa, use o nó de Requisição HTTP.

Por que a lista de modelos está vazia ou errada no n8n?

O n8n carrega e filtra a lista do lado dele. Digite o ID do modelo uncensored manualmente ou use o nó de Requisição HTTP, onde o modelo é apenas um campo no corpo.

Posso usar streaming no n8n?

A API suporta streaming via SSE, mas a maioria dos nós do n8n aguarda a resposta completa antes de repassar os dados. Para fluxos de trabalho, uma chamada normal sem streaming é mais simples.

Como verifico meu saldo a partir de um fluxo de trabalho?

Chame GET /v1/balance, ou leia o cabeçalho X-Balance-USD em qualquer resposta, e adicione um nó IF que alerta você quando ele cair abaixo de um limite.

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.