Como Trabalhar com a API Cohere

A Cohere oferece aos desenvolvedores acesso a sofisticados Modelos de Linguagem Grande (LLMs) capazes de entender e gerar texto semelhante ao humano. Para interagir com estes modelos de forma programática, você precisa de uma chave de API. Essa chave atua como seu identificador único e senha, permitindo que os sistemas da Cohere autentiquem suas solicitações e acompanhem seu uso.

Este guia irá orientá-lo através das etapas essenciais: obtendo sua chave de API, entendendo as diferenças críticas entre os tipos de chave (especialmente em relação a custos e limites de uso), e realizando um teste inicial simples usando a ferramenta Apidog para garantir que sua chave está funcionando corretamente.

Etapa 1: Obtendo Sua Chave de API da Cohere

Obter sua chave é o primeiro e mais crucial passo. A Cohere torna esse processo relativamente simples através do seu painel online.

Navegue até o Painel da Cohere: Abra seu navegador e vá para o ponto de acesso principal da plataforma da Cohere. Você normalmente encontrará uma página de login ou cadastro.
Acesse Sua Conta:

Se você já tem uma conta na Cohere, faça login usando suas credenciais.
Se você é novo na Cohere, precisará se inscrever para uma conta. Siga o processo de registro, que geralmente envolve fornecer um endereço de e-mail e definir uma senha.

Localize a Seção de Chaves de API: Após fazer login com sucesso no painel da Cohere, procure uma seção especificamente dedicada à gestão de Chaves de API. Isso pode estar nas configurações da conta, em uma seção para desenvolvedores, ou acessível diretamente por um item de menu rotulado como "Chaves de API". A interface é projetada para ser amigável, então deve ser relativamente visível.

Inicie a Geração da Chave: Dentro da seção de Chaves de API, você encontrará uma opção para criar uma nova chave. Você provavelmente verá opções diferenciando entre tipos de chave, notavelmente "Chave de Avaliação" e potencialmente "Chave de Produção". Para testes iniciais e aprendizado, selecione a opção para gerar uma Chave de Avaliação.

Atribua um Nome: Um prompt solicitará que você nomeie sua chave. Escolha um nome descritivo que ajude você a lembrar seu propósito mais tarde, especialmente se você gerar várias chaves para diferentes projetos. Exemplos incluem "MinhaPrimeiraChaveDeTeste", "ChaveDoProjetoDeAprendizado" ou "ChaveTesteApidog".

Gere e Proteja Sua Chave: Clique no botão para confirmar e gerar a chave (por exemplo, "Gerar Chave de Avaliação"). A Cohere exibirá então sua nova chave de API gerada. Este é o único momento em que a chave completa será mostrada. É absolutamente essencial que você copie esta chave imediatamente e a armazene em um local muito seguro, como um gerenciador de senhas ou uma nota segura. Trate-a com o mesmo nível de segurança que uma senha. Não a compartilhe publicamente, não a insira diretamente em código do lado do cliente ou a faça commit em sistemas de controle de versão como Git. Uma vez que você feche a janela pop-up ou navegue para longe, não poderá recuperar a chave completa novamente por razões de segurança (embora você possa ver o nome da chave e potencialmente seus primeiros/últimos caracteres no painel). Se você perdê-la, precisará gerar uma nova.

Com sua chave de API copiada e protegida, você está pronto para entender o que pode fazer com ela e as regras associadas.

Etapa 2: Entendendo os Tipos de Chave, Custos e Limites de Uso

Nem todas as chaves de API da Cohere são criadas iguais. O tipo de chave que você tem determina quanto você pode usar a API, com que rapidez e se isso gera custos. Entender essas diferenças é vital para evitar interrupções ou cobranças inesperadas.

A. Chaves de API de Avaliação: Grátis para Avaliação

Quando você se inscreve pela primeira vez ou gera uma chave sem configurar a cobrança, normalmente você recebe uma Chave de Avaliação. Estas são projetadas para exploração, aprendizado e testes em pequena escala.

Custo: As chaves de avaliação são grátis para usar. Você não será cobrado pelo uso associado a uma chave de avaliação.
Limite Geral de Uso: A restrição mais significativa é um limite mensal de 1.000 chamadas de API no total em todos os endpoints da Cohere combinados. Isso significa que cada solicitação que você faz (seja para Chat, Embed, Rerank, etc.) conta para este total mensal. Depois de atingir 1.000 chamadas em um mês civil, sua chave deixará de funcionar até o início do próximo mês.
Limites de Taxa (Solicitações por Minuto - RPM): Para garantir uso justo e estabilidade do sistema, as chaves de avaliação também têm limites de taxa rigorosos, restringindo quantas solicitações você pode enviar dentro de uma janela de um minuto para endpoints específicos. Estes são cruciais para estar ciente, pois excedê-los resultará em erros 429 Muitas Solicitações. Os limites de taxa das chaves de avaliação incluem:
Endpoint de Chat (/v2/chat): 20 solicitações por minuto. Este é o endpoint usado para IA conversacional, geração de texto, sumarização, etc.
Endpoint de Embed (/v2/embed) - Texto: 100 solicitações por minuto. Usado para gerar embeddings vetoriais para dados textuais (busca semântica, clustering).
Endpoint de Embed (/v2/embed) - Imagens: 5 solicitações por minuto. Usado para gerar embeddings vetoriais para dados de imagem (busca multimodal).
Endpoint de Rerank (/v2/rerank): 10 solicitações por minuto. Usado para melhorar a relevância da classificação dos resultados de busca.
Endpoint de Tokenize (/v2/tokenize): 100 solicitações por minuto. Usado para ver como o texto é dividido em tokens pelos modelos da Cohere.
Endpoint de Classify (/v1/classify): 100 solicitações por minuto. Usado para tarefas de classificação de texto (legado, ajuste fino preferido agora).
Endpoints Legados (Sumarizar, Gerar): 5 solicitações por minuto.
Outro/Padrão: Limites podem ser aplicados a outros endpoints menos comuns ou de gerenciamento.

