Modelos de imagemUsuários avançadosAtualizado em
POST/v1/images/generations

Console da API

POST/v1/images/generations
Ver chaves

As requisições usam a chave informada e seguem a cobrança padrão da API.

Gemini 3.1 Flash Image Preview

ID da solicitação gemini-3.1-flash-image-preview

Protocolos

Autenticação

Obtenha uma chave em Gerenciar chaves de API. Para requisições JSON, defina Content-Type: application/json.

  • Authorization: Bearer YOUR_API_KEY
  • Gemini · x-goog-api-key: YOUR_API_KEY

Parâmetros da requisição

POST /v1/images/generations

CampoTipoObrigatórioDescrição
modelstringObrigatórioUse este ID de modelo gemini-3.1-flash-image-preview.
promptstringObrigatórioDescreva a imagem a gerar.
aspect_ratiostringOpcionalProporção da imagem de saída. Por exemplo, 1:1 ou 16:9. Quando omitido, o valor é calculado a partir de size. Padrão 1:1.
image_sizestringOpcionalFaixa de resolução da saída. Valores aceitos 1K, 2K, 4K. Quando omitido, o valor é calculado a partir de size. Padrão 1K.
nintegerOpcionalQuantidade de imagens por solicitação. Use 1 para obter um resultado. Padrão 1.
image_urlsstring[]OpcionalLista JSON de imagens de referência. Cada item é uma URL HTTPS pública ou uma URL de dados de imagem em Base64. Também aceita image_input. Máximo de imagens de referência 4.
?asyncstringOpcionalParâmetro de consulta da URL. Use 1, true ou yes para receber 202 e task_id. Omita para aguardar o resultado.

POST /v1/images/edits

CampoTipoObrigatórioDescrição
modelstringObrigatórioUse este ID de modelo gemini-3.1-flash-image-preview.
promptstringObrigatórioDescreva as alterações na imagem de referência.
aspect_ratiostringOpcionalProporção da imagem de saída. Por exemplo, 1:1 ou 16:9. Quando omitido, o valor é calculado a partir de size. Padrão 1:1. Para edições, defina este campo no corpo JSON.
image_sizestringOpcionalFaixa de resolução da saída. Valores aceitos 1K, 2K, 4K. Quando omitido, o valor é calculado a partir de size. Para edições, defina este campo no corpo JSON. Padrão 1K.
nintegerOpcionalQuantidade de imagens por solicitação. Use 1 para obter um resultado. Padrão 1.
image_urlsstring[]CondicionalLista JSON de imagens de referência. Cada item é uma URL HTTPS pública ou uma URL de dados de imagem em Base64. Também aceita image_input. Máximo de imagens de referência 4. Inclua ao menos uma referência em edições via JSON.
image[]file[]CondicionalPara edições com multipart/form-data, envie ao menos uma imagem. Repita o campo para várias imagens. Para um único arquivo, também é possível usar image. Máximo de imagens de referência 4.
?asyncstringOpcionalParâmetro de consulta da URL. Use 1, true ou yes para receber 202 e task_id. Omita para aguardar o resultado.

POST /v1beta/models/gemini-3.1-flash-image-preview:generateContent

CampoTipoObrigatórioDescrição
model (path)stringObrigatórioUse gemini-3.1-flash-image-preview como ID do modelo no caminho da URL.
contentsobject[]ObrigatórioConteúdo da conversa em ordem. Cada item reúne suas partes de entrada em parts.
contents[].rolestringOpcionalPapel da mensagem. Use user para a entrada do usuário e model para mensagens anteriores do modelo.
contents[].partsobject[]ObrigatórioArray de partes dentro de um item de conteúdo. Partes de texto usam text.
contents[].parts[].inlineDataobjectCondicionalObjeto de mídia embutida. Informe mimeType e data em Base64. Os tipos aceitos dependem do modelo e do endpoint.
systemInstructionobjectOpcionalObjeto de instrução de sistema. Coloque o texto das instruções em parts[].text.
generationConfig.maxOutputTokensintegerOpcionalLimita o número de tokens de saída. O limite aceito depende do modelo e do endpoint.
generationConfig.responseModalitiesstring[]OpcionalModalidades de saída. Use ["IMAGE"] para solicitar uma imagem.

