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.
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 documentado é criar uma tarefa → consultar o status → baixar o resultado, começando por POST /v1/media/tasks. Este guia percorre o processo e explica o que muda em relação à API nativa do Google e a interfaces compatíveis com OpenAI.
Documentação verificada em 14 de outubro de 2026. Este guia da OmniaKey se baseia na documentação pública do Google e da OmniaKey. Não executamos geração paga nem medimos velocidade ou qualidade dos provedores. Um modelo listado no catálogo não garante permissão para sua chave nem um canal disponível naquele momento.
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.
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. Aceita 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 antes de executar o exemplo.