As chaves de avaliação são ideais para:

Aprender como a API da Cohere funciona.
Experimentar diferentes modelos e parâmetros no Playground ou por chamadas diretas.
Construir pequenos projetos pessoais ou protótipos com uso limitado esperado.
Avaliar as capacidades da Cohere antes de se comprometer com um uso pago.

Se você constantemente atingir o limite mensal ou os limites de taxa por minuto, é um forte indicativo de que você precisa atualizar para uma chave de produção.

B. Chaves de API de Produção: Para Construir e Escalar

Quando estiver pronto para construir aplicativos com usuários reais, lidar com cargas de trabalho maiores ou ir além das limitações da avaliação, você precisará de uma Chave de Produção. Isso requer a configuração de informações de cobrança em sua conta da Cohere.

Custo: As chaves de produção operam em um modelo pague conforme o uso, baseado principalmente em uso de tokens. Tokens são unidades de texto (aproximadamente correspondendo a palavras ou partes de palavras) que os modelos processam. Você é cobrado tanto pelos tokens que você envia para o modelo (tokens de entrada) quanto pelos tokens que o modelo gera em sua resposta (tokens de saída).
Os Preços Variam Por Modelo: Modelos mais poderosos geralmente custam mais por token do que modelos mais leves e rápidos.
Exemplo de Preços (Ilustrativo - confira a página oficial de preços da Cohere para taxas atuais):
Modelo Command R: Pode custar cerca de $0,50 por milhão de tokens de entrada e $1,50 por milhão de tokens de saída. (Nota: O resultado de pesquisa anterior indicou $2,50 de entrada / $10,00 de saída para o Command R - usando esses valores: $2,50 / 1M tokens de entrada, $10,00 / 1M tokens de saída.)
Modelo Command R+: Sendo mais capaz, provavelmente teria um preço mais alto, talvez $3,00 por milhão de tokens de entrada e $15,00 por milhão de tokens de saída.
Modelos de Embed (por exemplo, embed-english-v3.0): Modelos de embedding são normalmente precificados apenas em tokens de entrada, pois não geram saídas de texto longas. O preço pode ser em torno de $0,10 por milhão de tokens de entrada.
Cálculo de Tokens: A Cohere fornece um endpoint Tokenizer e documentação para ajudá-lo a entender como o texto é traduzido em tokens para uma estimativa de custo precisa. Entradas e saídas mais longas naturalmente custam mais.
Limite Geral de Uso: Não há limite mensal total de chamadas para chaves de produção. Você pode fazer quantas chamadas forem necessárias, desde que permaneça dentro dos limites de taxa e gerencie seus custos.
Limites de Taxa (Solicitações por Minuto - RPM): As chaves de produção se beneficiam de limites de taxa significativamente mais altos, permitindo que os aplicativos lidem com muito mais tráfego:
Endpoint de Chat (/v2/chat): 500 solicitações por minuto (comparado a 20/min para Avaliação).
Endpoint de Embed (/v2/embed) - Texto: 2.000 solicitações por minuto (comparado a 100/min).
Endpoint de Embed (/v2/embed) - Imagens: 400 solicitações por minuto (comparado a 5/min).
Endpoint de Rerank (/v2/rerank): 1.000 solicitações por minuto (comparado a 10/min).
Endpoint de Tokenize (/v2/tokenize): 2.000 solicitações por minuto.
Endpoint de Classify (/v1/classify): 1.000 solicitações por minuto.
Aumentos de Limite de Taxa: Para aplicativos de volume muito alto, pode ser possível solicitar aumentos adicionais de limite de taxa entrando em contato com o suporte da Cohere.

As chaves de produção são necessárias para:

Desenvolver e implantar aplicativos destinados a usuários finais.
Lidar com volumes consistentes ou altos de solicitações de API.
Qualquer caso de uso comercial.
Desbloquear todo o potencial de desempenho sem ser restringido por limites de avaliação.

C. Escolhendo a Chave Certa:

