Chamar a Gemini API a partir da China costuma ser difícil não pelo código, mas pelo link: se a requisição sai de forma estável, se a latência é aceitável, se a cota basta e quem resolve quando algo falha. Muitas equipes validam primeiro com um proxy pessoal e levam a mesma configuração para produção, para depois refazer o trabalho por causa de concorrência, limites de taxa e conformidade.

Este artigo divide as soluções comuns em três tipos: conexão direta, proxy próprio e gateway de IA doméstico, explicando limites de aplicação, tratamento de cota e método de implantação. A conclusão antecipada: na fase de protótipo, use o que for mais prático; em produção, escolha por "monitorável, degradável e explicável em conformidade".

Nota: Google e Gemini são marcas de seus titulares. Este artigo toma como exemplo a situação comum de rede e interfaces em outubro de 2026; regiões de serviço, cotas e termos seguem as páginas oficiais. Respeite as leis locais e os termos de uso das plataformas.

1. Comparação inicial das três soluções

Dimensão Conexão direta oficial Proxy próprio Gateway de IA doméstico
Disponibilidade típica Muito afetada por rede e região Depende da qualidade da saída Fornecida pelo provedor, com página de status
Latência Oscilação evidente Pode ser otimizada, mas há um salto extra Em geral mais estável
Custo de operação Baixo, mas diagnóstico difícil Alto: servidor e saída Baixo, uso por interface
Cota Limitada pela taxa e região oficiais Não altera a cota oficial Distribuída e limitada pelo gateway
Cobrança Dólar, fatura por consumo Custo oficial mais servidor Renminbi, pré-pago
Explicação de conformidade Exige descrever o link transfronteiriço Saída e logs sob sua responsabilidade Contrato doméstico e limites de serviço
Cenário indicado Validação pessoal, tarefas pouco sensíveis Sistemas internos com equipe de rede Negócio de produção voltado a clientes

Esta tabela não decide por você; ela lembra que o proxy resolve apenas "se conecta", não cota, fatura ou conformidade. Tratar o proxy como solução de produção de longo prazo é manter a incerteza dentro do link.

2. Conexão direta: rede ou permissão?

Falhas de conexão direta costumam ocorrer em três situações; siga a ordem de diagnóstico:

  1. Região indisponível: em regiões não cobertas pelo serviço oficial, a requisição pode expirar ou ser recusada; trocar a chave não resolve.
  2. Rede inacessível: resolução DNS, handshake TLS e roteamento de saída podem falhar; use curl -v para ver onde para.
  3. Autenticação ou projeto incorreto: 401 é problema de chave; 403 geralmente é projeto, API não habilitada ou permissão de modelo.
export GEMINI_API_KEY="sua-chave"

curl -v "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  --max-time 15

Se a conexão expira na fase de estabelecimento, ajustar parâmetros depois não adianta; se conecta mas retorna 4xx, investigue pelo código de status. Registre fase, duração e código de cada falha para distinguir oscilação eventual de indisponibilidade estrutural.

3. Proxy próprio: resolve conectividade, não cota

A estrutura típica é: servidor de negócio → saída no exterior → Gemini API. Serve equipes com capacidade de operação de rede e sensibilidade de dados controlável, mas quatro pontos precisam entrar no manual de operação:

  • O IP de saída é estável? Pode ser classificado como tráfego anômalo pelo serviço de destino?
  • A camada de proxy registra o conteúdo das requisições? Por quanto tempo os logs ficam? Quem pode acessá-los?
  • Como certificados, domínios e portas são gerenciados? Há alerta quando expiram?
  • Qual é a largura de banda, a concorrência e o failover do próprio servidor de proxy?

O proxy não aumenta a cota oficial. Limites de RPM e TPM do plano gratuito ou de faixas baixas continuam existindo, e o horário de pico continua formando fila. O problema mais comum é toda a operação compartilhar uma única saída: um script descontrolado derruba o link inteiro. Separar saídas e limites por negócio é necessário.

4. Integração via gateway: normalmente só três mudanças

Gateways de IA domésticos costumam oferecer entrada compatível com OpenAI; o código existente só precisa mudar Base URL, chave e nome do modelo:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model="<nome do modelo Gemini na página de preços>",
    messages=[{"role": "user", "content": "Responda apenas OK"}],
    max_tokens=64,
)
print(resp.choices[0].message.content)
print(resp.usage)

