PT ▾
Obter chave de API

Best LLM API Guia

Como usar uma API LLM: da primeira chamada ao streaming

Usar uma API LLM significa enviar uma lista JSON de mensagens via HTTPS e ler a resposta. Este guia leva você de uma chave à primeira requisição, depois ao streaming, saída JSON e chamadas de ferramentas.

Atualizado:

Pacote de requisição brilhante viajando de um terminal para um servidor e tokens de streaming de volta

Pontos principais

  • O endpoint é compatível com OpenAI: altere a base URL e a chave, mantenha seu SDK.
  • Use o ID do modelo uncensored e POST para /v1/chat/completions.
  • Streaming, modo JSON e chamada de funções são todos suportados.
  • Um 429 significa desacelerar; leia o código de erro para saber o motivo.

O que é uma chamada de API LLM

Se você se pergunta como usar serviços de API LLM, a ideia é simples. Você envia um POST HTTPS com uma lista de mensagens. Cada mensagem tem um role (system, user ou assistant) e algum texto. O servidor executa o modelo e envia de volta a próxima mensagem do assistant. Esse é todo o contrato.

O modelo não tem memória entre chamadas. Se você quer uma conversa, envie as mensagens anteriores novamente a cada vez. É por isso que os prompts crescem, por que o custo cresce com eles, e por que a janela de contexto de 100.000 tokens importa: é o limite para prompt mais resposta juntos.

Este serviço usa o mesmo protocolo da API OpenAI Chat Completions. Qualquer SDK OpenAI ou cliente compatível funciona assim que você altera duas coisas, a base URL e a chave. Apenas texto entra e sai. Não há geração de imagem, áudio ou vídeo e não há endpoint de embeddings.

Alguns termos são usados ao longo do restante deste guia. Um token é um pedaço de texto, aproximadamente três quartos de uma palavra em inglês em média. Tokens de entrada são tudo que você envia, e tokens de saída são o que o modelo escreve. Você é cobrado por ambos, a taxas diferentes, e a resposta diz exatamente quantos de cada ela usou. Uma base URL é o endereço que seu cliente adiciona a cada caminho, e uma chave de API é o segredo que prova que a requisição é sua. Se você conhece essas quatro palavras, o resto é rotina.

Passo 1: obter uma chave e anotar três valores

Crie uma conta com Google, ou com um email e senha, e abra a página da chave de API. Lá você pode copiar sua chave e resgatar o crédito de teste de $0,50 com um clique. Não é necessário cartão para o teste.

Você precisa de três valores para cada requisição:

  • Base URL: https://api.bestllmapi.com/v1
  • ID do modelo: uncensored
  • Cabeçalho de autenticação: Authorization: Bearer YOUR_KEY

Mantenha a chave fora do controle de código-fonte. Coloque-a em uma variável de ambiente como LLM_API_KEY e leia-a de lá. Qualquer pessoa que tiver a chave pode gastar seu crédito.

Passo 2: enviar uma primeira requisição com curl

O Curl é a verificação mais rápida de que tudo funciona, antes de qualquer biblioteca estar envolvida.

export LLM_API_KEY="paste-your-key-here"

curl https://api.bestllmapi.com/v1/chat/completions \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Explain what a token is in two sentences."}
    ],
    "temperature": 0.7
  }'

A resposta é JSON. O texto está em choices[0].message.content, e um objeto usage lista tokens de prompt e completion, que é a base da sua cobrança. Você também pode listar modelos com GET https://api.bestllmapi.com/v1/models; você deve ver uncensored.

Os cabeçalhos da resposta também ajudam. X-Request-Id identifica a chamada se você entrar em contato com o suporte, e X-Balance-USD mostra o que resta na sua conta.

Lendo a resposta e escolhendo parâmetros

Uma resposta tem alguns campos que vale conhecer antes de escrever qualquer código de parsing. choices é uma lista, e você quase sempre quer o primeiro item. Dentro dele, message.content contém o texto, e finish_reason diz por que o modelo parou. Um valor de stop significa que terminou naturalmente. Um valor de length significa que atingiu o limite max_tokens ou ficou sem janela de contexto, então a resposta pode ser cortada no meio da frase.

