O que é uma API de LLM?

Uma API de LLM é um endpoint HTTP para um modelo de linguagem hospedado: você envia um prompt, recebe texto gerado de volta e paga por token. Ela é uma API comum com três propriedades incomuns — é stateless (você reenvia a conversa inteira a cada chamada), medida em tokens (entrada e saída precificadas separadamente) e não determinística (o mesmo prompt pode retornar textos diferentes). Domine essas três e o resto é a disciplina operacional que as páginas bem ranqueadas pulam: onde a chamada pertence, quanto ela custa e como ela falha.

Principais pontos

Uma chamada real, no servidor

// JavaScript — Cloud Code (cloud/main.js)
// The LLM call belongs server-side — the key never reaches the client
Parse.Cloud.define('summarize', async (req) => {
  const res = await Parse.Cloud.httpRequest({
    method: 'POST',
    url: 'https://api.llm-provider.example/v1/chat/completions',
    headers: {
      Authorization: `Bearer ${process.env.LLM_KEY}`, // server-side secret
      'Content-Type': 'application/json',
    },
    body: {
      model: 'default-chat',
      messages: [
        { role: 'system', content: 'Summarize in one sentence.' },
        { role: 'user', content: req.params.text },
      ],
      max_tokens: 80, // cost + latency guardrail, enforced by YOU
    },
  });
  return res.data.choices[0].message.content;
});

// Flutter / Dart — Back4app Flutter SDK
// The client calls YOUR function, never the LLM API directly
final summary = await ParseCloudFunction('summarize')
    .execute(parameters: {'text': longArticle});
print(summary.result);
// The model key stays on the server. If this app called the LLM API
// itself, the key would ship in the binary — one decompile from theft.

// iOS / Swift — Back4app Swift SDK
// The client calls YOUR function, never the LLM API directly
let summary: String = try await Cloud.run(
    name: "summarize", parameters: ["text": longArticle])
print(summary)
// The model key stays on the server. If this app called the LLM API
// itself, the key would ship in the IPA — one decompile from theft.

// Android / Kotlin — Back4app Android SDK
// The client calls YOUR function, never the LLM API directly
val summary = ParseCloud.callFunction<String>(
    "summarize", mapOf("text" to longArticle))
println(summary)
// The model key stays on the server. If this app called the LLM API
// itself, the key would ship in the APK — one decompile from theft.

O formato é portátil — a maioria dos provedores aceita o mesmo formato de chat completions, então a requisição e a resposta abaixo se leem igual, qualquer que seja o modelo apontado:

POST /v1/chat/completions            Authorization: Bearer <chave>
{ "model": "default-chat",
  "messages": [
    { "role": "system", "content": "Seja conciso." },        ← define o comportamento
    { "role": "user",   "content": "Explique tokens." } ],   ← a instrução
  "max_tokens": 200, "temperature": 0.7, "stream": false }

→ { "choices": [ { "message": { "role": "assistant",
                                "content": "Um token é…" },
                   "finish_reason": "stop" } ],
    "usage": { "prompt_tokens": 24, "completion_tokens": 118,
               "total_tokens": 142 } }        ← o que você paga

Tokens são a moeda

Um token é um pedaço de texto — cerca de quatro caracteres, ou três quartos de uma palavra em inglês. Todo o custo de uma API de LLM se reduz a contá-los, e dois fatos surpreendem. A saída custa mais que a entrada — muitas vezes várias vezes mais — porque ler o seu prompt é barato, enquanto gerar cada token da resposta é intensivo em computação, uma predição de cada vez sobre o vocabulário inteiro. E o contexto é pago a cada chamada: o modelo é stateless, então “memória” é você reenviando os turnos anteriores, e um histórico longo ou um trecho recuperado grande é cobrado de novo em cada requisição. A fórmula mensal aproximada que vale internalizar:

custo mensal ≈ ( requisições/dia
                 × (média_tokens_entrada × preço_entrada_por_M / 1_000_000
                  + média_tokens_saída  × preço_saída_por_M   / 1_000_000) )
               × 30

As alavancas que mexem nele: limite max_tokens, apare o contexto reenviado,
use um modelo menor para tarefas fáceis e faça cache de prefixos de prompt reutilizados.

Os parâmetros que importam

Streaming: por que as UIs de chat parecem rápidas

Ative a flag stream e a resposta chega de forma incremental como Server-Sent Events — linhas data:, um bloco de tokens por vez, terminando num marcador [DONE] — em vez de um blob único depois de vários segundos. A razão é perceptual: o tempo até o primeiro token é uma fração do tempo até a resposta completa, então o usuário vê palavras aparecendo em vez de um spinner girando. É texto unidirecional do servidor para o cliente sobre HTTP puro, que é exatamente o formato do SSE e precisamente por isso o streaming de LLM o usa em vez de WebSockets. A consequência no backend: seu proxy precisa fazer o stream atravessar — lendo o event stream do provedor e repassando-o — em vez de bufferizar a resposta inteira e anular o propósito.

Tool calling e saída estruturada

