Como Usar APIs de LLM: Tokens, Custos, Chaves e a Sua Primeira Funcionalidade de IA

Uma API de LLM é um serviço web que permite à sua app enviar texto para um grande modelo de linguagem — como os modelos GPT da OpenAI, o Claude da Anthropic ou o Gemini da Google — e receber a resposta de volta em código. Regista-se junto do fornecedor, cria uma chave de API e o servidor da sua app envia pedidos com essa chave; é cobrado por cada pedido pelo número de tokens (blocos de texto) que entram e saem. É isso que normalmente significa "acrescentar IA a uma app": um pedido bem escrito a um modelo de terceiros, feito de forma segura a partir do seu servidor.

Porque é que isto importa quando se constrói com IA

Há duas IAs diferentes numa app criada com IA, e é fácil confundi-las:

1. A IA que constrói a sua app — o agente do próprio criador, que escreve o código.
2. A IA dentro da sua app — uma funcionalidade que os seus utilizadores usam, como um assistente de conversa, um botão "resumir isto" ou a classificação automática.

A segunda chama uma API de LLM com a sua chave e fatura a sua conta no fornecedor. Perceber tokens, contexto e preços é o que lhe permite desenhar uma funcionalidade que funciona, não deixa a chave escapar e não lhe traz surpresas na fatura.

Uma analogia do dia a dia: um freelancer muito capaz, pago por palavra

Pense numa API de LLM como um escritor freelancer brilhante, com quem fala por email e a quem paga por palavra — tanto pelas palavras que lhe envia como pelas que ele escreve de volta (e as palavras que ele escreve custam mais).

• Não tem memória entre emails. Se quiser que continue uma conversa, cola as mensagens anteriores em cada novo email.
• Só consegue ler uma certa quantidade de cada vez. Esse limite é a janela de contexto.
• Quanto mais clara for a instrução, melhor e mais curta será a resposta — o que também sai mais barato.

Os conceitos principais

Tokens

Os modelos leem e escrevem texto em tokens. A documentação de preços da Anthropic estima cerca de 4 carateres, ou cerca de 0,75 palavras em inglês, por token, a partir de setembro de 2026. Modelos e línguas diferentes são tokenizados de forma diferente, por isso trate isto como um guia aproximado. Tudo conta: as suas instruções, a mensagem do utilizador, quaisquer documentos que inclua, a conversa anterior e a resposta.

Entrada e saída

Os tokens de entrada são o que envia. Os tokens de saída são o que o modelo escreve. Nas páginas de preços da OpenAI, da Anthropic e da Google, a partir de setembro de 2026, os tokens de saída custam várias vezes mais do que os de entrada para o mesmo modelo. A página de preços do Gemini da Google também indica que o "raciocínio" interno de um modelo conta como saída.

Janela de contexto

O número máximo de tokens que um modelo pode receber num único pedido, incluindo a resposta. Os modelos atuais aceitam entradas muito longas — alguns modelos atuais da Anthropic, por exemplo, aceitam até um milhão de tokens. Mas entradas longas custam mais e demoram mais, por isso envie apenas o que a tarefa precisa.

Pedidos sem estado

Com a maioria das APIs do tipo chat, cada pedido é independente por defeito. Para que um chat "se lembre", a sua app volta a enviar as mensagens anteriores a cada nova mensagem. É por isso que uma conversa longa custa mais por mensagem do que uma curta.

O prompt de sistema

Instruções que definem o papel do modelo e as regras para cada pedido: "Resume pedidos de apoio em três pontos. Nunca incluas endereços de email de clientes." Os utilizadores não o veem, mas ele molda cada resposta.

Streaming

Em vez de esperar pela resposta completa, a API pode enviar o texto à medida que é gerado, para que os utilizadores vejam as palavras aparecer de imediato. Isto faz as interfaces de chat parecer muito mais rápidas.

Como funcionam os preços

A partir de setembro de 2026, verificado nas próprias páginas de preços dos fornecedores:

Alguns fornecedores também oferecem uma forma de experimentar antes de pagar: a Anthropic dá a novos utilizadores um pequeno montante de crédito gratuito, e a API Gemini da Google tem um escalão gratuito em alguns modelos, com a ressalva de que o conteúdo enviado nesse escalão pode ser usado para melhorar os produtos da Google.

Os preços variam muito entre os modelos pequenos e rápidos de um fornecedor e os seus maiores, e mudam com frequência, por isso não os indicamos aqui. Uma estimativa simples para qualquer funcionalidade é: (tokens de entrada × preço de entrada + tokens de saída × preço de saída) × número de pedidos por mês. Depois acrescente uma margem e defina um limite mensal de gastos no painel do fornecedor.

Um exemplo prático: um botão "resumir este pedido"

Uma pequena equipa de apoio quer um botão que transforme uma longa troca de emails de um cliente em três pontos e numa resposta sugerida.

