Como usar a API do Gemini 4 Hydrogen com Google ou Ofox

Para chamar o Gemini 4 Hydrogen diretamente pelo Google, use gemini-4-hydrogen com uma chave de API do Google. Pela rota Chat Completions da Ofox, use google/gemini-4-hydrogen com uma chave da Ofox. O endpoint, as credenciais e o parser da resposta precisam corresponder à mesma rota. Trocar apenas o nome do modelo não basta ao mudar de protocolo.

O Google lançou o Hydrogen para desenvolvedores em 12 de novembro de 2026. Diferentemente do Carbon, cujo acesso por API exige a modalidade paga, o Hydrogen aceita as modalidades gratuita e paga do Google. O acesso gratuito ainda depende da elegibilidade, da verificação e dos limites ativos do projeto. Este guia usa a documentação e o catálogo da Ofox conferidos em 13 de novembro de 2026 e vai da escolha da rota até o salvamento e a validação de uma resposta de texto.

Este guia é publicado pela Ofox. Conferimos os formatos de requisição e testamos a validação das respostas com dados sintéticos; não executamos inferência paga do Hydrogen nem medimos velocidade ou qualidade das respostas. Os exemplos são requisições reproduzíveis para você executar, não evidência de um teste real já aprovado para uma conta específica. Para escolher o modelo, consulte a comparação entre Carbon, Hydrogen e Argon. As fontes originais do Google citadas aqui estão em inglês.

Escolha a rota antes de criar a chave

Os dois exemplos acessam a mesma família de modelos por serviços diferentes. Execute o que corresponde à sua conta; não é necessário executar ambos para concluir o tutorial.

O Google recomenda Interactions para novas integrações, mas continua oferecendo GenerateContent. O catálogo público atual da Ofox lista o Hydrogen com suporte aos protocolos OpenAI e Gemini e informa explicitamente /v1/chat/completions para a rota OpenAI. Este artigo usa essa rota documentada. Isso não significa que o exemplo de Interactions do Google funcione na Ofox apenas substituindo a URL base.

A Ofox também documenta uma rota nativa Gemini, com outro formato de requisição. A documentação geral de um protocolo não garante que todo modelo Gemini aceite todas as funções, como cache explícito. Escolha o protocolo antes de adicionar ferramentas, streaming ou entradas multimodais.

Anúncio oficial capturado em 13 de novembro de 2026. A imagem registra o lançamento, não um teste da API ou uma medição de desempenho. Fonte em inglês.

Prepare o projeto Google e verifique a modalidade gratuita

Para o exemplo do Google, abra a página de chaves do AI Studio e identifique o projeto ao qual a requisição será atribuída. Novos usuários podem receber um projeto padrão; projetos Cloud existentes podem precisar ser importados para o AI Studio. Crie ou selecione uma chave do projeto desejado e confira a modalidade e a cota disponível. Uma chave de outro projeto pode autenticar normalmente, mas consumir outra cota.

A disponibilidade gratuita do Hydrogen não significa que todo projeto recém-criado esteja pronto. O guia de verificação de projetos do Google cita projetos adicionais e criados fora do AI Studio entre os casos que podem exigir verificação. As requisições afetadas retornam 403 com FREE_TIER_VERIFICATION_REQUIRED.

Se esse for exatamente o erro:

1. Abra o link de verificação da mensagem ou selecione Verify project na página Projects do AI Studio. Confirme que o número do projeto corresponde à sua chave.
2. Siga a verificação de dispositivo do Google usando um celular físico compatível. Se você não tiver as permissões necessárias, peça ao administrador do projeto para concluir a etapa.
3. Aguarde a confirmação de verificação e repita uma vez a pequena requisição abaixo.

Criar outra chave no mesmo projeto não elimina uma exigência de verificação do projeto. Ativar faturamento pago é uma alternativa separada, com cobranças próprias, e não uma etapa inicial obrigatória para todo usuário do Hydrogen. Leia a causa específica de um 403 antes de alterar o faturamento.

