Como acessar a API Gemini 4 Carbon e validar a primeira resposta

Use o ID exato gemini-4-carbon em um projeto pago da Gemini API. Para uma integração nova, o Google recomenda começar pela Interactions API. A configuração só está validada quando a interação termina e entrega texto utilizável. Um HTTP 200, sozinho, não basta.

O Carbon foi disponibilizado publicamente para desenvolvedores pagantes da API em 10 de novembro de 2026. O anúncio anterior de acesso restrito já não descreve todas as condições atuais. Este guia foi conferido com a documentação em 13 de novembro de 2026 e vai da escolha do projeto e da chave até uma resposta salva que você possa inspecionar.

Os exemplos usam a API nativa do Google, não um endpoint da Ofox. Conferimos o formato documentado das requisições e testamos o parser com dados sintéticos, mas não executamos uma chamada paga ao Carbon para este artigo. O prompt é uma tarefa para você testar, não um resultado de avaliação de desempenho. Se ainda estiver escolhendo o modelo, veja a comparação entre Carbon, Hydrogen e Argon.

1. Confirme que a chave pertence ao projeto pago correto

Você precisa de uma conta Google habilitada para usar a Gemini API, um projeto Google Cloud acessível no AI Studio, uma chave desse projeto e faturamento ativo da API. Verifique esses quatro requisitos separadamente. Uma assinatura do aplicativo Gemini ou do Google AI Ultra não configura, por si só, a cobrança da API no projeto usado pelo seu aplicativo.

1. Abra o Google AI Studio e selecione o projeto pretendido. Se já existe um projeto Cloud, importe-o quando necessário, em vez de criar outro sem relação apenas para fazer aparecer o botão de criação de chave.
2. Na gestão de chaves do projeto, crie ou selecione uma chave. Registre o nome ou ID do projeto, não o segredo, nas notas de implantação. Confirme que o terminal ou servidor carregará a chave desse mesmo projeto.
3. Conclua a configuração paga do mesmo projeto nas opções de faturamento do AI Studio. Conforme a conta, o fluxo pode usar Prepay, oferecer a escolha Prepay/Postpay ou manter uma modalidade transitória de Postpay. O Prepay pode exigir um pagamento mínimo de US$ 5 ou equivalente local. Siga o estado real exibido na conta: cadastrar um cartão não prova que há fundos disponíveis para as requisições.
4. Confirme que o faturamento está ativo e que o saldo antecipado necessário está disponível. Antes da chamada, verifique as cotas do projeto e a elegibilidade regional. Projetos pagos também têm limites.

Fontes: guias do Google sobre chaves de API e faturamento, em inglês. Se importar o projeto ou criar a chave não for possível, peça ao administrador que confira as permissões necessárias. Não resolva a ausência de um botão expondo a chave ou concedendo permissões amplas sem critério.

Página oficial em inglês capturada em 13 de novembro de 2026. Ela comprova a abertura para desenvolvedores, não o estado de faturamento da sua conta nem uma chamada bem-sucedida. Anúncio original.

Uma chave antiga pode falhar por motivos além de um erro de digitação

As novas chaves do AI Studio são, por padrão, authorization keys. A documentação atual rejeita standard keys sem restrições; standard keys com restrições explícitas continuam funcionando. Confira o tipo e as restrições, sem presumir que toda chave antiga se tornou inválida.

Guarde o segredo em uma variável de ambiente no servidor ou em um gerenciador de segredos. Localmente, configure GEMINI_API_KEY sem versionar o valor no repositório. Não o inclua em capturas de tela, relatos de erro ou JavaScript do navegador. Os exemplos leem GEMINI_API_KEY explicitamente porque, na detecção automática do SDK, GOOGLE_API_KEY tem precedência. Um valor antigo dessa variável poderia selecionar outro projeto sem que você percebesse.

Verifique apenas se a variável existe, sem imprimir seu conteúdo:

python3 -c 'import os; print("Key configured:", bool(os.environ.get("GEMINI_API_KEY")))'

True indica somente que existe um valor. Não valida a chave, o projeto nem o faturamento. A requisição seguinte fornece a próxima evidência.

2. Faça uma primeira chamada em Python com limite definido

Crie um ambiente separado para evitar que um SDK antigo de outro aplicativo determine o comportamento do exemplo:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade 'google-genai>=2.34.0'
python -m pip show google-genai

No Windows PowerShell, ative com .venv\Scripts\Activate.ps1. O pacote é google-genai, importado com from google import genai; não o substitua pelo antigo google-generativeai. O suporte básico a Interactions e a continuação automática em primeiro plano têm versões mínimas diferentes. O limite acima inclui a continuação atual do Python, embora esta chamada curta permaneça intencionalmente dentro de uma única etapa de resposta. Consulte Interactions e long decode, em inglês.

Salve como carbon_first_call.py:

import json
import os
from pathlib import Path
from google import genai

key = os.environ.get("GEMINI_API_KEY")
if not key:
    raise SystemExit("Set GEMINI_API_KEY for the intended paid project.")

