Primeira requisição do Google Colab: mantenha a chave de API no Secrets

Você pode fazer sua primeira requisição em um notebook do Colab sem instalar nada no seu computador. Salve a chave no Colab Secrets, leia-a com userdata.get(...), aponte o pacote openai para https://api.cheaptokens.dev/v1 e imprima choices[0].message.content e usage. A chave nunca fica em uma célula, então compartilhar o notebook não compartilha sua chave.

Essa última parte é o motivo de todo o trabalho. Digamos que você termine o notebook e envie o link para um colega. Se a chave estiver colada em uma célula, ele agora a tem. Se ela estiver no Secrets, ele recebe o código e nada mais.

Este guia se baseia em a primeira requisição com requests puro. Aqui a única novidade é onde a chave fica e como um notebook a lê. Para a mesma ideia em um laptop, veja armazenar uma chave em uma variável de ambiente.

O que você precisa#

• Uma conta do Google e um novo notebook em colab.research.google.com.
• Uma chave de API da CheapTokens e um saldo recarregado. Chaves e saldo ficam na sua conta; a documentação mostra os passos exatos.
• Cinco minutos.

A API é compatível com OpenAI Chat Completions, então o pacote Python padrão openai funciona com um base_url diferente. O README do openai-python (verificado em 5 de novembro de 2026) lista Python 3.10 ou superior e pip install openai.

Coloque a chave no Colab Secrets#

Na barra lateral esquerda do notebook há um ícone de chave, que abre o painel Secrets. Adicione um novo secret, dê a ele o nome CHEAPTOKENS_KEY, cole sua chave como valor e ative o acesso ao notebook para o notebook em que você está trabalhando. O texto dos botões pode mudar, então procure o ícone de chave em vez de um caminho de menu.

Escolha o nome que você quer agora: é a string que você passará para o código. Um nome errado é um erro fácil de cometer, e a seção de erros mostra como ele aparece.

Execute a primeira requisição#

O Colab lê secrets com google.colab.userdata.get(name), uma função no módulo colabtools do Google (docstrings verificadas em 5 de novembro de 2026). Instale o SDK, leia o secret, envie uma requisição.

!pip install -q openai

from google.colab import userdata
from openai import OpenAI

client = OpenAI(
    api_key=userdata.get('CHEAPTOKENS_KEY'),
    base_url='https://api.cheaptokens.dev/v1',
)

resp = client.chat.completions.create(
    model='deepseek-ai/DeepSeek-V4-Flash-0731',
    messages=[{'role': 'user', 'content': 'Explain a token in one sentence.'}],
    max_tokens=200,
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

O primeiro print mostra a resposta do modelo. O segundo imprime dois números: tokens que você enviou e tokens que o modelo escreveu. Essa é a conta inteira da requisição, e é por isso que a imprimimos toda vez.

Quanto custa a requisição#

Tokens são o que você paga, então olhe a segunda linha da saída. Digamos que uma pergunta curta como a acima use cerca de 40 tokens de entrada e a resposta tenha 150 tokens de saída. Essa requisição custa $0.000016 pelo preço atual, e mil delas custam $0.0156. Substitua 40 e 150 pelos dois números que seu notebook imprimiu.

DeepSeek-V4-Flash é o padrão aqui por um motivo: contexto de 380K, até 32.768 tokens de saída por resposta e um preço único a qualquer hora do dia, sem horários de pico. Um saldo cobre todos os modelos, então você pode trocar o modelo nesta célula sem mudar mais nada. Experimente zai-org/GLM-5.3-Flash (contexto de 390K, até 8.192 tokens de saída) e execute a célula novamente. Veja todos os modelos e preços para a lista completa.

Quando uma célula falha#

Erros do lado dos secrets vêm primeiro, antes de qualquer requisição sair do Colab. O código-fonte do colabtools (verificado em 5 de novembro de 2026) diz que userdata.get pode lançar três erros.

• SecretNotFoundError: não há secret com esse nome. Compare a string em userdata.get('...') com o nome no painel Secrets, letra por letra. Maiúsculas e minúsculas importam.
• NotebookAccessError: o secret existe, mas este notebook não tem acesso a ele. Ative o botão de acesso no painel Secrets e execute a célula novamente.
• TimeoutException: o Colab não respondeu à solicitação do secret. A mensagem de erro diz que secrets só podem ser obtidos quando o código é executado pela interface do Colab, então execute a célula no próprio notebook do Colab, não em um script exportado.

Se o secret carrega e a requisição ainda falha, o problema está no lado da API. Um 401 significa que a chave está errada ou ausente; um 404 geralmente indica uma base URL ou um id de modelo errado. API 401 ou 404: chave, base URL, id do modelo percorre os dois casos, e listar modelos com GET /v1/models mostra como copiar o id exato.

Compartilhamento e rotação#

Compartilhe o notebook e o código que chama userdata.get vai junto; a chave não está em nenhuma célula ou saída, então não há nada para vazar. Quem abrir o notebook precisa do próprio secret com o mesmo nome, caso contrário recebe SecretNotFoundError (veja acima).

Se você criar uma nova chave, atualize o valor no painel Secrets; o código continua o mesmo porque ele apenas nomeia o secret.

Um hábito ainda importa: nunca imprima a chave. Uma célula como print(userdata.get('CHEAPTOKENS_KEY')) a coloca na saída, e as saídas são salvas com o notebook.

Próximo passo: coloque a resposta em um loop, um chat ou uma pequena ferramenta. A documentação cobre o restante da API.