Comece com Avaliação: Sempre comece com uma chave de avaliação para aprendizado e desenvolvimento inicial.
Monitore o Uso: Fique de olho em seu volume e frequência de chamadas.
Atualize Quando Necessário: Se seu aplicativo consistentemente atingir limites de taxa, exceder o limite mensal de 1.000 chamadas ou se você estiver se preparando para um lançamento público ou comercial, atualize para uma chave de produção adicionando detalhes de cobrança no painel da Cohere.

Ok, aqui está a seção revisada da Etapa 3 focando no teste da solicitação de chat em streaming fornecida no comando curl usando o Apidog, apresentada em Markdown:

Etapa 3: Realizando uma Chamada de Teste Básica da API para Chat em Streaming com Apidog

Antes de integrar a API em um código complexo, especialmente para respostas em streaming, é útil realizar um teste direto. O Apidog permite que você replique a estrutura do comando curl para verificar sua chave e entender o fluxo básico de solicitação/resposta para streaming.

Inicie o Apidog: Abra o aplicativo Apidog em seu computador.
Crie uma Nova Solicitação: Clique no botão '+' ou equivalente para criar uma nova solicitação de API. Nomeie algo descritivo, como "Teste de Chat em Streaming da Cohere".
Configure o Endpoint:

Método HTTP: Selecione POST.
URL: Insira a URL do endpoint de Chat da Cohere v2: https://api.cohere.ai/v2/chat

4. Configure os Cabeçalhos:

Navegue até a aba "Cabeçalhos". Você precisará adicionar vários cabeçalhos com base no comando curl:
Accept: Chave: Accept, Valor: application/json
Content-Type: Chave: Content-Type, Valor: application/json
Authorization: Chave: Authorization, Valor: Bearer SUA_CHAVE_API (Substitua SUA_CHAVE_API pela sua chave de API da Cohere real. Certifique-se de que haja um espaço após Bearer).

5. Construa o Corpo da Solicitação (com Streaming Habilitado):

Vá até a aba "Corpo".
Selecione a opção para entrada "raw".
Escolha JSON como formato.
Cole o seguinte payload JSON, espelhando os dados do comando curl, incluindo a crucial flag "stream": true:

{
  "stream": true,
  "model": "command-r",
  "messages": [
    {
      "role": "user",
      "content": "Olá mundo!"
    }
  ]
}

(Nota: O exemplo curl usou "role": "user" (minúsculo) e modelo "command-a-03-2025". Eu mantive "role": "USER" e modelo "command-r" para consistência com os exemplos anteriores, mas você deve ajustar o modelo e a capitalização do papel no JSON acima para corresponder precisamente à solicitação específica que você pretende testar, se for diferente.)

6. Execute a Solicitação: Clique no botão "Enviar" no Apidog.

7. Analise a Resposta (Especificidades de Streaming):

Código de Status: Você ainda deve receber um código de status 200 OK se a solicitação inicial for aceita pelo servidor.
Cabeçalhos de Resposta: Verifique os cabeçalhos de resposta em busca de sinais de streaming, como Transfer-Encoding: chunked.
Corpo da Resposta: Como o Apidog exibe a resposta em streaming pode variar. Ele pode:
Aguardar até que o stream seja concluído e mostrar o texto totalmente concatenado ou o payload final do evento.
Mostrar os chunks brutos ou Eventos Enviados pelo Servidor (SSE) à medida que eles chegam, parecendo potencialmente com múltiplos objetos JSON um após o outro.
Provavelmente não renderizará o texto suavemente token por token como um aplicativo projetado para isso.
Conteúdo: Confira o conteúdo do corpo da resposta. Você deve ver eventos relacionados ao stream, como eventos de text-generation contendo partes da resposta "Olá mundo!", e eventualmente um evento stream-end indicando que o processo foi concluído.
Erros: Se você receber erros (401, 403, 400, 429), diagnostique-os como descrito anteriormente (verifique a chave de API, validade do JSON, limites de taxa). Um 400 Bad Request pode ocorrer se o modelo especificado não suportar streaming ou se outros parâmetros forem incompatíveis.

Esse teste ajuda a confirmar que a API aceita sua solicitação de streaming e que sua chave é válida para esse tipo de interação, mesmo que o Apidog não seja a ferramenta ideal para visualizar a natureza em tempo real do streaming. Ele verifica se a configuração fundamental da solicitação está correta.

Conclusão

Agora você tem sua chave de API da Cohere e entende as diferenças cruciais entre chaves de Avaliação e Produção, particularmente em relação ao limite de 1.000 chamadas mensais e limites de taxa por minuto nas chaves de Avaliação versus o modelo de pagamento conforme o uso, baseado em tokens e limites mais altos das chaves de Produção. Você também realizou um teste básico, mas vital, usando o Apidog para confirmar que sua chave funciona e você pode estruturar uma chamada de API simples.

Essa base é essencial para interagir efetivamente com a API da Cohere. Lembre-se de manter sua chave segura, monitorar seu uso em relação aos limites (especialmente em uma chave de Avaliação) e consultar a documentação da Cohere para informações detalhadas sobre modelos específicos, parâmetros avançados e uso de SDK à medida que você começa a construir aplicativos mais sofisticados.