Guias principais

Construa uma integração confiável com a TokenLab

Mantenha custos, tentativas de repetição, chaves de API e registros de solicitações sob controle

Uma boa integração torna as escolhas de preço e modelo visíveis, sobrevive a falhas comuns de rede e nunca expõe uma chave de API no navegador. As práticas abaixo se aplicam a chat, imagem, vídeo, áudio e outras APIs da TokenLab.

Escolha modelos com dados atuais

Nomes de modelos, capacidades e preços mudam. Consulte a Models API ou as páginas dos modelos em vez de manter uma lista permanente no código ou na documentação.

Para um novo caso de uso:

  1. Filtre os modelos pela capacidade que seu produto precisa.
  2. Compare seus preços atuais na TokenLab.
  3. Teste um pequeno conjunto com solicitações representativas dos usuários.
  4. Mantenha o ID do modelo explícito em cada solicitação.

Não altere modelos silenciosamente. Uma substituição pode alterar a qualidade da saída, o preço, o tamanho do contexto, as ferramentas disponíveis ou o suporte a mídia.

Estabeleça um limite superior de custo

Para modelos de texto, limite a saída ao tamanho que seu produto realmente pode usar. O nome do parâmetro depende da API e do modelo, portanto, verifique a página do modelo antes de enviar max_tokens ou max_output_tokens.

Instruções mais curtas não são automaticamente melhores, mas contexto duplicado e textos padrão repetidos sempre adicionam tokens de entrada. Mantenha instruções estáveis concisas e envie apenas o histórico necessário para a próxima resposta.

Para solicitações de imagem, vídeo, música, 3D e Worlds, o custo geralmente depende da contagem de saídas, duração, resolução ou outra opção de mídia. Mostre a estimativa atual antes que um usuário confirme uma geração cara, sempre que a API puder fornecer uma.

Transmita respostas de texto longas

O streaming mostra a resposta à medida que ela chega e evita que o usuário espere pela resposta completa. Isso não reduz o custo em tokens.

Para um exemplo completo com configuração de cliente e verificações de conclusão, veja Streaming.

Trate uma desconexão como uma resposta incompleta. Não apresente uma saída parcial como concluída com sucesso e não repita uma solicitação automaticamente quando isso puder criar um segundo efeito colateral ou cobrança.

Tente novamente apenas quando for seguro

Tente novamente respostas 429 após Retry-After ou retry_after. Um curto exponential backoff é apropriado para respostas 5xx transitórias. Erros de autenticação, validação, saldo e tamanho de contexto precisam de uma alteração por parte da aplicação ou do usuário; enviar a mesma solicitação novamente não os corrigirá.

Veja Limites de taxa (Rate limits) para um exemplo de repetição limitada que respeita o Retry-After e desativa repetições duplicadas do SDK.

Defina um limite de repetições e um limite de tempo total. Para criação de mídia, salve o ID da tarefa retornado. Para as solicitações listadas em Retry safely with an idempotency key, envie uma Idempotency-Key, para que uma repetição após um tempo limite não possa executar ou cobrar a mesma solicitação duas vezes.

Mantenha as chaves de API no servidor

Nunca incorpore uma chave de API da TokenLab em JavaScript de navegador, em um pacote de aplicação móvel, em um repositório público ou em um log visível ao cliente.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
)

Use chaves de API separadas para desenvolvimento, produção e aplicações independentes. Dê a cada chave apenas os modelos e o limite de gastos de que ela precisa. Revogue uma chave imediatamente se ela puder ter sido exposta.

Mantenha registros úteis de solicitações

Armazene os identificadores que permitem conectar uma ação do usuário a registros de uso e suporte:

  • request_id para a solicitação da API
  • task_id para geração assíncrona
  • billing_transaction_id quando retornado
  • ID do modelo e endpoint
  • seu próprio ID de usuário, projeto ou trabalho

Não registre chaves de API, tokens de gerenciamento, prompts privados completos, mídia privada ou URLs assinadas. Os registros de uso no Console e na Management API são a fonte para os valores faturados; as contagens de tokens de resposta do modelo, por si só, podem não descrever a cobrança final.

Projete para trabalho assíncrono

As APIs de imagem, vídeo, música, 3D e Worlds podem retornar antes que o resultado esteja pronto. Salve o ID da tarefa, faça o polling em GET /v1/tasks/{id} e pare apenas em completed ou failed. Uma consulta de status failed não significa que a geração em si falhou.

Veja Tarefas assíncronas e polling para cancelamento, tempo limite e tratamento de solicitações duplicadas.

Antes do lançamento

  • Execute solicitações representativas com o modelo exato e o formato de API que você irá disponibilizar.
  • Verifique tanto as respostas de sucesso quanto as de erro comum.
  • Confirme se o preço exibido em seu produto corresponde ao preço atual da TokenLab.
  • Torne as atualizações, tempos limite de rede e cliques repetidos seguros.
  • Torne possível rastrear um resultado visível ao usuário de volta ao seu Request ID.

Nesta página