1. Obtenha uma chave. Crie uma conta com um fornecedor e gere uma chave de API. Defina um limite mensal de gastos baixo.
2. Guarde a chave como segredo no seu servidor, com um nome como ANTHROPIC_API_KEY ou OPENAI_API_KEY — nunca no código da página. Veja variáveis de ambiente e segredos.
3. Acrescente uma rota no servidor, POST /api/summarise, que:
   • verifica se a pessoa tem sessão iniciada e pertence à equipa de apoio;
   • carrega o pedido da base de dados;
   • envia ao fornecedor um prompt de sistema ("Resume em três pontos e depois redige uma resposta educada; não inventes números de encomenda") mais o texto do pedido;
   • limita o tamanho da resposta com uma definição de número máximo de tokens de saída;
   • devolve o resultado e regista quantos tokens foram usados.
4. O botão chama a sua rota, não o fornecedor, e mostra o resumo à medida que vai chegando.
5. Trate as falhas. Se o fornecedor estiver lento ou devolver um erro, mostre "Não foi possível resumir de momento" e mantenha o pedido utilizável.
6. Meça. Ao fim de uma semana, veja os registos de tokens. Se a maior parte do custo vier de cadeias de emails longas, corte o histórico citado antes de enviar.

Repare no que não é preciso: sem treinar modelos, sem infraestrutura especial. Uma chave, uma rota no servidor e um prompt bem escrito.

Termos-chave

• Chave de API: o segredo que identifica a sua conta junto do fornecedor. Quem a tiver pode gastar o seu dinheiro.
• Modelo: o LLM específico que chama. Os fornecedores oferecem vários tamanhos a preços e velocidades diferentes.
• Temperatura: uma definição do grau de variação das respostas. Quanto mais baixa, mais previsível.
• Máximo de tokens: um limite para o tamanho da resposta, que também limita o custo.
• Limite de pedidos (rate limit): quantos pedidos ou tokens a sua conta pode usar por minuto.
• Embeddings: números que representam o significado de um texto, usados para pesquisar nos seus próprios documentos.
• RAG (geração aumentada por recuperação): encontrar passagens relevantes dos seus próprios dados e incluí-las no prompt, para que o modelo responda com base no seu conteúdo.
• Uso de ferramentas / chamada de funções: permitir que o modelo peça à sua app para executar uma função específica, como "consultar o estado de uma encomenda".

Erros comuns e ideias erradas

• Colocar a chave no código do frontend. O erro mais caro. O código do navegador é público. Chame sempre a partir do seu servidor. A lista de verificação de segurança para apps criadas com IA abrange isto junto com outras verificações de lançamento.
• Sem limite de gastos nem limites por utilizador. Um erro, um ciclo ou um utilizador abusivo pode aumentar os custos rapidamente. Defina um limite no fornecedor e limite os pedidos por utilizador na sua app.
• Enviar tudo em todos os pedidos. Documentos inteiros e históricos de chat completos multiplicam os tokens de entrada. Corte, resuma as mensagens mais antigas ou recupere apenas as partes relevantes.
• Confiar cegamente na saída. Os modelos podem afirmar coisas erradas com confiança. Para factos, preços ou qualquer assunto jurídico ou médico, baseie as respostas nos seus próprios dados e mostre as fontes, ou peça a uma pessoa que verifique.
• Deixar que o input do utilizador anule as suas regras. Os utilizadores podem escrever "ignora as tuas instruções". Mantenha as permissões e as ações sensíveis no código do servidor, não apenas no prompt.
• Começar pelo maior modelo. Experimente primeiro um modelo mais pequeno e mais barato; suba apenas se a qualidade o exigir.
• Enviar dados pessoais sem pensar. Verifique os termos de utilização de dados do fornecedor, sobretudo nos escalões gratuitos, e envie apenas o que a funcionalidade precisa.

O que pedir ao seu criador de IA

Acrescente um botão "Resumir" na página do pedido. Chama uma rota no servidor que usa o segredo OPENAI_API_KEY (nunca exposto ao navegador), verifica se o utilizador tem sessão iniciada, envia o texto do pedido com este prompt de sistema: […], limita a resposta a 300 tokens, transmite a resposta para a página e mostra um erro amigável se a chamada falhar. Registe os tokens usados por pedido e limite cada utilizador a 30 resumos por hora.

Para uma experiência de chat completa, veja como criar uma app de chatbot com IA; para outras ideias, como acrescentar funcionalidades de IA à sua app. Se as APIs em geral forem novidade para si, comece por o que é uma API.

APIs de LLM em apps criadas com o Mythex

Quando constrói com o Mythex, a IA dentro da sua app usa a sua própria chave do fornecedor. Adiciona-a como segredo do projeto, ou através do cartão de segredos que o Mythex mostra no chat quando precisa dele, e pede ao agente para fazer a chamada no servidor. O consumo do fornecedor é faturado na sua conta do fornecedor, não aos créditos de construção do Mythex. O Mythex não inclui tokens para os utilizadores da sua app nem um produto de base de conhecimento incorporado, e os limites de pedidos e os controlos de custos são seus para desenhar e testar. A receita de documentação acrescentar funcionalidades de IA com as suas próprias chaves de API tem um prompt inicial, e a página criador de apps com IA mostra por onde começar.

Perguntas