client = genai.Client(api_key=key)
interaction = client.interactions.create(
    model="gemini-4-carbon",
    input="Return exactly three checklist items for reviewing an API integration.",
    store=False,
    generation_config={
        "thinking_level": "low",
        "max_output_tokens": 32768,
    },
)

payload = interaction.model_dump(mode="json")
Path("carbon-response.json").write_text(
    json.dumps(payload, indent=2), encoding="utf-8"
)
text = interaction.output_text or ""
print("Interaction:", interaction.id)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
if interaction.status != "completed" or not text.strip():
    raise SystemExit("No completed text result; inspect carbon-response.json.")
print(text)

Execute python carbon_first_call.py. Isso envia uma requisição paga. Use primeiro uma das opções: não execute automaticamente Python e REST em sequência como testes duplicados. Os 32.768 tokens são um teto conjunto para raciocínio e saída visível, não uma previsão da cobrança nem uma ordem para produzir esse volume de texto. Um prompt curto com nível low serve para verificar acesso, não para realizar uma pesquisa complexa.

O sucesso deve produzir um ID de interação, completed, informações de uso e três itens úteis de checklist. Leia a resposta também: uma interação concluída ainda pode descumprir o formato ou o conteúdo pedido. Guarde o JSON para diagnóstico. Se depois substituir o prompt inofensivo por dados de clientes, trate o arquivo de resposta como material potencialmente confidencial.

Definimos store=False porque esta é uma requisição isolada. Isso desativa o armazenamento da interação para recuperação posterior ou continuação de conversa no servidor; não é uma promessa abrangente sobre todas as políticas de logs de provedores. O padrão é store=true. Não copie essa configuração para uma tarefa em segundo plano ou para um exemplo que dependa de previous_interaction_id.

3. Chame o endpoint REST e leia os campos corretos

REST ajuda a enxergar exatamente o que o cliente envia. Você precisa de curl e Python 3 para o parser. Salve o corpo em carbon-request.json:

{
  "model": "gemini-4-carbon",
  "input": "Return exactly three checklist items for reviewing an API integration.",
  "store": false,
  "generation_config": {
    "thinking_level": "low",
    "max_output_tokens": 32768
  }
}

Envie para o endpoint Interactions:

curl --silent --show-error --fail-with-body --max-time 900 \
  'https://generativelanguage.googleapis.com/v1beta/interactions' \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @carbon-request.json \
  --output carbon-response.json

Um corpo de erro enviado pelo servidor também é salvo para inspeção. Um código de saída do curl diferente de zero indica um problema de transporte ou da requisição HTTP; não prossiga como se tivesse recebido a resposta. Os 900 segundos são um timeout explícito do cliente, não uma afirmação de que o Carbon sempre leva 15 minutos. O timeout do cliente tampouco prova que o servidor parou. Não repita imediatamente um trabalho possivelmente cobrado sem verificar o que ocorreu.

output_text é uma propriedade de conveniência do SDK, não um campo da resposta REST. No REST, o texto está em steps, nos itens model_output e em seus conteúdos do tipo text. Um parser de candidates do GenerateContent ou de outputs de um exemplo antigo pode interpretar uma resposta válida como vazia.

Salve o arquivo inspect_carbon.py ao lado da resposta:

import json
import sys
from pathlib import Path


def extract_text(payload):
    return "".join(
        part.get("text", "")
        for step in payload.get("steps", [])
        if step.get("type") == "model_output"
        for part in step.get("content", [])
        if part.get("type") == "text"
    )


def inspect(path):
    payload = json.loads(Path(path).read_text(encoding="utf-8"))
    if "error" in payload:
        raise SystemExit("API error: " + json.dumps(payload["error"]))
    text = extract_text(payload)
    print("Interaction:", payload.get("id"))
    print("Status:", payload.get("status"))
    print("Usage:", json.dumps(payload.get("usage")))
    if payload.get("status") != "completed" or not text.strip():
        raise SystemExit("No completed text result; inspect the saved response.")
    print(text)


if __name__ == "__main__":
    inspect(sys.argv[1] if len(sys.argv) > 1 else "carbon-response.json")

Rode python3 inspect_carbon.py carbon-response.json. O parser reúne todas as partes de texto, sem assumir que o primeiro step contém a resposta final. Ele se recusa intencionalmente a tratar resultados parciais ou interações que exigem uma ação como sucesso. Pode ser usado em monitoramento, mas não conecte sua falha a um ciclo infinito de novas chamadas.

Testamos localmente respostas sintéticas concluídas, vazias, com erro e com múltiplos steps. Isso valida a extração e o tratamento de falhas, não autenticação, disponibilidade, latência ou qualidade da API real do Google.

4. Entenda as configurações antes de usar uma carga real

A primeira chamada evita ferramentas, arquivos grandes e ciclos longos de agente. Acrescente esses elementos um por vez depois que o acesso funcionar. O guia do Carbon em inglês estabelece estes limites:

