Como usar um proxy da API de imagens Gemini
Escolha o formato da API, gere uma imagem e retome a tarefa se o tempo de espera acabar.
Nesta página
- De que tipo de proxy você precisa?
- Escolha um modelo de imagens específico
- Gere uma imagem pela OmniaKey
- 1. Crie e salve a tarefa
- 2. Consulte o ID salvo
- 3. Baixe apenas um resultado concluído
- Edite com uma imagem de referência
- Identifique a camada que falhou
- Compare custos e valide a integração
- Perguntas frequentes
- Basta trocar a URL base do SDK?
- Um proxy elimina os limites do Gemini?
- Com qual modelo devo começar?
- Fontes e próximo passo
Um proxy da API de imagens Gemini é um gateway entre seu aplicativo e um modelo de imagens Gemini. Para usá-lo, você precisa do ID de um modelo que produza imagens, do formato de requisição do serviço e de uma forma de obter o arquivo. Trocar a URL base de um cliente de texto não comprova suporte à geração de imagens.
Na OmniaKey, o fluxo publicado na nossa documentação de imagens, verificado em 14 de outubro de 2026, é criar uma tarefa → consultar o status → baixar o resultado, começando por POST /v1/media/tasks. As etapas abaixo percorrem o processo e explicam o que muda em relação à API nativa do Google e a interfaces compatíveis com OpenAI.
De que tipo de proxy você precisa?
Aqui, proxy significa um serviço de API que trata requisições de modelos, autenticação e respostas. Um proxy de rede encaminha tráfego, mas não converte sozinho um formato de API de imagens em outro. Escolha com base na especificação publicada pelo serviço.
| Interface | Formato da requisição | Onde a imagem aparece |
|---|---|---|
| Gemini GenerateContent | /v1beta/models/MODEL:generateContent, com contents e campos compatíveis de generationConfig | Partes de imagem como candidates[].content.parts[].inlineData |
| Proxy compatível com OpenAI | Endpoint e esquema de imagens documentados pelo provedor | Dados ou URLs de imagem no formato definido pelo serviço |
| Tarefas de imagens da OmniaKey | /v1/media/tasks, com model, type, operation, input, parameters | Primeiro um ID; depois assets[] quando o status for succeeded |
O guia atual de imagens do Google usa exemplos da Interactions API. A referência de GenerateContent descreve outro contrato. Não misture os campos nem os formatos de resposta e não presuma que o proxy ofereça os dois.
Também é preciso separar compreensão de imagens e geração. Um modelo pode descrever uma foto e produzir apenas texto. Uma chamada de texto bem-sucedida não valida geração ou edição. A expressão “compatível com OpenAI” também não garante todos os métodos do SDK para uma rota de imagens.
Escolha um modelo de imagens específico
A documentação do Google distingue estes IDs:
- Nano Banana 2.1:
gemini-nano-banana-2.1, ponto de partida recomendado pelo Google para novos fluxos gerais de imagens. - Nano Banana Pro:
gemini-3-pro-image, uma opção separada para tarefas visuais mais exigentes. - Nano Banana 2:
gemini-3.1-flash-image, a geração anterior, não um alias da 2.1.
Copie o ID do serviço que você vai chamar. Confira acesso, geração ou edição, tamanhos e unidade de cobrança. Para a 2.1, a OmniaKey documenta parameters.aspect_ratio e parameters.image_size, com níveis 1K, 2K e 4K. Esses campos não são intercambiáveis com imageConfig do Google nem com size e quality do GPT Image.
Veja a página do Nano Banana 2.1 para a oferta atual e a comparação entre 2.1 e Pro para escolher o modelo. Para experimentar o Nano Banana 2.1 e os outros modelos Nano Banana antes de escrever a chamada do relay, abra o Gerador de imagens IA.
Gere uma imagem pela OmniaKey
Você precisa de Bash, cURL, jq e uma chave OmniaKey armazenada na variável local OMNIAKEY_API_KEY. Execute os comandos no backend ou no computador de desenvolvimento; não coloque a chave no código do navegador. O prompt simples em inglês serve para verificar o fluxo antes de avaliar a qualidade da imagem.
1. Crie e salve a tarefa
Escolha um Idempotency-Key exclusivo para esta solicitação lógica. O valor do exemplo é demonstrativo: troque-o uma vez ao criar um trabalho novo e mantenha a chave e o corpo idênticos nas novas tentativas desse trabalho. Salve ambos antes do envio.
curl --fail-with-body --silent --show-error \
https://api.omniakey.com/v1/media/tasks \
-H "Authorization: Bearer $OMNIAKEY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: gemini-image-demo-20261014-001" \
-d '{
"model": "gemini-nano-banana-2.1",
"type": "image",
"operation": "generate",
"input": {"prompt": "A blue ceramic cup on a white studio table, no text"},
"parameters": {"aspect_ratio": "1:1", "image_size": "1K"}
}' -o task.json
Continue apenas se o cURL terminar com sucesso e task.json contiver um id. Uma tarefa nova retorna 202 Accepted; repetir a mesma chave e o mesmo corpo recupera a tarefa original com 200. Um 202 não significa concluída. Consulte o ciclo de vida das tarefas, em inglês.
2. Consulte o ID salvo
O exemplo em Bash limita o número de consultas. Ao atingir o limite, o ID continua disponível para você retomar depois. Ele não cancela a tarefa nem cria outra.
TASK_ID="$(jq -er '.id' task.json)" || exit 1
for attempt in {1..60}; do
curl --fail-with-body --silent --show-error \
"https://api.omniakey.com/v1/media/tasks/$TASK_ID" \
-H "Authorization: Bearer $OMNIAKEY_API_KEY" \
-o result.json || exit 1
STATUS="$(jq -er '.status' result.json)" || exit 1
case "$STATUS" in
succeeded) break ;;
failed|canceled) jq '.error' result.json; exit 1 ;;
queued|processing) sleep 3 ;;
*) exit 1 ;;
esac
done
Se a criação exceder o tempo de espera antes de retornar um ID, repita o mesmo corpo e a mesma chave de idempotência. Se já tiver o ID, consulte essa tarefa. Uma chave nova pode criar outro trabalho cobrado. A recuperação depende do prazo de retenção: os registros ficam disponíveis por 24 horas após a criação.
3. Baixe apenas um resultado concluído
jq -e '.status == "succeeded"' result.json >/dev/null || exit 1
ASSET_URL="$(jq -er '.assets[0].url' result.json)" || exit 1
curl --fail --location --silent --show-error \
"$ASSET_URL" -o generated-image
Leia mime_type para escolher a extensão correta e verifique se o arquivo abre e tem as dimensões esperadas. URLs assinadas expiram. Consulte novamente enquanto a tarefa e o arquivo estiverem disponíveis para obter um link novo. Baixe os resultados que quiser guardar; o link não é armazenamento permanente.
Edite com uma imagem de referência
Use operation: "edit" e envie Base64 embutido em input.image, ou input.images para várias referências quando houver suporte. A instrução de edição continua em input.prompt. A documentação de imagens, em inglês mostra o formato completo.
O limite é de 1 MiB para o corpo inteiro da requisição, incluindo Base64. Comprima ou reduza a referência se necessário. Os limites de upload da API direta do Google não substituem os do proxy. Comece com uma imagem pequena e uma alteração clara, verificando também o que deveria permanecer igual.
Mudar o prompt, a referência, o modelo ou um parâmetro cria outra solicitação e exige uma chave nova. Reutilizar a chave com outro corpo retorna 409 idempotency_key_reused.
Identifique a camada que falhou
| Sintoma | O que conferir | Próxima ação |
|---|---|---|
401 / 403 | Chave, host, autenticação e acesso ao modelo | Corrija credenciais ou permissões antes de tentar de novo |
400 / 404 | Endpoint, ID, campos e proprietário da tarefa | Confira o contrato; não invente aliases |
413 | Tamanho total, incluindo Base64 | Reduza a imagem de entrada |
409 idempotency_key_reused | Mesma chave com corpo diferente | Use o corpo original para recuperar ou outra chave para um novo trabalho |
429 | Cota, frequência de chamadas e concorrência | Leia o erro, reduza a carga e aplique espera progressiva com limite quando adequado |
503 | Configuração ou capacidade temporária | worker_disabled e no_available_channel exigem verificar configuração e disponibilidade |
| Só texto ou saída vazia | Suporte a imagem, filtros de segurança e interpretação da resposta | Em GenerateContent, confira promptFeedback, finishReason e todas as partes |
| Tempo de consulta esgotado | A tarefa ainda está rodando? | Retome o mesmo ID sem criar outra tarefa |
O guia de solução de problemas do Google descreve o próprio serviço. O proxy acrescenta outra camada: registre status HTTP, código do erro, ID e duração sem dados sensíveis. Não grave chaves ou referências privadas nos logs. Um JSON com 200 não prova que há uma imagem utilizável.
Compare custos e valide a integração
A cobrança direta do Google e a de um proxy são ofertas diferentes. Antes de rodar um lote, confira os preços atuais da OmniaKey e a unidade do modelo. Não aplique preço de token de texto à saída de imagens nem presuma que uma assinatura pessoal do Gemini pague chamadas do proxy.
Uma medida útil é total efetivamente cobrado ÷ número de imagens aprovadas. Inclua novas tentativas cobradas e imagens rejeitadas na revisão. É uma fórmula de planejamento, não um teste medido nem uma promessa de menor preço.
Antes de aumentar o volume, valide cinco casos pequenos:
- Um prompt retorna uma imagem que abre, no formato e nas dimensões esperados.
- A edição de uma referência faz a alteração e preserva os detalhes necessários.
- Repetir a chave e o corpo retorna o mesmo ID de tarefa.
- É possível retomar a consulta pelo ID depois do tempo de espera local.
- Um parâmetro inválido ou modelo indisponível gera um erro compreensível, não um falso sucesso.
Registre modelo, parâmetros, duração, estado final, cobrança e resultado da revisão. Confira o tratamento dos prompts e das referências antes de enviar material de produção.
Perguntas frequentes
Basta trocar a URL base do SDK?
Só quando o proxy documenta o endpoint, os campos e a resposta de imagem esperados pelo SDK. Teste a operação de imagem; uma chamada de chat não basta.
Um proxy elimina os limites do Gemini?
Não. Limites do provedor, modelo, proxy e conta podem se aplicar ao mesmo tempo. Um gateway não garante geração ilimitada nem disponibilidade regional.
Com qual modelo devo começar?
Confira o catálogo atual e avalie um modelo compatível em uma tarefa pequena. O guia do Nano Banana 2.1 explica as mudanças do modelo; este artigo trata da conexão e validação da API.
Fontes e próximo passo
As referências principais são o guia de imagens, a referência GenerateContent e a solução de problemas do Google, além dos documentos da OmniaKey citados. Esses links de documentação estão em inglês. Especificações verificadas em 14 de outubro de 2026; confirme o acesso ao modelo na página do modelo Nano Banana 2.1 antes de executar o exemplo.
Modelos deste artigo
Artigos relacionados
Nano Banana Pro API: tutorial em Python, edição de imagem e preço
Um POST, uma consulta, um download: um script de Nano Banana Pro que funciona.
Fotos de produto com Nano Banana: 8 prompts testados
Oito prompts, 22 edições, dois modelos: quais fotos mantiveram o rótulo, onde o tênis saiu espelhado e qual modelo escolher para cada trabalho.
Melhor LLM para agentes de programação em 2026: Claude vs GPT vs Gemini
Compare LLMs para agentes de programação em 2026: Claude, GPT e Gemini em ferramentas, contexto e custo, e entenda por que roteamento supera escolher um único modelo.