Confira os limites ativos no AI Studio. O Google aplica limites por projeto, não por chave, e os limites de requisições e tokens podem ser atingidos separadamente. Duas chaves de um projeto não criam duas cotas independentes. Não fornecemos um número universal de requisições gratuitas por minuto: use os limites exibidos para o seu projeto e modelo.

Guarde a chave na variável de ambiente GEMINI_API_KEY do servidor ou no gerenciador de segredos da implantação. Não a inclua no código do navegador nem no repositório. A documentação atual das chaves diferencia chaves de autorização e chaves padrão: novas chaves do AI Studio são de autorização por padrão. Chaves padrão sem restrições são rejeitadas; aquelas com restrições explícitas ainda podem funcionar.

O programa abaixo lê GEMINI_API_KEY explicitamente. Isso evita a precedência automática do SDK, que daria prioridade a GOOGLE_API_KEY se ambas estivessem definidas. No macOS/Linux, use export GEMINI_API_KEY="YOUR_GOOGLE_KEY"; no PowerShell, $env:GEMINI_API_KEY="YOUR_GOOGLE_KEY". Substitua o valor no terminal local, evite manter segredos em históricos compartilhados e execute o programa na mesma sessão em que configurou a variável.

Faça a requisição ao Google com Python

Use Python 3.11 ou superior para o SDK atual e crie um ambiente isolado. Nossas verificações locais usaram google-genai 3.3.0 com Python 3.11; o pacote declara essa versão mínima do Python. O exemplo usa google-genai, não o antigo google-generativeai.

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 o ambiente com .venv\Scripts\Activate.ps1. A versão mínima indicada inclui suporte a continuações em primeiro plano no Python, embora este teste curto permaneça dentro do orçamento de uma única resposta do Hydrogen. Salve o código como hydrogen_google.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 Google project.")

client = genai.Client(api_key=key)
interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Give exactly three short bullet points about avoiding duplicate API retries.",
    store=False,
    generation_config={
        "thinking_level": "low",
        "max_output_tokens": 65536,
    },
)
Path("hydrogen-google.json").write_text(
    json.dumps(interaction.model_dump(mode="json"), indent=2),
    encoding="utf-8",
)
print("Saved hydrogen-google.json")
print("Interaction:", interaction.id)
print("Status:", interaction.status)

Execute python hydrogen_google.py. O comando envia uma requisição real ao projeto da chave; o uso na modalidade paga é cobrado. Ele salva a resposta mesmo quando a interação não termina com texto útil. Execute o validador abaixo antes de considerar o teste concluído.

O prompt é curto e usa raciocínio low. O valor 65.536 é um limite máximo conjunto para raciocínio e saída visível, não um pedido para gerar essa quantidade nem um consumo garantido. Um limite muito pequeno pode não deixar espaço para texto depois do raciocínio. Mantenha a entrada curta e confira o uso real, sem tratar o teto como consumo.

store=False cria uma interação única sem estado de interação armazenado. Não copie essa configuração sem alterações para tarefas em segundo plano ou conversas que dependam de previous_interaction_id. Ela também não é uma promessa geral sobre todos os registros mantidos pelo provedor. A visão geral de Interactions explica as regras de armazenamento.

Faça a requisição pela Ofox com Chat Completions

Crie ou selecione uma chave seguindo a documentação de configuração e uso de API Key e armazene-a como OFOX_API_KEY no servidor ou terminal local. No macOS/Linux, use export OFOX_API_KEY="YOUR_OFOX_KEY"; no PowerShell, $env:OFOX_API_KEY="YOUR_OFOX_KEY", substituindo o valor localmente. Antes de executar, confira o saldo e a página atual do Hydrogen em inglês. A cota gratuita do Google não paga requisições da Ofox, e o saldo da Ofox não paga o endpoint do Google.

Nosso snapshot completo do catálogo público continha 133 modelos, incluindo google/gemini-4-hydrogen. Isso confirma o registro e os protocolos anunciados naquela data. Não comprova uma inferência bem-sucedida nem garante o comportamento de toda conta, provedor ou configuração futura.