Para aplicativos migrados com teto pequeno, o Google recomenda permitir pelo menos 32.768 tokens de raciocínio e saída. É uma decisão de orçamento, não prova de consumo máximo em toda chamada. Reduza o nível de raciocínio quando fizer sentido e confira o uso, em vez de deduzir o custo pelo tamanho da resposta. Veja condições de preço e cálculos reproduzíveis no guia de escolha do Gemini 4.

Quando a primeira chamada vira um trabalho longo

Não aumente apenas max_output_tokens deixando todo o restante igual. A documentação de long decode em inglês separa continuação em primeiro plano, streaming e execução em segundo plano. Um SDK recente pode combinar etapas em primeiro plano; um cliente REST próprio precisa tratar requires_continuation e repassar os dados necessários para continuar.

Para tarefas em segundo plano, habilite o armazenamento, salve o ID e limite o tempo de espera no polling. queued e in_progress são estados pendentes; completed permite validar o resultado; incomplete, failed e cancelled são desfechos diferentes. requires_action pede a execução de uma ferramenta, não significa resposta final pronta. Aumentar o orçamento ou definir background=true não garante comprimento específico. Este tutorial de primeira chamada não implementa esse controlador separado de tarefas longas.

No histórico de conversa mantido no servidor, previous_interaction_id carrega a conversa anterior, mas não herda tools, system_instruction ou generation_config. Reenvie essas configurações quando forem necessárias no próximo turno. Interactions armazena respostas por padrão; no acesso pago do Google, a retenção padrão é de 55 dias, com opções menores configuráveis. Escolha de propósito, em vez de herdar a decisão de um código copiado.

5. Investigue as falhas na ordem em que acontecem

Leia o erro estruturado e anote endpoint, ID exato do modelo, identificador do projeto, versão do SDK e horário, excluindo a chave. Corrija a primeira camada que falhou antes de mudar prompts ou aumentar orçamentos.

A referência de erros do Google em inglês explica as categorias. Nosso diagnóstico de erros da API Argon também ajuda a separar rota, cota e resposta; mantenha os detalhes exclusivos do Argon separados do Carbon. Se adicionar ferramentas e encontrar erro de assinatura, use o diagnóstico de missing thought signature em inglês, em vez de descartar o histórico sem investigar.

Migrando um cliente Gemini existente

Mantenha uma versão funcional de referência e altere uma fronteira por vez. A API nativa GenerateContent do Google continua suportada. Recomendar Interactions para projetos novos não exige reescrever imediatamente todos os clientes em funcionamento.

Ao migrar, atualize o formato de requisição e o parser juntos. Trocar só o modelo para gemini-4-carbon e continuar lendo candidates é uma migração incompleta. Confira os níveis de raciocínio, remova referências explícitas de cache e suposições antigas sobre amostragem e reveja timeouts e limites de saída. No JavaScript Interactions, generation_config, thinking_level e max_output_tokens usam snake_case. Não transporte a capitalização da configuração de GenerateContent.

Execute o mesmo prompt inofensivo antes de reconectar ferramentas e arquivos de clientes. Depois valide uma tarefa representativa com critérios de aceitação conhecidos. Um teste inicial bem-sucedido confirma o caminho de integração, não a confiabilidade de um agente de produção com várias etapas.

Este exemplo pode ser usado pela Ofox?

A Ofox publica este guia, mas os exemplos usam credenciais e endpoints nativos do Google. Nosso registro do catálogo público de 13 de novembro de 2026 não listava Carbon. É uma observação datada, não prova de ausência de suporte em toda conta ou rota futura. Não verificamos uma chamada Carbon pela Ofox nem afirmamos que basta trocar a Base URL.

Para integrar pela Ofox, confira primeiro a disponibilidade atual do modelo exato e os protocolos suportados. Depois siga a documentação da Gemini API na Ofox para endpoint, autenticação e formato de requisição daquela rota. Mantenha as chaves Ofox e Google separadas. Uma rota compatível com Gemini não demonstra suporte ao endpoint Interactions do Google nem a todos os recursos do Carbon.

Quando uma rota Ofox retornar erro, consulte a resposta real e o guia de tratamento de erros da Ofox. A conta de faturamento Google, o saldo Ofox e uma assinatura de aplicativo são sistemas diferentes. Crédito em um não paga requisições ao outro.

Registre a validação da primeira chamada

Antes de considerar a configuração concluída, salve estas evidências sem segredos:

• Modelo exato, endpoint, versão do SDK e identificador do projeto.
• Uma resposta com ID de interação, status e uso.
• Texto extraído que cumpra o pedido de três itens.
• Nível de raciocínio, orçamento de saída e escolha de armazenamento usados.
• Erros encontrados e a correção concreta que resolveu cada um.

Agora existe uma referência para separar acesso, protocolo e saída. Ao acrescentar uma ferramenta ou um prompt maior, se a chamada básica passar e só a nova tarefa falhar, investigue o que mudou. Não é preciso recriar chaves, trocar projetos de faturamento ou executar novamente o agente inteiro a cada tentativa.