O objeto usage fornece tokens de prompt, tokens de conclusão e um total. Registre isso para cada chamada desde o primeiro dia. É a única maneira confiável de aprender quanto seu app realmente custa, e facilita detectar um bug que envia o mesmo prompt longo duas vezes.

Escolher parâmetros é principalmente uma questão de tipo de tarefa. Para extração, classificação e código, use uma temperatura baixa como 0,2, para que a mesma entrada dê quase a mesma saída. Para brainstorming e histórias, 0,8 a 1,0 dá mais variedade. Altere um valor de cada vez, e use seed quando quiser comparações repetíveis entre duas versões de prompt.

Passo 3: usar o SDK OpenAI em Python ou Node

Na prática você usará uma biblioteca. Em Python, instale com pip install openai e aponte para a URL base nova.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.bestllmapi.com/v1",
    api_key=os.environ["LLM_API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Give me three names for a hiking app."},
    ],
    temperature=0.8,
    max_tokens=200,
)

print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

A versão Node é quase idêntica. Instale com npm install openai.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.bestllmapi.com/v1",
  apiKey: process.env.LLM_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Give me three names for a hiking app." }],
});

console.log(resp.choices[0].message.content);

max_tokens é opcional. Se você não o definir, a resposta pode usar o que sobrar da janela de 100.000 tokens, então defina-o quando quiser respostas curtas. As configurações de amostragem temperature, top_p, stop, seed e as penalidades são passadas para o modelo.

Passo 4: transmitir a resposta

Sem streaming, seu usuário encara uma tela em branco até que toda a resposta esteja pronta. Com stream: true o servidor envia tokens via Server-Sent Events conforme são produzidos, e os totais de uso chegam no final.

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.bestllmapi.com/v1", api_key=os.environ["LLM_API_KEY"])

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Write a short product description for a desk lamp."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if getattr(chunk, "usage", None):
        print("\nTokens:", chunk.usage.total_tokens)

Uma coisa a lembrar: uma requisição streaming ocupa seu slot de concurrency até o stream terminar. Uma chave completa permite 8 requisições simultâneas, uma chave de teste 2. Se um usuário fechar a aba, feche o stream do seu lado também, ou o slot fica ocupado.

Mantendo uma conversa

Como a API não tem memória, um aplicativo de chat é um loop que adiciona a uma lista. O padrão abaixo é o núcleo de quase todos os chatbots.

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.bestllmapi.com/v1", api_key=os.environ["LLM_API_KEY"])

messages = [{"role": "system", "content": "You are a friendly travel planner."}]

while True:
    user_text = input("You: ")
    if user_text.strip().lower() in ("quit", "exit"):
        break
    messages.append({"role": "user", "content": user_text})
    resp = client.chat.completions.create(model="uncensored", messages=messages)
    answer = resp.choices[0].message.content
    messages.append({"role": "assistant", "content": answer})
    print("Bot:", answer)

Cada etapa reenvia a lista inteira, então o custo por turno aumenta conforme o chat fica mais longo. O preço é $0,15 por 1M de tokens de entrada e $0,50 por 1M de tokens de saída. Um turno com 2.000 tokens de entrada e 400 tokens de saída custa 2.000 / 1.000.000 x $0,15 = $0,0003 mais 400 / 1.000.000 x $0,50 = $0,0002, totalizando $0,0005. Nesse ritmo, o crédito de teste de $0,50 cobre cerca de 1.000 turnos.

Quando a lista fica longa, remova as mensagens mais antigas de user e assistant, mas mantenha a mensagem system no topo. Ou peça ao modelo para escrever um resumo curto dos turnos iniciais e substitua-os por ele.

Passo 5: modo JSON e chamada de ferramentas

Quando seu código precisa analisar a resposta, peça JSON. Defina response_format para {"type": "json_object"} e também diga "JSON" no prompt para que o modelo saiba que formato você quer.

import os, json
from openai import OpenAI

client = OpenAI(base_url="https://api.bestllmapi.com/v1", api_key=os.environ["LLM_API_KEY"])

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply only with JSON."},
        {"role": "user", "content": "Extract name and city: 'Maria lives in Lisbon.' Use keys name and city."},
    ],
)
print(json.loads(resp.choices[0].message.content))

