Como fazer a primeira chamada ao Gemini 4 Carbon pela API do AI Studio

O Google lançou o Gemini 4 Carbon em 10/11/2026 como o seu modelo mais forte, voltado a tarefas longas e a raciocínio em várias etapas, segundo o anúncio no Google Blog. Para quem desenvolve, o canal oficial é a API pelo Google AI Studio.

Este tutorial cobre o caminho mínimo: pegar a chave, instalar o SDK, mandar um pedido curto e conferir se a resposta voltou. Se você quer o panorama de quem recebeu acesso, vale ler a chegada do Carbon aos desenvolvedores antes.

A ideia aqui é simples: sair do zero e ver texto voltando do modelo, sem complicar.

O que você precisa antes de chamar o Gemini 4 Carbon

Você precisa de acesso pago, de uma chave de API e de Python ou Node.js numa versão suportada. Sem o primeiro item, o resto não adianta.

• Acesso pago: o Carbon foi liberado para usuários da API paga e assinantes do AI Ultra. O anúncio fala em "all paying developers", ou seja, ele não está no nível gratuito (Google Blog para desenvolvedores).
• Chave de API: gerada no Google AI Studio. Ela autentica as requisições e acompanha o uso (quickstart da Gemini API).
• Ambiente: Python 3.9+ ou Node.js v18+.

E o custo? O preço introdutório vai até 30/11/2026: US$ 2 por milhão de tokens de entrada e US$ 10 por milhão de tokens de saída. Depois dessa data, passa para US$ 4 por milhão de entrada e US$ 20 por milhão de saída, conforme o post para desenvolvedores do Google.

Os limites de requisição dependem do tier de uso do projeto e sobem automaticamente conforme o uso e o gasto aumentam (página de rate limits). Então não estranhe se um projeto novo tiver teto mais baixo no começo.

Passo a passo: da chave de API à primeira resposta do Carbon

O fluxo tem cinco passos: chave, variável de ambiente, SDK, chamada e checagem. Bora ver na prática.

1. Obtenha a chave no Google AI Studio

   Para usuários novos, o AI Studio já cria automaticamente um projeto e uma chave, que você copia na página de API keys. Se precisar de outra, use Create API key e siga a caixa de diálogo (quickstart).

   Erro comum deste passo: usar uma chave de um projeto que está no nível gratuito. O Carbon é para desenvolvedores pagantes, então a chave precisa ser de um projeto com acesso à API paga.

2. Defina a variável GEMINI_API_KEY

   Por que uma variável de ambiente? Porque assim a chave não fica escrita no código. Os SDKs da Gemini API leem GEMINI_API_KEY automaticamente, e se ela não estiver definida você precisa passar a chave ao criar o cliente.

   export GEMINI_API_KEY="SUA_CHAVE"

   Erro comum deste passo: definir a variável num terminal e rodar o script em outro. A variável vale só para aquela sessão, então o SDK não acha a chave e a chamada falha na autenticação.

3. Instale o SDK

   Escolha a sua linguagem. Os comandos são os do quickstart oficial.

   Python 3.9+:

   pip install -q -U google-genai

   JavaScript com Node.js v18+:

   npm install @google/genai

4. Faça a primeira chamada pela Interactions API

   No Google GenAI SDK atual, o Carbon é usado pela Interactions API, segundo o guia do desenvolvedor do Gemini 4 Carbon. A chamada é client.interactions.create com o modelo e um input, e o texto volta em output_text.

   O formato da chamada está no guia de primeiros passos, e o ID do modelo na Gemini API é gemini-4-carbon, segundo a página de novidades do Carbon.

   Python:

   from google import genai
   
   client = genai.Client()  # lê GEMINI_API_KEY do ambiente
   
   interaction = client.interactions.create(
       model="gemini-4-carbon",
       input="Explique em duas frases o que é uma API REST.",
   )
   
   print(interaction.output_text)

   JavaScript:

   import { GoogleGenAI } from "@google/genai";
   
   const client = new GoogleGenAI({}); // lê GEMINI_API_KEY do ambiente
   
   const interaction = await client.interactions.create({
     model: "gemini-4-carbon",
     input: "Explique em duas frases o que é uma API REST.",
   });
   
   console.log(interaction.output_text);

   Erro comum deste passo: errar o ID do modelo (qualquer variação de gemini-4-carbon) ou seguir um tutorial antigo baseado em generateContent. Essa API agora aparece na documentação como "Gemini Generate Content API (Legacy)", e o caminho atual do SDK é a Interactions API.

5. Confira o resultado