Duas funcionalidades transformam “texto entra, texto sai” em algo programável. Tool calling: você descreve as funções disponíveis (nome + schema JSON) na requisição e o modelo — em vez de prosa — retorna uma chamada JSON estruturada nomeando uma tool e seus argumentos; seu código a executa e devolve o resultado (o passo a passo do Fowler é a referência clara). O modelo nunca executa a função; ele apenas pede. Saída estruturada, distinta de tool calling e frequentemente confundida com ele, são três coisas que valem separar:

Tool calling é o mecanismo que torna um agente de IA possível — a mesma requisição/resposta, rodada em loop até o modelo parar de pedir tools.

API de LLM vs. auto-hospedar um modelo aberto

A leitura honesta: a API vence para quase todo mundo quase sempre — zero infraestrutura, início instantâneo e mais barata até o volume ser genuinamente grande e constante. Auto-hospedar um modelo aberto (com Ollama, vLLM ou llama.cpp) só paga seu custo operacional depois de um break-even alto, ou quando residência de dados é requisito rígido. A maioria dos produtos começa na API e revisita a pergunta se a escala um dia obrigar.

Confiabilidade: endpoints de LLM são instáveis

Trate a API de LLM como uma dependência remota lenta, limitada por taxa e que falha de vez em quando, porque é isso que ela é. Os limites chegam como requisições por minuto e tokens por minuto; exceda qualquer um e você recebe um 429. A disciplina é a mesma que toda API com rate limit exige: num 429 ou num 5xx, faça retry com backoff exponencial mais jitter e honre o Retry-After; num 4xx — autenticação ruim, requisição malformada, recusa por política de conteúdo — não faça retry, porque vai falhar de forma idêntica. Some timeouts por requisição (a geração pode travar) e lembre que uma chamada não idempotente repetida custa tokens duas vezes. Nada disso é específico de LLM; tudo isso é pulado pelos tutoriais que param no curl do caminho feliz.

A regra que os tutoriais enterram: nunca chame do cliente

O fato operacional mais importante, e o que as páginas de glossário omitem: a chamada à API de LLM pertence ao seu servidor, nunca ao browser ou ao app. Uma chave de API de modelo embarcada no cliente está a uma olhada na aba de rede ou a um decompile de binário de ser roubada — e, ao contrário de uma chave publicável vazada, uma chave de modelo roubada é um estranho com o seu orçamento de tokens e nenhum limite além da sua fatura. O padrão é a mesma disciplina de proxy que todo serviço com chave secreta precisa: o cliente chama o seu endpoint, seu backend guarda a chave na configuração do servidor e chama o modelo, e a resposta volta através de você. Esse proxy também é onde vive todo outro controle deste artigo — tetos de custo, retries, streaming, poda de prompt — e é por isso que “para onde vai a chamada?” tem uma resposta só.

Casos de uso comuns

• Resumo e extração — transforme texto longo em dados curtos e estruturados, temperature: 0.
• Chat e assistentes — respostas em streaming sobre um histórico de conversa reenviado.
• Classificação e tagging — Structured Outputs impondo o seu schema de rótulos.
• Respostas com RAG — geração ancorada em contexto recuperado, com custo administrado aparando esse contexto.
• Ações agênticas — tool calling em loop, cada tool uma função de backend com permissões.

Você deveria usar uma API de LLM? Matriz de decisão

Limitações e trade-offs

• Não-determinismo é o padrão. O mesmo prompt varia entre execuções; qualquer coisa que exija repetibilidade exata precisa de temperature: 0 e, com frequência, validação da saída.
• O custo escala com os tokens, silenciosamente. Um contexto generoso ou um max_tokens sem teto torna cara em volume uma funcionalidade barata — meça o uso, não o presuma.
• A latência é de segundos, não de milissegundos. Chamadas de LLM são lentas para os padrões da web; projete para isso com streaming, padrões assíncronos e estados de loading honestos.
• A dependência é externa e limitada por taxa. Outages e throttling do provedor são os seus outages; retries, fallbacks e cache são resiliência, não polimento.
• As saídas podem estar erradas com confiança. A API retorna texto fluente independentemente da verdade; ancoragem (RAG) e validação são como você passa a confiar nela.

APIs de LLM no Back4app

O Back4app é uma plataforma open-source de Backend as a Service (BaaS) que combina banco de dados gerenciado, APIs REST e GraphQL geradas automaticamente, autenticação, armazenamento de arquivos e funções serverless com Cloud Code. A pergunta “onde a chamada pertence” se responde sozinha aqui: dentro de uma Cloud Function, exatamente como mostram as abas de código — o cliente chama o seu summarize, a função guarda a chave do modelo na configuração do servidor e chama a API de LLM, e a chave nunca toca o dispositivo. Esse único posicionamento resolve a lista de lacunas inteira de uma vez: tetos de custo (a função define max_tokens e escolhe o modelo), retries e backoff (na função, contra o endpoint instável) e entrega de dois jeitos — retorne a resposta de forma síncrona para uma resposta única, ou grave-a no banco e deixe os clientes assistirem a ela se preencher via Live Queries, que é streaming sem um socket que você precisou construir. A API de LLM deixa de ser um risco de integração e vira mais uma chamada server-side que o seu backend já sabe fazer com segurança.