--- term: 'API de LLM' seoTitle: 'API de LLM: Tokens, Streaming, Tool Calling, Chave no Servidor' headline: 'O que é uma API de LLM?' slug: api-de-llm category: ai-modern-stack shortDefinition: '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.' relatedTerms: - api - api-key-security - cloud-code-serverless-functions - retrieval-augmented-generation-rag contrastsWith: - ai-agent aboutTerms: - 'Tokens' - 'Chat Completions' - 'Streaming (SSE)' - 'Tool Calling' faq: - question: 'O que é uma API de LLM?' answer: 'Um endpoint HTTP que permite ao seu código enviar um prompt a um grande modelo de linguagem hospedado e receber texto gerado de volta — sem rodar o modelo, as GPUs ou a infraestrutura de inferência por conta própria. Você faz POST de um corpo JSON, recebe uma mensagem do assistente mais a contagem de tokens usados, e paga por token.' - question: 'O que é um token e como o preço é calculado?' answer: 'Um token é um pedaço de texto — cerca de quatro caracteres ou três quartos de uma palavra em inglês. Você paga por milhão de tokens, com tarifas separadas para entrada (seu prompt) e saída (a resposta gerada). A saída tipicamente custa várias vezes mais que a entrada, porque gerar cada token exige mais computação do que ler um.' - question: 'O que é a janela de contexto?' answer: 'O número máximo de tokens — entrada mais saída — que um modelo consegue considerar numa requisição. Ela limita quanto histórico de conversa ou documento você pode incluir e é um vetor direto de custo: cada chamada paga por todo o contexto enviado, então um histórico longo ou um trecho recuperado grande é dinheiro gasto a cada requisição.' - question: 'O que é streaming e por que as UIs de chat o usam?' answer: 'Ativar a flag de stream faz a resposta chegar de forma incremental, como Server-Sent Events, em vez de um bloco final único, e a UI renderiza os tokens conforme são gerados. Ele existe pela latência percebida: o tempo até o primeiro token é uma fração do tempo até a resposta completa, então o usuário vê palavras imediatamente em vez de um spinner por vários segundos.' - question: 'O que é function calling ou tool calling?' answer: 'Você descreve as tools disponíveis — um nome e um schema JSON — na requisição; o modelo, em vez de responder em prosa, retorna uma chamada JSON estruturada nomeando uma tool e seus argumentos. Seu código a executa e devolve o resultado. O modelo nunca executa a função; apenas a solicita. Esse é o mecanismo que transforma uma API de LLM num agente.' - question: 'A API de LLM deve ser chamada do cliente ou do servidor?' answer: 'Do servidor, sempre. Uma chave de API embarcada num bundle de browser ou binário mobile está a uma inspeção da aba de rede ou a um decompile de ser roubada — e uma chave de modelo roubada é um estranho gastando o seu orçamento de tokens. Toda chamada de LLM passa pelo seu backend, com a chave na configuração do servidor.' - question: 'API de LLM ou auto-hospedar um modelo aberto?' answer: 'Uma API significa zero infraestrutura, cobrança por chamada e lançar hoje; auto-hospedar um modelo aberto (com ferramentas como Ollama, vLLM ou llama.cpp) compra controle total e residência de dados, mas só vence em custo com volume muito alto e sustentado, depois de contar GPUs e operação. A maioria dos produtos começa na API e revisita a conta na escala.' - question: 'Como lidar com rate limits e falhas?' answer: 'Os limites vêm como requisições por minuto e tokens por minuto; num 429 ou num 5xx, faça retry com backoff exponencial mais jitter e honre o header Retry-After, se houver. Não faça retry de erros 4xx — autenticação ruim, requisição malformada e recusas por política de conteúdo vão falhar de forma idêntica na segunda vez.' codeLanguages: [javascript, dart, swift, kotlin] externalAuthorities: - name: 'Server-Sent Events — WHATWG HTML Living Standard' url: 'https://html.spec.whatwg.org/multipage/server-sent-events.html' - name: 'How to call an LLM API with function calling — Martin Fowler' url: 'https://martinfowler.com/articles/function-call-LLM.html' - name: 'RFC 8259 — JSON' url: 'https://datatracker.ietf.org/doc/html/rfc8259' - name: 'Ollama — run open models locally' url: 'https://github.com/ollama/ollama' - name: 'Large language model — Wikipedia' url: 'https://en.wikipedia.org/wiki/Large_language_model' cta: title: 'O lugar certo da chamada de LLM' text: 'Coloque a chamada ao modelo numa Cloud Function do Back4app: chave no servidor, tetos de custo aplicados, resultado gravado no banco e transmitido aos clientes via Live Queries — nenhuma chave no dispositivo, nunca.' linkText: 'Comece grátis' linkUrl: 'https://www.back4app.com/signup' author: 'Back4app Engineering' publishedDate: '2026-08-21' translationKey: llm-api --- **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](/glossary/pt/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 | Pergunta | Resposta | | --- | --- | | O que é | POST de um array `messages` → resposta do assistente + contagem de tokens | | A cobrança | Por token, entrada e saída precificadas separadamente; a saída custa mais | | A pegadinha stateless | Memória é você reenviando os turnos anteriores — toda chamada, todo token pago | | A regra de ferro | Nunca chame do cliente — a chave vaza; faça proxy pelo backend | | A ponte para agentes | Tool calling — o modelo solicita uma função, seu código a executa | ## Uma chamada real, no servidor **JavaScript:** ```javascript // 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 // 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. ``` **Swift:** ```swift // 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. ``` **Kotlin:** ```kotlin // Android / Kotlin — Back4app Android SDK // The client calls YOUR function, never the LLM API directly val summary = ParseCloud.callFunction( "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: ```text POST /v1/chat/completions Authorization: Bearer { "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](/glossary/pt/rag/) grande é cobrado *de novo* em cada requisição. A fórmula mensal aproximada que vale internalizar: ```text 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 | Parâmetro | Controla | Orientação prática | | --- | --- | --- | | `temperature` | Aleatoriedade (0–2) | 0 para extração/classificação; ~0.7 para prosa | | `top_p` | Nucleus sampling | Ajuste este *ou* temperature — não os dois | | `max_tokens` | Teto do tamanho da saída | Quase sempre defina — limita custo e latência | | `stop` | Sequências de parada | Encerre a geração num delimitador que você controla | ## 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](https://html.spec.whatwg.org/multipage/server-sent-events.html) — 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](/glossary/pt/sse-vs-websockets-vs-polling/) 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](https://martinfowler.com/articles/function-call-LLM.html) é 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: | Mecanismo | Garantia | Use para | | --- | --- | --- | | Modo JSON | JSON válido — mas de qualquer formato | Necessidades soltas de "me dê JSON" | | Structured Outputs | Corresponde exatamente ao *seu* schema | Extração, classificação, dados tipados | | Tool calling | Uma chamada à *sua* função | Fazer coisas, não só formatar | Tool calling é o mecanismo que torna um [agente de IA](/glossary/pt/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 | | API de LLM hospedada | Modelo aberto auto-hospedado | | --- | --- | --- | | Infraestrutura | Nenhuma — o provedor a opera | GPUs, stack de serving, ops | | Cobrança | Por token, pague pelo uso | Capacidade fixa, sua para preencher | | Tempo para lançar | Minutos | Dias a semanas | | Residência de dados | Os termos do provedor | Totalmente sua | | Custo em volume baixo/com picos | O mais barato | GPUs ociosas queimam dinheiro | | Custo em volume extremo e sustentado | Pode exceder o self-hosting | Vence depois do break-even | 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](https://github.com/ollama/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](/glossary/pt/rate-limiting-de-api/) 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](/glossary/pt/seguranca-de-chaves-de-api/) 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](/glossary/pt/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 | Situação | Escolha | | --- | --- | | Lançar uma funcionalidade de IA agora | Uma API de LLM — zero infraestrutura | | Qualquer app voltado ao cliente | A API, chamada **no servidor** — nunca do dispositivo | | Volume extremo e sustentado | Avalie self-hosting (Ollama, vLLM) depois do break-even | | Residência de dados estrita | Auto-hospede, ou um provedor com as garantias certas | | Tarefa determinística, baseada em regras | Talvez nenhum LLM — código comum é mais barato e confiável | | O modelo precisa *fazer* coisas | Tool calling → um [agente](/glossary/pt/agente-de-ia/) | ## 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](/glossary/pt/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](/glossary/pt/cloud-code-funcoes-serverless/), 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](/glossary/pt/seguranca-de-chaves-de-api/) 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](/glossary/pt/live-queries-tempo-real/), 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.