Exemplos de requisição

Defina a chave de API na variável de ambiente local ICODEEASY_API_KEY e escolha um endpoint que aceite chamadas HTTP diretas. Caso o endpoint exija um cliente específico, siga o guia de configuração desse cliente.

Substitua as URLs e os IDs de mídia dos exemplos por ativos válidos.

Images Generations

bash
curl -sS 'https://api.icodeeasy.cc/v1/images/generations' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "model": "gemini-3.1-flash-image-preview",
  "prompt": "A watercolor illustration of a paper lantern by a lake.",
  "aspect_ratio": "16:9",
  "image_size": "1K"
}'

Images Edits

bash
curl -sS 'https://api.icodeeasy.cc/v1/images/edits' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "model": "gemini-3.1-flash-image-preview",
  "prompt": "Change the background to a pale blue wall. Preserve the subject.",
  "image_urls": [
    "https://example.com/reference.png"
  ],
  "aspect_ratio": "16:9",
  "image_size": "1K"
}'

Gemini generateContent

bash
curl -sS 'https://api.icodeeasy.cc/v1beta/models/gemini-3.1-flash-image-preview:generateContent' \
  -H "x-goog-api-key: $ICODEEASY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "A watercolor illustration of a paper lantern by a lake."
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ]
  }
}'

Gemini generateContent · JSON

Consultar tarefa de imagem

bash
curl -sS 'https://api.icodeeasy.cc/v1/images/tasks/YOUR_TASK_ID' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY"

Respostas e tarefas

/v1/images/generations · /v1/images/edits

HTTP 200 · Sucesso síncrono

Com ?sync=1, leia as URLs geradas em data[].url. created é um timestamp Unix em segundos e id é o ID da tarefa.

json
{
  "id": "d142c93a-de26-40c9-be62-0de840d10960",
  "created": 1781599773,
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ]
}

HTTP 202 · Envio assíncrono

json
{
  "task_id": "d142c93a-de26-40c9-be62-0de840d10960",
  "status": "pending"
}

Com ?async=1, consulte GET /v1/images/tasks/{task_id} com a mesma chave de API. status é pending, completed ou failed. Quando a tarefa concluir, leia a URL da imagem em result_url.

HTTP 200 · Consulta de tarefa concluída

json
{
  "task_id": "d142c93a-de26-40c9-be62-0de840d10960",
  "status": "completed",
  "model": "gemini-3.1-flash-image-preview",
  "result_url": "https://example.com/generated-image.png"
}

Erros comuns

Se a consulta retornar failed, leia error. Se houver error_detail, confira retryable antes de enviar novamente.

Exemplos de resposta e erros

Gemini generateContent · JSON

Leia as imagens nas partes com inlineData em candidates[].content.parts[]. Decodifique data de Base64 e use mimeType para identificar o formato da imagem.

json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "BASE64_IMAGE_DATA"
            }
          }
        ]
      }
    }
  ]
}

Guia completo de integração · Consulte o guia completo da API para ver os campos, estados de tarefas e formatos de resposta.

Recursos e limites

  • text_to_image · Compatível
  • image_to_image · Compatível
  • image_editing · Compatível
  • native_generation · Compatível
  • reference_images · Condicional — Requer imagens de referência válidas em um formato de solicitação compatível
  • Limites Imagens de referência: até 4 · Resoluções: 1k, 2k, 4k

Aliases de compatibilidade e redirecionamentos aposentados

  • gemini-3.1-flash-image → gemini-3.1-flash-image-preview (Alias)

Catálogo de recursos dos modelos · Ver preços

Guias relacionados

API de geração de imagens

Gere ou edite imagens com a API compatível com OpenAI. Envie prompts, dimensões e imagens de referência e consulte os resultados ou o status das tarefas assíncronas.

Gemini generateContent

Use a API nativa do Gemini com respostas JSON ou streaming via SSE. Informe o ID do modelo no caminho e o texto em contents[].parts[].

Catálogo de recursos dos modelos

Compare modelos públicos de texto, imagem e vídeo por ID normalizado, protocolos, clientes, ferramentas, recursos de mídia, limites e data de revisão.

Criar conta e obter uma API Key