Tovanix
Tovanix

Usar o gateway de API de IA

Com uma chave de API, chame modelos de vários provedores e pague pelo uso real com o saldo da conta:

  • Crie a chave em Serviços de IA → Gateway de API → Chaves API, escolha o grupo de preços de cada provedor e, se quiser, defina um limite mensal de gastos, que pode ser alterado depois na lista de chaves
  • Os formatos de requisição OpenAI, Anthropic e Gemini são suportados; para integrar, normalmente basta trocar o endereço do gateway e a chave
  • Preço = preço oficial × multiplicador do grupo de preços; alguns grupos têm preço para o horário fora de pico
  • Um valor é reservado antes da chamada e acertado pelo uso real ao final, com débito agrupado do saldo uma vez por minuto
  • Uso e registros oferece estatísticas e o detalhamento de cada chamada

Para que serve o gateway

O gateway de API dos Serviços de IA é um ponto de acesso unificado para chamar grandes modelos: com uma chave de API, você chama modelos de vários provedores, paga pelo uso real com o saldo da conta e não precisa abrir conta nem recarregar em cada provedor.

  • SDKs oficiais funcionam como estão: integrar normalmente só exige alterar base_url e api_key, mantendo as estruturas de requisição e resposta.
  • Os formatos de requisição OpenAI, Anthropic e Gemini são suportados, inclusive entre formatos — por exemplo, chamar um modelo Claude com o SDK da OpenAI; o gateway faz a conversão automaticamente.
  • O preço é definido pelo grupo de preços: dentro de um grupo, cada modelo tem um único preço. Quando o grupo tem várias rotas e uma delas falha, a chamada passa automaticamente para a próxima rota do mesmo grupo, sem mudar o preço.

Criar uma chave de API

  • Abra a página Chaves de API: No console, vá em Serviços de IA → Gateway de API → Chaves API e clique em “Criar chave”, no canto superior direito.
  • Informe o nome, o grupo de preços e o limite mensal: Dê um nome conforme o uso, por exemplo production, test, cursor. Para cada provedor com mais de um grupo disponível, escolha um “Grupo de preços”; se não escolher, vale o grupo padrão desse provedor. Deixar o limite mensal de gastos vazio significa sem limite; informar 0 bloqueia qualquer gasto neste mês. Depois de criada a chave, o limite pode ser alterado na lista de chaves em “Alterar limite”, com verificação de identidade.
  • Verifique sua identidade: Depois de clicar em “Criar”, é preciso verificar sua identidade: com a verificação em duas etapas (2FA) ativada, informe o código dinâmico de 6 dígitos do autenticador; sem ela, informe o código enviado por e-mail. Depois da verificação, não é preciso verificar de novo para criar outras chaves ou alterar limites por 10 minutos nesta sessão.
  • Salve imediatamente a chave em texto original: A chave começa com sk-nc- e uma sequência, sendo exibida apenas uma vez porque o backend só armazena o hash. Copie para seu gerenciador de senhas antes de fechar o diálogo.

Após fechar, o texto original desaparece definitivamente — a plataforma guarda o hash, não a chave. Se não salvou, a única opção é excluir e criar outra. A exclusão é imediata e tudo que ainda usa aquela chave será desconectado.

Grupos de preços

O grupo de preços define quanto esta chave paga ao chamar os modelos de um provedor: preço = preço oficial × multiplicador do grupo. Os grupos são divididos por provedor; cada provedor tem seus próprios grupos e um grupo padrão.

  • Ao criar a chave, só é preciso escolher o grupo dos provedores que têm dois ou mais grupos; os que têm um só grupo não pedem escolha. Os provedores sem escolha usam o próprio grupo padrão.
  • A coluna “Grupo” da lista de chaves mostra o grupo e o multiplicador escolhidos para cada provedor; clique em “Trocar” para mudar, e a partir da próxima chamada a cobrança segue o novo grupo.
  • As chamadas só passam pelas rotas do grupo escolhido e nunca mudam para outro grupo; por isso, o preço de um mesmo modelo não muda quando a rota muda.

Se o grupo escolhido para um provedor for desativado, a lista mostra “Grupo desativado”, e as chamadas aos modelos desse provedor com esta chave são recusadas (HTTP 403). Basta clicar em “Trocar” e escolher outro grupo.

Faça sua primeira chamada