Salve como hydrogen-ofox-request.json:

{
  "model": "google/gemini-4-hydrogen",
  "messages": [
    {
      "role": "user",
      "content": "Give exactly three short bullet points about avoiding duplicate API retries."
    }
  ],
  "max_tokens": 65536,
  "stream": false
}

Envie pelo terminal com curl:

curl --silent --show-error --fail-with-body --max-time 900 \
  'https://api.ofox.io/v1/chat/completions' \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @hydrogen-ofox-request.json \
  --output hydrogen-ofox.json

A requisição segue a documentação do endpoint Chat Completions e seus parâmetros. Ao configurar posteriormente um SDK compatível com OpenAI, mantenha apenas uma ocorrência de /v1: a URL base é https://api.ofox.io/v1, e o endpoint REST completo acrescenta /chat/completions.

O exemplo omite intencionalmente temperature, top_p e extensões de raciocínio específicas de um provedor. O objeto nativo generation_config do Google não é um parâmetro de Chat Completions da OpenAI. Não o cole supondo que o gateway o encaminhará. Para configurar raciocínio em uma rota da Ofox, confira primeiro o mapeamento documentado dos parâmetros. A tabela nativa de quatro níveis abaixo não comprova que qualquer campo de compatibilidade funcione.

Um código de saída do curl diferente de zero indica falha HTTP ou de transporte. Leia o corpo do erro salvo e remova chaves antes de compartilhar logs. O timeout é um limite de espera do cliente, não uma estimativa de latência. Se ele expirar, não dispare imediatamente várias novas requisições pagas: o encerramento no cliente não prova que o processamento no provedor parou.

Valide a resposta conforme o protocolo usado

HTTP 200 pode conter uma interação inacabada, uma chamada de ferramenta ou nenhum texto aproveitável. Uma resposta correta também pode parecer vazia se você procurar os campos da outra API. O SDK do Google oferece a propriedade auxiliar interaction.output_text, mas o recurso salvo usa steps; Chat Completions usa choices.

Salve este validador completo como check_hydrogen.py. Ele lê arquivos locais, não faz chamadas de rede e nunca reenvia a inferência.

import json
import sys
from pathlib import Path

def validate(payload, route):
    if "error" in payload:
        raise ValueError("API error: " + json.dumps(payload["error"]))
    if route == "google":
        if payload.get("status") != "completed":
            raise ValueError("Interaction is not completed: " + str(payload.get("status")))
        text = "".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"
        )
    elif route == "ofox":
        choices = payload.get("choices") or []
        if not choices:
            raise ValueError("No Chat Completions choices in response")
        choice = choices[0]
        if choice.get("finish_reason") != "stop":
            raise ValueError("Text did not finish normally: " + str(choice.get("finish_reason")))
        text = (choice.get("message") or {}).get("content") or ""
    else:
        raise ValueError("Route must be google or ofox")
    if not isinstance(text, str) or not text.strip():
        raise ValueError("No usable text; inspect the saved JSON")
    return text

def main():
    if len(sys.argv) != 3:
        raise SystemExit("Usage: python check_hydrogen.py google|ofox response.json")
    payload = json.loads(Path(sys.argv[2]).read_text(encoding="utf-8"))
    try:
        text = validate(payload, sys.argv[1])
    except ValueError as exc:
        raise SystemExit(str(exc))
    print("Response ID:", payload.get("id"))
    print("Usage:", json.dumps(payload.get("usage")))
    print(text)

if __name__ == "__main__":
    main()

Para Google, execute python check_hydrogen.py google hydrogen-google.json. Para Ofox, python check_hydrogen.py ofox hydrogen-ofox.json. Quando aprovado, o programa imprime ID, usage e texto visível. Leia o texto e confirme os três tópicos curtos e relevantes pedidos no prompt. O validador verifica conclusão do protocolo e texto não vazio, não a qualidade factual da orientação do modelo.