Chamada de funções permite que o modelo peça para seu código executar uma função. Você descreve a função em tools; o modelo responde com uma entrada tool_calls em vez de texto; você executa a função e envia o resultado de volta com role: "tool".

import os, json
from openai import OpenAI

client = OpenAI(base_url="https://api.bestllmapi.com/v1", api_key=os.environ["LLM_API_KEY"])

tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "Look up an order by its id",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
}]

messages = [{"role": "user", "content": "Where is order A-1042?"}]
first = client.chat.completions.create(
    model="uncensored", messages=messages, tools=tools, tool_choice="auto"
)
msg = first.choices[0].message

if msg.tool_calls:
    call = msg.tool_calls[0]
    args = json.loads(call.function.arguments)
    result = {"order_id": args["order_id"], "status": "shipped"}
    messages.append(msg)
    messages.append({
        "role": "tool",
        "tool_call_id": call.id,
        "content": json.dumps(result),
    })
    final = client.chat.completions.create(
        model="uncensored", messages=messages, tools=tools
    )
    print(final.choices[0].message.content)

Modelos podem produzir argumentos malformados às vezes, então envolva json.loads em um bloco try no código real e envie um erro de volta como resultado da ferramenta se a análise falhar.

Quando algo dá errado

A maioria dos problemas do primeiro dia é uma dessas.

  • 401 ou erro de autenticação: a chave está faltando, tem um erro de digitação, ou o cabeçalho não está no formato Bearer KEY.
  • 404: a base URL está faltando /v1, ou você chamou o caminho errado. O caminho de chat é /v1/chat/completions.
  • 429 com código rate_limited: você passou o limite de requisições por minuto (300 em uma chave completa, 60 em uma chave de teste).
  • 429 com código concurrency: muitas requisições ao mesmo tempo (8 em uma chave completa, 2 em uma chave de teste). Coloque suas chamadas em fila.
  • 429 com Retry-After: 5: sobrecarga temporária. Aguarde cinco segundos e tente novamente.
  • Requisição muito grande: o limite do corpo da requisição é 8 MB, e prompt mais resposta devem caber em 100.000 tokens.

Requisições falhas ou recusadas não são cobradas, então tentar novamente cuidadosamente não custa nada a mais. Para cada código de erro e mais exemplos, leia a documentação, e veja preço para estimar quanto uma carga de trabalho custa a $0,15 por 1M tokens de entrada e $0,50 por 1M tokens de saída.

Tentando novamente educadamente no código

Um script que envia muitas requisições eventualmente encontrará um 429. A correção é um pequeno wrapper de retry que espera e tenta novamente. Esta versão respeita a pausa de cinco segundos que a API pede em sobrecarga temporária.

import os, time
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api.bestllmapi.com/v1", api_key=os.environ["LLM_API_KEY"])

def ask(prompt, tries=5):
    for attempt in range(tries):
        try:
            r = client.chat.completions.create(
                model="uncensored",
                messages=[{"role": "user", "content": prompt}],
            )
            return r.choices[0].message.content
        except RateLimitError:
            time.sleep(5 * (attempt + 1))
    raise RuntimeError("still rate limited after retries")

print(ask("List three uses for a paperclip."))

Se você executa muitas requisições em paralelo, limite a contagem de workers ao seu limite de concurrency. Um pool de threads de 8 corresponde a uma chave completa, e 2 corresponde a uma chave de teste. Passar disso gera apenas erros concurrency.

Perguntas e respostas

Preciso de um SDK especial?

Não. Qualquer SDK OpenAI ou cliente compatível com OpenAI funciona. Defina a base URL para https://api.bestllmapi.com/v1, use sua chave e defina o modelo para uncensored.

Posso testar antes de pagar?

Sim. Novos usuários podem obter $0,50 de crédito de teste com um clique na página da chave de API. Não precisa de cartão e é válido por 7 dias.

A API lembra mensagens anteriores?

Não. Envie o histórico da conversa na lista de messages em cada requisição. O prompt mais a resposta devem caber na janela de contexto de 100.000 tokens.

O que significa o erro 429?

Você atingiu um limite. O código rate_limited significa muitas requisições por minuto, concurrency significa muitas ao mesmo tempo, e um cabeçalho Retry-After significa sobrecarga breve.

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.

Obter chave de API