Como começar com IA na Zenifra

Este guia mostra como gerar sua credencial, limitar o uso com budget e fazer a primeira chamada usando um cliente OpenAI-compatible.

Pré-requisitos

• uma conta na Zenifra
• acesso ao console da Zenifra
• crédito disponível, incluindo créditos promocionais quando concedidos
• um projeto Python com o pacote openai instalado
• uma variável de ambiente para guardar a chave

Passo 1: Criar a API key

No console da Zenifra, abra Modelos IA, clique em Criar Chave de API e informe um nome que identifique o ambiente, a aplicação ou a equipe que usará a chave. O nome aceita de 4 a 24 caracteres e pode conter apenas letras sem acento, números e hífen, sem espaços, como producao-api-01.

Permissões necessárias

Para usar IA por sessão de usuário, o owner tem acesso completo; assistant e member precisam dos grants da organização. Para automações, API Keys da organização usam o ID da chave de IA:

Os scopes acima são independentes: criar uma chave não deve ser tratado como autorização automática para visualizar uso de outras chaves. A chave usada pelo cliente para ai.zenifra.com é uma credencial de inferência separada da API Key da organização.

As chaves pertencem à organização, mas mantêm o vínculo com quem as criou. Ao remover um membro da organização, as chaves de IA criadas por esse membro são desativadas automaticamente.

Essa chave será usada pela sua aplicação para autenticar chamadas ao endpoint https://ai.zenifra.com/v1. O segredo será exibido somente uma vez após a criação; copie-o e guarde-o com segurança, como qualquer outro segredo de produção.

Passo 2: Definir budget e modelos permitidos

Ao criar a chave, você pode definir um limite adicional de custo e selecionar os modelos que ela poderá acessar. Esse limite nunca aumenta o crédito disponível da organização.

Esse fluxo é útil para separar uso por ambiente, equipe ou integração.

Os modelos permitidos aceitam all-team-models (todos os modelos disponíveis para a organização, o padrão) ou de 1 a 50 IDs únicos do catálogo, como zenifra/qwen3.8-flash. IDs fora do catálogo são recusados.

Gerenciar chaves pela API

As mesmas operações do console estão em https://api.zenifra.com/v1, com o cabeçalho x-organization-id e os scopes da seção anterior.

A listagem aceita page (a partir de 1, padrão 1), limit (de 1 a 50, padrão 50) e user_email para filtrar as chaves de um membro ativo; member só pode filtrar o próprio e-mail. A resposta traz o campo pagination:

{
  "status": "success",
  "data": [
    {
      "id": "6650f1c2a9b8c7d6e5f40312",
      "name": "producao-api-01",
      "models": ["zenifra/qwen3.8-flash"],
      "quota_limits": { "daily": 10, "monthly": 200 },
      "rpm": 60,
      "tpm": 100000,
      "is_active": true,
      "status": "active",
      "created_at": "2026-10-01T12:00:00.000Z",
      "expires_at": null
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 1, "pages": 1 }
}

Uma chave revogada ou com prazo de validade vencido aparece com status: "inactive". Uma chave revogada não volta a ficar ativa.

Ao alterar quotas, envie quota_limits com daily e monthly positivos; monthly precisa ser maior ou igual a daily.

Limites e erros das chaves

Cada organização pode ter até 100 chaves de IA ativas ao mesmo tempo. Chaves revogadas ou vencidas não contam.

Passo 3: Fazer a primeira requisição

Instale o SDK da OpenAI no seu projeto Python:

pip install openai

Depois, use o exemplo abaixo. Para esta documentação, vamos usar o modelo zenifra/qwen3.8-flash, se ele estiver habilitado para a sua chave no console:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://ai.zenifra.com/v1",
    api_key=os.environ["ZENIFRA_AI_API_KEY"],
)

response = client.chat.completions.create(
    model="zenifra/qwen3.8-flash",
    messages=[
        {
            "role": "user",
            "content": "Qual é a média de temperatura na região sul do Brasil?",
        }
    ],
)

print(response.choices[0].message.content)

Passo 4: Acompanhar uso e custos

No console, você consegue visualizar:

• custos diários
• custos totais
• uso por modelo
• modelos atuais
• chaves criadas

Como funciona a cobrança

O uso de IA pode ser cobrado por tokens, imagem ou outra unidade indicada no catálogo. Modelos por token podem ter preço padrão (peak), preço off-peak e faixas de preço conforme a quantidade de tokens de entrada. Consulte Preços de modelos de IA e o Console antes de publicar integrações em produção.

O consumo de IA é pré-pago e usa o crédito compartilhado da organização. Sem crédito utilizável, novas chamadas são bloqueadas. Um cartão cadastrado não libera uso adicional de IA.

Novos usuários recebem R$30,00 em crédito promocional, com vagas limitadas, enquanto a promoção estiver disponível. Esse crédito também pode ser usado com a oferta de IA.

FAQ

Preciso usar o SDK da OpenAI?

Não obrigatoriamente. O importante é usar um cliente compatível com a API da OpenAI e configurar base_url e api_key corretamente.

Onde acompanho os modelos e preços atuais?

No console, na área de Modelos IA.

Posso limitar o uso de uma chave?

Sim. O fluxo de criação da chave permite definir um budget de custo e selecionar quais modelos ela pode acessar.

Quantas chaves de IA posso criar?

Até 100 chaves ativas por organização. Revogue as chaves que não usa para liberar espaço.

Próximos passos

• IA na Zenifra
• Preços de modelos de IA
• Exemplo Node.js e TypeScript
• Streaming
• Modelos de Pagamento
• Exemplos