O endereço do gateway é o próprio domínio do console. O Painel traz exemplos curl nos formatos OpenAI, Anthropic e Gemini, e a janela exibida quando a chave é criada também mostra um, todos com o endereço do gateway já preenchido.

  • OpenAI — /v1/chat/completions — Cabeçalho Authorization, com o valor Bearer seguido da sua chave
  • Anthropic — /v1/messages — Cabeçalho x-api-key
  • Gemini — /v1beta/models/nome-do-modelo:generateContent; para streaming, :streamGenerateContent — Cabeçalho x-goog-api-key ou o parâmetro de URL ?key=
  • Com um SDK oficial, aponte base_url para o gateway e defina api_key com essa chave; o restante do código permanece igual.
  • Também há /v1/models (lista os modelos disponíveis), /v1/embeddings (vetores de texto) e /v1/images/generations (geração de imagens, cobrada por imagem), todos chamados no formato OpenAI.
  • No campo model da requisição, informe o identificador do modelo mostrado no cartão da Central de modelos. Um identificador errado ou um modelo que não está no catálogo retorna 404.

Catálogo de modelos e exibição de preços

O catálogo lista todos os modelos disponíveis por provedor e permite buscar por nome, slug, descrição ou capacidade, mostrando parâmetros como contexto e saída máxima.

  • Preço = preço oficial × multiplicador do grupo de preços. A aba “Todos” mostra os preços do grupo padrão de cada provedor; ao abrir um provedor, você pode alternar entre os grupos dele. O multiplicador no canto superior direito do cartão é o do grupo atual.
  • Modelos cobrados por token têm dois itens, entrada e saída, em valores por 1 milhão de tokens; quando há preço de leitura de cache, ele aparece em uma linha à parte. Modelos de imagem, áudio, vídeo e outros, cobrados por imagem, segundo, minuto ou chamada, mostram o preço unitário direto no cartão.
  • Alguns cartões têm uma linha “Prompts acima de” um certo tamanho, com outro preço: se o prompt de uma requisição passar desse tamanho, a requisição inteira é cobrada pelo preço dessa linha.
  • Nos modelos com a linha “Pesquisa na web” no cartão, usar a pesquisa na web do próprio modelo gera uma cobrança adicional pelo número de pesquisas.

Quando o grupo tem preço para o horário fora de pico, o cartão mostra “Fora de pico” e o multiplicador, e passar o mouse por cima mostra o horário de pico; fora do horário de pico, o preço do grupo é multiplicado por esse multiplicador, conforme o momento em que a requisição é feita. Se o cartão mostrar “Ainda não há rotas neste grupo”, ele lista os grupos em que o modelo pode ser usado; “Indisponível” significa que, no momento, nenhum grupo consegue chamá-lo.

Uso e registros

Em Serviços de IA → Gateway de API → Uso e registros, a parte de cima traz estatísticas, com períodos de 24 horas, 7 dias, 30 dias e 90 dias (7 dias por padrão); a parte de baixo traz o detalhamento das chamadas.

  • Estatísticas: número de requisições, valor cobrado, total de tokens (incluindo o cache), taxa de sucesso e latência média, além da evolução diária e dos rankings por modelo e por chave.
  • Detalhamento: horário, modelo, se foi streaming, tokens de entrada / saída / cache, valor cobrado, multiplicador, latência e status de cada chamada, com filtro por slug do modelo.
  • O detalhamento só registra chamadas que chegaram ao modelo, com status “Sucesso” ou “Erro”; registros com “Erro” não são cobrados. Requisições recusadas antes de chegar ao modelo (por exemplo, chave inválida, limite mensal atingido, saldo insuficiente ou grupo desativado) não aparecem no detalhamento — o motivo está na mensagem de erro retornada pela API.
  • A coluna “Multiplicador” mostra o multiplicador do grupo, sem o desconto do horário fora de pico; quanto foi realmente debitado em cada chamada é o que mostra a coluna “Cobrado em USD”.

Como você é cobrado

A cobrança é feita pelo uso real com o saldo da conta, sem precisar recarregar este serviço separadamente. Custo de cada chamada = preço oficial × multiplicador do grupo; se o grupo tiver horário fora de pico, nesse horário o valor ainda é multiplicado pelo multiplicador fora de pico, conforme o momento em que a requisição é feita.

  • Antes da chamada, é reservado um valor com base no tamanho da entrada e na saída máxima do modelo; ao terminar, a cobrança segue o uso real e o excedente é liberado. Se o saldo disponível não cobrir essa reserva, a resposta é de saldo insuficiente (HTTP 402), e a mensagem de erro informa quanto é preciso reservar e quanto está disponível.
  • Os custos se acumulam a cada chamada e são debitados do saldo de forma agrupada uma vez por minuto; nas faturas de Finanças, é gerada a cada hora uma linha “Uso de Serviços de IA (resumo de 1 hora)”.
  • Quando o saldo disponível cai para US$ 5 ou menos, a plataforma avisa você uma vez por mensagem no site e outros canais de notificação; se o saldo voltar a ficar acima de US$ 5 e cair de novo, você é avisado outra vez. Nesse período, as respostas da API trazem os cabeçalhos X-Tovanix-Balance-Low: 1 e X-Tovanix-Balance-Available (valor disponível no momento), que o seu programa pode usar para lembrar de recarregar com antecedência.
  • Cada chave pode ter seu próprio limite mensal de gastos, contado por mês do calendário e renovado automaticamente no mês seguinte. A verificação é feita antes de cada chamada: se o gasto do mês somado às chamadas em andamento atingir o limite, novas chamadas não passam; como a última chamada é cobrada pelo uso real, o gasto do mês pode passar um pouco do limite.