O nome do modelo segue a página de preços do site; não copie o exemplo. Após integrar, execute uma requisição mínima e depois um lote de tarefas reais, observando três coisas: latência do primeiro token, taxa de falha e se o conteúdo retornado sofreu degradação. O gateway é a fronteira do serviço; antes de escolher, confirme página de status, canais de suporte, regras de reembolso e termos de dados.

5. Cota e 429: escreva o retry corretamente

A cota do Gemini costuma ser calculada por modelo, projeto e janela de tempo, incluindo requisições por minuto, tokens por minuto e requisições por dia. Ao atingir o limite, geralmente retorna 429, e a forma de tratamento decide se a falha vai se ampliar:

  1. Backoff exponencial com jitter aleatório, para que todos os clientes não tentem no mesmo instante.
  2. Defina número máximo de tentativas e timeout total; ao ultrapassar, degrade, sem reenviar indefinidamente.
  3. Enfileire por prioridade de negócio: requisições interativas à frente do processamento offline.
  4. Torne operações de escrita idempotentes para evitar efeitos duplicados no retry.
  5. Monitore a distribuição temporal dos 429 para distinguir limite por minuto de cota diária esgotada.
  6. Reserve modelo ou canal alternativo e troque automaticamente quando o principal for limitado.

Se a cota diária acabou, repetir não adianta: reduza a faixa, diminua chamadas não críticas ou ajuste a cota. Se houve pico de concorrência, limite primeiro e escale depois; inverter a ordem só deixa o link inteiro mais lento.

6. Conformidade e dados: três perguntas obrigatórias

  1. A requisição contém dados pessoais, contratos de clientes, código ou dados financeiros?
  2. Por quais nós os dados passam, em que regiões ficam e por quanto tempo os logs são retidos?
  3. Em um incidente de segurança, quem fornece registros e em quanto tempo notifica?

Quanto mais longo o link transfronteiriço, maior o custo de explicação. Para sistemas de produção voltados a clientes, classifique e estratifique os dados, anonimizando campos sensíveis; se precisar reter logs, defina permissões de acesso e processo de exclusão. Não pule a revisão de conformidade só porque "é apenas uma chamada de API".

7. Etapas de implantação

  1. Faça uma semana de teste de carga com tarefas reais, cobrindo pico e vale.
  2. Registre taxa de sucesso, latência p50 e p95, distribuição de 429 e custo por tarefa.
  3. Confirme a diferença entre teto de cota e pico do negócio e reserve margem.
  4. Integre monitoramento e alertas cobrindo taxa de erro, latência, saldo e limites.
  5. Ensaie a troca entre principal e backup e confirme que a degradação é aceitável.
  6. Arquive contrato, nota fiscal, termos de dados e descrição de segurança.
  7. Migre com pouco tráfego e amplie após uma semana de observação.

Perguntas frequentes

É possível chamar a Gemini API diretamente na China?

A conexão direta depende da região oficial do serviço, da saída de rede e do estado da conta; o comportamento pode ser timeout, reset de conexão ou 4xx. Não conclua com um único sucesso ou falha; avalie pela distribuição de falhas e latência ao longo de uma semana.

O acesso via proxy é estável?

O proxy melhora a conectividade, mas a estabilidade depende da qualidade da saída, da concorrência e da operação. Ele não altera a cota oficial nem resolve automaticamente conformidade e logs; uso em produção exige monitoramento e degradação completos.

Por que sempre retorna 429?

Pode ser limite por minuto, cota diária esgotada ou pico de concorrência. Veja primeiro os cabeçalhos de resposta e a página de uso para distinguir o tipo; com cota diária esgotada, o retry é inútil e é preciso ajustar a cota ou reduzir chamadas não críticas.

O gateway altera a capacidade do modelo?

O gateway faz principalmente autenticação, roteamento, limitação e cobrança e, em condições normais, não altera o modelo em si. Porém, canais diferentes podem expor modelos, parâmetros e versões distintos; antes de entrar em produção, faça um teste comparativo com o mesmo lote de tarefas.

Quais pontos de conformidade observar no acesso doméstico?

Confirme ao menos se os dados cruzam fronteiras, se incluem dados pessoais, por quanto tempo os logs são retidos e se o provedor fornece contrato e descrição de segurança. Para dados sensíveis, anonimização primeiro e revisão conforme a política da empresa.

Próximos passos

Se não quiser manter proxy e saída próprios, execute primeiro uma requisição Gemini no ZSQH AI Gateway e depois separe chaves e defina orçamento por projeto. Modelos disponíveis e preços seguem a página de preços.

Leitura relacionada: