Primeiro, entenda os termos comuns de IA e provedores de IA
Ao se deparar com Key, Base URL, nome do modelo, multiplicador e códigos de erro, venha aqui primeiro para entender os termos antes de prosseguir com a integração e solução de problemas.
Termos Básicos de IA
| Termo | Explicação simples | A que os iniciantes devem prestar atenção? |
|---|---|---|
| modelo | O recurso de IA que é realmente responsável por responder a perguntas, escrever código e gerar imagens ou vídeos. | O nome do modelo deve ser copiado exatamente como está no painel do provedor; não altere maiúsculas/minúsculas, hifens ou números de versão por conta própria. |
| Grande Modelo (LLM) | Termo geral para modelos capazes de lidar com tarefas como linguagem natural, código, imagens, etc. | Mais caro não significa necessariamente mais adequado para você; diferentes modelos podem ser melhores para escrita, programação, imagens ou vídeos. |
| Multimodal | O mesmo modelo consegue processar diferentes tipos de entrada, como texto, imagens, áudio ou vídeo. | O fato de a ferramenta ter suporte a multimodal não significa que seu provedor e o modelo atual também suportem. |
| Prompt / Instrução | A solicitação que você envia para a IA, por exemplo: "Ajude-me a resumir este conteúdo." | Quanto mais específico for o prompt, mais fácil será obter resultados úteis. |
| System Prompt | Regras com prioridade mais alta que as perguntas comuns, frequentemente usadas para definir papel, estilo e limites de segurança. | System prompts em ferramentas de código afetam como os arquivos são lidos e como o código é modificado. |
| Janela de Contexto | A quantidade de conteúdo que o modelo consegue lembrar e processar de uma só vez. | Um contexto maior não significa necessariamente mais inteligência, mas é mais adequado para lidar com documentos longos, projetos grandes e conversas contínuas de vários turnos. |
| Compressão Automática / Resumo Automático | Quando a conversa ou o arquivo está prestes a exceder o limite de contexto, algumas ferramentas resumem o conteúdo anterior em uma síntese mais curta antes de continuar enviando ao modelo. | A compressão automática permite continuar a conversa, mas o resumo pode perder detalhes; ao resolver problemas, alterar código ou verificar configurações, não presuma que o modelo ainda lembra de todo o texto original. |
| Token | A unidade básica para cobrança e cálculo de tamanho no modelo; pode ser entendida a grosso modo como pequenos fragmentos em que o texto é dividido. | Tanto a entrada quanto a saída consomem tokens; documentos longos e conversas extensas aumentam significativamente os custos. |
| Temperatura | Parâmetro que controla o nível de aleatoriedade da resposta. | Se deseja estabilidade e reprodutibilidade, diminua o valor; se busca criatividade e respostas mais diversas, aumente adequadamente. |
Termos sobre Provedores de IA
| Termo | Explicação simples | A que os iniciantes devem prestar atenção? |
|---|---|---|
| Provedor de IA (relay) | Encaminha a requisição da sua ferramenta para uma ou mais plataformas de serviços de modelo. | Não é o modelo em si; o foco deve ser quais modelos ele suporta, sua estabilidade, preço e histórico de riscos. |
| provedor | Uma plataforma que oferece interfaces de IA, modelos, cobrança e gerenciamento de backend, podendo ser oficial ou um provedor intermediário. | Os endereços de API, chaves, nomes de modelos e métodos de cobrança podem variar entre diferentes provedores. |
| Canais oficiais | Serviços fornecidos diretamente pelas empresas desenvolvedoras dos modelos, como as plataformas oficiais da OpenAI, Anthropic, Google, etc. | A estabilidade e as regras são mais claras, mas pode haver barreiras de pagamento, restrições de região, preço e cotas. |
| Mirror / Proxy | Encaminha a requisição para a camada intermediária do serviço de destino. | Preste atenção redobrada à privacidade, estabilidade e se o conteúdo das requisições está sendo salvo ao ver esses termos. |
| New API / Painel com Desenvolvimento Secundário | Muitos provedores de IA criam ou modificam seus painéis a partir de sistemas open-source. | Nomes de menus podem aparecer como Token, Canal, Agrupamento, Multiplicador de Modelo, e não são necessariamente iguais aos das plataformas oficiais. |
| Canal | A rota no painel que se conecta a determinado serviço de modelo upstream. | Quando o canal apresenta instabilidade, a Key pode estar correta, mas a requisição ainda assim falhará. |
| Agrupamento de Modelos | Distribui diferentes modelos ou diferentes permissões para grupos específicos. | Se a sua chave não pertencer ao grupo correspondente, o modelo ficará indisponível ou exibirá 'model not found'. |
| Mapeamento de Modelos | O provedor mapeia um nome de exibição para o modelo real no upstream. | O nome exibido na página pode ser diferente do nome real do modelo; ao configurar, siga rigorosamente as orientações do backend. |
Campos de Configuração
| Configuração | Explicação simples | Como preencher |
|---|---|---|
| API | A aplicação chama a API do modelo. A ferramenta não abre um chat web, mas envia a pergunta ao provedor via API. | Necessário apenas se a ferramenta oferecer suporte explícito à configuração de API. |
| API Key / Key / Secret | Uma sequência de caracteres usada pela ferramenta para comprovar: "Eu sou esta conta." | Copie o conteúdo completo do painel do provedor, não tire capturas de tela públicas e não copie espaços extras. |
| Token | Como muitos provedores de IA chamam a Key em seus painéis. | Ao ver token, Token, API Key ou secret, geralmente trata-se da mesma coisa: credenciais de acesso. |
| Base URL / Endereço da API | O endereço de interface fornecido pelo provedor para que a ferramenta envie requisições ao modelo. | É o link da API; às vezes parece a página inicial de um site, às vezes precisa terminar em /v1; siga o exemplo do painel. |
| Endpoint | Outro nome para o endereço de interface. | Se vir Endpoint na documentação do provedor, geralmente procure por Endereço da API ou Base URL. |
| Provider | Item de configuração do provedor na ferramenta. | Pode ser entendido como "qual provedor, qual Key e qual endereço de API desejo usar." |
| Model / Model ID / Model Name | Informa ao provedor qual API de modelo deve ser chamada. | Copie exatamente de acordo com a lista de modelos do painel; adicione manualmente apenas se a busca automática da lista falhar. |
| Compatível com OpenAI | O formato de API do provedor segue o padrão da API da OpenAI, permitindo que muitas ferramentas usem a opção OpenAI Provider. | Ser compatível com a OpenAI não significa suportar todas as interfaces de Claude, Gemini, geração de imagens e vídeos. |
Cobrança e Limites
| Termo | Explicação simples | A que os iniciantes devem prestar atenção? |
|---|---|---|
| Saldo | O valor ou pontos que você ainda tem disponíveis para usar na conta do provedor. | Saldo insuficiente pode fazer a requisição falhar; não se trata necessariamente de um erro de configuração. |
| Multiplicador de preço | Um coeficiente de cobrança comumente usado em provedores de IA para indicar quantas vezes o preço base de um modelo será cobrado. | Quanto mais poderoso o modelo, maior o contexto ou mais complexa a tarefa com imagens e vídeos, mais alto pode ser o multiplicador. |
| Preço de entrada (Input) | O custo gerado pelo conteúdo que você envia para o modelo. | Documentos longos, códigos extensos e históricos longos de conversa aumentam os custos de entrada. |
| Preço de saída (Output) | O custo gerado pelo conteúdo da resposta do modelo. | Ao pedir ao modelo para escrever textos muito longos, o custo de saída também aumentará. |
| Concorrência | Quantas requisições podem ser iniciadas simultaneamente. | Se a concorrência for muito baixa, abrir várias ferramentas ou compartilhar a conta com outras pessoas causará filas de espera ou falhas. |
| RPM / TPM | Limite de requisições por minuto (RPM) / tokens por minuto (TPM). | Mensagens de limite de taxa geralmente indicam que as requisições estão rápidas demais ou o conteúdo está muito longo. |
| Comprimento do contexto | Quanto conteúdo uma única requisição consegue carregar no máximo. | Ao ultrapassar o limite, a ferramenta pode truncar o conteúdo, retornar erro imediatamente ou comprimir/resumir o histórico antes de continuar. |
| Cache | Provedores ou modelos reutilizam conteúdos já processados para reduzir custos ou aumentar a velocidade. | O cache nem sempre entra em vigor automaticamente nem é necessariamente gratuito; depende das regras do provedor e do modelo. |
| Preço de cache | Termo geral para custos ligados a cache; alguns sistemas detalham em preços distintos para criação, acertos (hits), leituras, etc. | Ao ver o preço de cache, confirme primeiro se trata de gravação, leitura ou se o painel combinou vários itens na exibição. |
| Preço de criação / gravação de cache | Custo cobrado ao gravar um conteúdo reutilizável no cache pela primeira vez. | Ao usar system prompts longos, documentos extensos ou contextos fixos pela primeira vez, essa taxa pode ser gerada. |
| Preço de acerto (hit) / leitura de cache | Custo cobrado quando requisições seguintes reutilizam conteúdo já armazenado no cache. | Geralmente é menor que o preço de entrada padrão, mas ainda pode haver cobrança; não assuma que o cache hit seja sempre gratuito. |
| Cache hit (Acerto de cache) | Parte do conteúdo desta requisição foi identificada pelo provedor como idêntica à anterior, reutilizando o cache diretamente. | O acerto só ocorre se atender às regras de cache do provedor, como manter o mesmo prefixo, ter comprimento suficiente e ser reutilizado dentro da validade. |
| Tempo de expiração do cache | Intervalo de tempo durante o qual o cache pode ser reutilizado. | Fazer requisições após a expiração pode gerar cobrança como entrada comum ou cobrar novamente a taxa de criação de cache. |
Termos de Erro Comuns
| Termo de erro | Significado comum | Verificação prioritária |
|---|---|---|
| 401 / Unauthorized | Falha na autenticação. | Verifique se a chave está completa, expirada ou se foram copiados espaços em branco extras. |
| 403 / Forbidden | A conta ou chave não tem permissão. | Permissões do modelo, permissões do grupo, restrições regionais, situação do saldo. |
| 404 / model not found | O modelo não existe ou a chave atual não pode usar este modelo. | Verifique se o nome do modelo foi copiado exatamente do painel e se a Key está incluída no grupo de modelos correspondente. |
| 429 / rate limit | Requisições frequentes demais ou o limite de cota foi atingido. | Concorrência, RPM, TPM, limites do provedor; tente novamente mais tarde. |
| timeout / tempo esgotado | A requisição não retornou a tempo. | Base URL, rede, status do provedor, se o modelo está na fila. |
| invalid api key | O formato da chave ou as permissões estão incorretos. | Copie a Key novamente, certificando-se de não confundir o nome de identificação/observação com a chave em si. |
| invalid base url | O endereço da interface está incorreto. | Confirme se é o endereço da API e não o endereço do console de gerenciamento; verifique se precisa de /v1 conforme indicado no painel. |
| insufficient quota | Crédito ou saldo insuficiente. | Saldo da conta, multiplicador do modelo, se a recarga já foi creditada. |
Quando não compreender a mensagem de erro, não altere várias configurações de uma só vez. Verifique na seguinte ordem: Key, Base URL, nome do modelo, saldo, permissões do modelo e status do provedor.