Testamos essa lógica localmente com respostas sintéticas concluídas, vazias, com erro, incompletas e de ferramentas, incluindo texto distribuído em vários passos de saída do Google. Isso comprova o comportamento do validador, não autenticação real, cotas, latência ou qualidade. tool_calls pode ser um motivo de conclusão correto em uma aplicação com ferramentas; neste teste de texto, ele reprova porque ainda falta a resposta final.

Escolha o esforço de raciocínio sem confundi-lo com o tamanho da saída

A API nativa do Hydrogen oferece quatro níveis de raciocínio. O padrão é high; Carbon e Argon usam medium por padrão. A documentação de raciocínio descreve esforço, não uma quantidade fixa de palavras.

São pontos de partida, não resultados de benchmark da Ofox. Compare níveis com a mesma entrada e os mesmos critérios de aceitação. Registre modelo exato, nível, status, duração, usage e motivo de aprovação ou reprovação. Altere uma configuração por vez: uma resposta mais curta não demonstra menor consumo de tokens de raciocínio.

O Hydrogen compartilha 1.048.576 tokens entre entrada, raciocínio e saída. Não oferece um milhão para entrada mais outro milhão independente para resposta. O orçamento síncrono padrão de raciocínio e saída é 65.536, limite suportado por uma única resposta com ou sem streaming. Saídas maiores exigem os mecanismos de continuação ou execução em segundo plano descritos em Long Decode.

Não configure um milhão de tokens de saída no primeiro teste. Se depois usar execução em segundo plano, salve o ID da tarefa e trate explicitamente os estados pendentes e finais. Definir apenas background=true não aumenta o limite padrão. Este tutorial valida uma chamada curta em primeiro plano, não um controlador completo de tarefas longas.

O Hydrogen produz texto. A ficha do modelo lista entradas de imagem, vídeo, áudio e PDF, mas não geração nativa de imagens, geração de áudio ou suporte à Live API. Analisar uma imagem é diferente de gerar outra. Acrescente uma entrada compatível somente depois de validar a referência de texto.

Corrija a falha na camada correspondente

Registre juntos endpoint, identificador do modelo, projeto ou conta, versão do SDK e erro exato. Remova as credenciais antes de compartilhar. Um campo incorreto não exige reconstruir toda a integração.

Para respostas da Ofox, consulte o guia de tratamento de erros. Para categorias do Google, use a referência oficial de solução de problemas. O guia de erros da API do Argon também mostra como separar falhas de rota, cota e parsing, mas seus parâmetros específicos não são padrões do Hydrogen.

Ao adicionar ferramentas, declare-as nos campos nativos da API escolhida. Pedir no prompt que o modelo imprima um formato inventado de chamada não faz um executor reconhecê-lo automaticamente. Preserve histórico e assinaturas exigidos pelo protocolo. Se a falha envolver uma assinatura, consulte o diagnóstico de thought signature ausente, em inglês.

Guarde uma configuração de referência reproduzível

A integração está pronta para a próxima função quando existe uma resposta salva, o sinal correto de conclusão, texto útil com os três tópicos solicitados e um registro de uso vinculado ao projeto ou conta pretendido. Salve modelo, rota, versão do SDK e configuração junto da resposta, sem incluir segredos.

Depois acrescente uma única mudança: um prompt de trabalho real, uma entrada de arquivo aceita, streaming ou uma ferramenta declarada. Se a nova versão falhar, repita o teste de referência. Assim você distingue uma regressão de acesso de um problema introduzido pela função nova.

Se a próxima decisão for encaminhar uma tarefa mais difícil ao Carbon, consulte o guia de escolha do Gemini 4. Os requisitos de acesso e as configurações da primeira chamada do Carbon estão no tutorial da API do Carbon. Uma chamada bem-sucedida ao Hydrogen comprova a sua integração atual, não que conta, parâmetros e parser possam ser copiados sem alterações para qualquer serviço.