O resultado esperado é um texto de resposta impresso no terminal, vindo de output_text. O conteúdo exato varia, então não espere uma frase específica.

A checagem final é esta: se apareceu texto e não um erro de autenticação ou de modelo, a chave, o SDK e o ID estão certos. Aí sim vale partir para prompts maiores.

Como ajustar o raciocínio do Carbon com thinking_level

O raciocínio do Carbon é controlado pelo parâmetro thinking_level, que aceita low, medium e high. O valor medium é o padrão e o recomendado, segundo o guia do desenvolvedor.

Pense nele como um botão de esforço: mais nível tende a mais raciocínio antes da resposta, e menos nível, o contrário. O Carbon não aceita MINIMAL, e o antigo thinking_budget foi descontinuado em favor de thinking_level.

Outro ponto que pega muita gente: temperature, top_p e top_k são ignorados pelo Carbon.

Erro comum: copiar a configuração de um projeto com modelos anteriores, cheia de temperature e thinking_budget, e achar que ela está mudando alguma coisa. Não está. O ajuste que conta no Carbon é o thinking_level.

Como continuar a conversa e testar por curl

Para encadear turnos, passe previous_interaction_id com o id da interação anterior na chamada seguinte (guia de primeiros passos). Assim o modelo recebe o contexto do turno anterior sem você reenviar tudo.

segunda = client.interactions.create(
    model="gemini-4-carbon",
    input="Agora dê um exemplo prático.",
    previous_interaction_id="ID_DA_INTERACAO_ANTERIOR",
)

print(segunda.output_text)

E sem SDK? Dá para testar por REST com curl pela API legada generateContent. O formato documentado é um POST no endpoint do modelo com os headers Content-Type: application/json e x-goog-api-key, e o corpo com contents, parts e text (guia da Generate Content API).

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-carbon:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -X POST \
  -d '{"contents":[{"parts":[{"text":"Explique em duas frases o que é uma API REST."}]}]}'

Esse caminho serve para um teste rápido de chave e acesso. Para projeto novo, o SDK atual usa a Interactions API, então não construa nada em cima do endpoint legado.

Quando vale usar o Carbon em vez do Argon

Segundo o Google no X, o Argon serve para tarefas complexas e o Carbon é o indicado para os problemas mais difíceis. Na prática, se o seu caso é um pedido pontual, o Carbon pode ser mais modelo do que você precisa.

Ele faz mais sentido quando a tarefa é longa ou tem muitas etapas. A página do modelo traz uma janela unificada de 1M de tokens (1.048.576), compartilhada entre entrada, raciocínio e saída. Com long decode, ele gera mais de 64K tokens, até 1M menos o tamanho da entrada.

Repare no "compartilhada": um contexto de entrada gigante come o espaço do raciocínio e da resposta. Por isso compensa dividir a tarefa em marcos em vez de despejar tudo de uma vez.

Os recursos suportados são thinking, system instructions, saída estruturada e compreensão de vídeo agêntica. Saída estruturada, por exemplo, ajuda muito quando o retorno vai ser lido por outro programa.

Sobre custo na fase de testes: tokens de entrada em cache custam 95% menos que o preço normal de entrada (Google Blog para desenvolvedores). Se você vai repetir o mesmo contexto longo em vários pedidos, esse desconto pesa na conta.

Se a decisão é para um time inteiro, um checklist de piloto na empresa ajuda a medir antes de colocar em produção.

Próximo passo depois da primeira resposta

Com a chamada funcionando, rode o mesmo prompt duas vezes, uma com thinking_level em low e outra em high. Compare a qualidade das respostas e o consumo de tokens de cada uma.

Faça isso antes de 30/11/2026, enquanto vale o preço introdutório, e você chega ao preço cheio já sabendo qual nível compensa para o seu caso.

Se você também assina o Google AI Ultra, o Carbon está disponível no app Gemini e no Antigravity, segundo o 9to5Google. Para integrar no seu código, porém, o caminho continua sendo a API.

Fontes consultadas

Consulta em 11/11/2026.

• Google Blog: Gemini 4 Carbon is now available
• Google no X
• Google Blog: Gemini 4 Carbon is now available for developers
• Gemini API: What’s new in Gemini 4 Carbon
• Gemini API: página do modelo Gemini 4 Carbon
• Gemini 4 Carbon: Developer Guide (AI Studio) e docs ai.google.dev
• Gemini API quickstart (Google AI for Developers)
• Getting started: Gemini API (Google AI for Developers)

Explore os vídeos do canal Hora de Codar. Se quiser aprofundar o contexto, veja LANÇOU o Gemini 4 Carbon! O novo 1º lugar que quase ninguém pode usar.