Cuidados

  • A chave em texto original aparece apenas na criação — salve-a naquele momento.
  • Excluir uma chave tem efeito imediato e não pode ser desfeito. Se quiser só pausar, clique em “Desativar” na lista; depois, é só clicar em “Ativar”.
  • Um limite mensal de 0 bloqueia completamente a chave naquele mês; não use 0 para significar ilimitado.
  • O gateway processa as requisições no nível padrão: o nível de velocidade indicado na requisição (por exemplo, speed: fast no Claude ou service_tier na OpenAI) é ignorado, e a cobrança também segue o preço padrão.
  • Ao chamar no formato Anthropic com a ferramenta de pesquisa na web, se a requisição não definir um limite de pesquisas, cada requisição faz no máximo 10 pesquisas.

Diagnóstico

  • Retorno 401, informando que a chave é inválida ou está desativada — A chave foi digitada errado, foi excluída ou está desativada — Na página Chaves API, confirme se a chave está com o status “Habilitado”; se estiver desativada, clique em “Ativar”. Uma chave excluída não pode ser recuperada — é preciso criar outra.
  • Retorno 402, informando que o limite mensal de gastos foi atingido — O gasto desta chave no mês chegou ao limite (limite 0 significa que nenhum gasto é permitido neste mês) — O acesso volta automaticamente no mês seguinte. Se não puder esperar, na página Chaves API clique em “Alterar limite” nessa chave e aumente o limite ou deixe-o vazio para ficar sem limite (exige verificação de identidade); o novo limite vale a partir da próxima chamada.
  • Retorno 402, informando saldo insuficiente — O saldo disponível não cobre o valor reservado para esta requisição — A mensagem de erro informa quanto esta requisição precisa reservar e quanto está disponível; recarregue e tente de novo.
  • Retorno 403 ou 503, informando que o grupo foi desativado ou que não há rota disponível — O grupo escolhido na chave para esse provedor foi desativado, ou o modelo está temporariamente sem rota disponível no grupo — Na página Chaves API, clique em “Trocar” e escolha outro grupo; o cartão do modelo na Central de modelos lista os grupos em que ele pode ser usado. Você também pode tentar de novo mais tarde.
  • A cobrança supera o preço do catálogo — A aba “Todos” mostra o preço do grupo padrão, mas a chave usa outro grupo; ou a chamada caiu no horário fora de pico, o prompt passou do limite de contexto longo ou houve pesquisa na web — Vale o valor cobrado em cada registro de Uso e registros.
  • Um aplicativo em produção desconecta de repente — A chave foi excluída ou desativada — Uma chave desativada volta a funcionar ao clicar em “Ativar” na lista; uma excluída só pode ser substituída por uma nova chave, que deve entrar no lugar da antiga no seu aplicativo.

Perguntas frequentes

Quanto código preciso mudar para integrar?

Normalmente só duas coisas: aponte o base_url para o gateway e troque o api_key por uma chave da plataforma. O gateway é compatível com os SDKs e protocolos oficiais, e o corpo da requisição, a estrutura da resposta e o formato de streaming continuam iguais.

Por que a cobrança é diferente do preço da Central de modelos?

A aba “Todos” mostra os preços do grupo padrão de cada provedor; se a sua chave usa outro grupo, a cobrança segue o preço desse grupo. Além disso, o desconto do horário fora de pico, a troca de preço da requisição inteira quando o prompt passa do limite de contexto longo e a cobrança adicional por pesquisa na web podem fazer o custo de uma chamada diferir do preço exibido. Vale o valor cobrado em cada registro de Uso e registros.

Como controlar os gastos de um projeto?

Crie uma chave só para esse projeto e defina um limite mensal de gastos. O limite é por chave, então os projetos não afetam uns aos outros; para ajustá-lo depois, clique em “Alterar limite” na lista de chaves (exige verificação de identidade).

Páginas relacionadas: Central de Ajuda · Guias e perguntas frequentes · Serviços de IA · Documentação da API

Carregando…