# Como usar um proxy da API de imagens Gemini

> Conecte a API de imagens Gemini por um proxy: modelo, formato, criação de tarefas, download, novas tentativas e custo por imagem aprovada.

- Canonical HTML: https://omniakey.com/pt-BR/blog/gemini-image-api-relay
- Markdown: https://omniakey.com/pt-BR/blog/gemini-image-api-relay.md
- Published: 2026-10-14 (updated 2026-10-14)
- Author: Kiki, COO at OmniaKey
- Language: pt-BR
- Category: API setup
- Reading time: 9 min
- All posts: https://omniakey.com/blog/llms.txt

---

**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](https://ai.google.dev/gemini-api/docs/image-generation) usa exemplos da **Interactions API**. A [referência de GenerateContent](https://ai.google.dev/api/generate-content) 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](https://ai.google.dev/gemini-api/docs/image-generation) 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](https://omniakey.com/pt-BR/gemini-nano-banana-2-1) para a oferta atual e a [comparação entre 2.1 e Pro](https://omniakey.com/pt-BR/blog/nano-banana-2-1-vs-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](https://omniakey.com/pt-BR/ai-image-generator).

## 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.

```bash
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](https://docs.omniakey.com/pt-BR/media/overview).

### 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.

```bash
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

```bash
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](https://docs.omniakey.com/pt-BR/media/image) 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](https://ai.google.dev/gemini-api/docs/troubleshooting) 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](https://omniakey.com/pt-BR/pricing) 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:

1. Um prompt retorna uma imagem que abre, no formato e nas dimensões esperados.
2. A edição de uma referência faz a alteração e preserva os detalhes necessários.
3. Repetir a chave e o corpo retorna o mesmo ID de tarefa.
4. É possível retomar a consulta pelo ID depois do tempo de espera local.
5. 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](https://omniakey.com/pt-BR/models) e avalie um modelo compatível em uma tarefa pequena. O [guia do Nano Banana 2.1](https://omniakey.com/pt-BR/blog/nano-banana-2-1-review) 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](https://ai.google.dev/gemini-api/docs/image-generation), a [referência GenerateContent](https://ai.google.dev/api/generate-content) e a [solução de problemas](https://ai.google.dev/gemini-api/docs/troubleshooting) 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](https://omniakey.com/pt-BR/gemini-nano-banana-2-1) antes de executar o exemplo.
