Gerar imagens

A API Imagen permite criar imagens de alta qualidade em segundos, usando o comando de texto para orientar a geração. Também é possível aumentar imagens usando a API Imagen.

Visualizar o card do modelo Imagen para geração

Modelos compatíveis

A API Imagen oferece suporte aos seguintes modelos:

  • imagen-4-0-generate-preview-05-20 (Pré-lançamento)
  • imagen-4.0-ultra-generate-exp-05-20 (Experimental)
  • imagen-3.0-generate-002
  • imagen-3.0-generate-001
  • imagen-3.0-fast-generate-001
  • imagen-3.0-capability-001
  • imagegeneration@006
  • imagegeneration@005
  • imagegeneration@002

Para mais informações sobre os recursos compatíveis com cada modelo, consulte Modelos de imagem.

Exemplo de sintaxe

Sintaxe para criar uma imagem de um prompt de texto.

Sintaxe

Sintaxe para gerar uma imagem.

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \

https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_VERSION}:predict \
-d '{
  "instances": [
    {
      "prompt": "..."
    }
  ],
  "parameters": {
    "sampleCount": ...
  }
}'

Python

generation_model = ImageGenerationModel.from_pretrained("MODEL_VERSION")

response = generation_model.generate_images(
    prompt="...",
    negative_prompt="...",
    aspect_ratio=...,
)
response.images[0].show()

Lista de parâmetros

Confira exemplos para detalhes de implementação.

Gerar imagens

REST

Parâmetros
prompt

string

Obrigatório. O comando de texto para a imagem.
sampleCount

int

Obrigatório. O número de imagens a serem geradas. O valor padrão é 4.
seed

Uint32

Opcional. A semente aleatória para geração de imagens. Essa opção não está disponível quando addWatermark está definido como true.

Se enhancePrompt estiver definido como true, o parâmetro seed não vai funcionar, porque enhancePrompt gera uma nova solicitação, o que resulta em uma imagem nova ou diferente.

enhancePrompt

boolean

Opcional. Um parâmetro opcional para usar um recurso de alteração de comando baseado em LLM para gerar imagens de melhor qualidade que reflitam melhor a intenção do comando original. Desativar esse recurso pode afetar a qualidade da imagem e a adesão ao comando.

negativePrompt

string

Opcional. Uma descrição do que não é recomendado nas imagens geradas.

negativePrompt não é compatível com imagen-3.0-generate-002 e modelos mais recentes.

aspectRatio

string

Opcional. É a proporção da imagem. O valor padrão é "1:1".

outputOptions

outputOptions

Opcional. Descreve o formato da imagem de saída em um objeto outputOptions.

sampleImageStyle

string

Opcional. Descreve o estilo das imagens geradas. Os valores a seguir são compatíveis:

  • "photograph"
  • "digital_art"
  • "landscape"
  • "sketch"
  • "watercolor"
  • "cyberpunk"
  • "pop_art"

O sampleImageStyle é aceito apenas por imagegeneration@002

personGeneration

string

Opcional. Permite a geração de pessoas pelo modelo. Os valores a seguir são compatíveis:

  • "dont_allow": desativa a inclusão de pessoas ou rostos em imagens.
  • "allow_adult": permite a geração somente de adultos.
  • "allow_all": permite a geração de pessoas de todas as idades.

O valor padrão é "allow_adult".
language

string

Opcional. O código do idioma correspondente ao idioma do comando de texto. Os valores a seguir são compatíveis:

  • auto: detecção automática. Se o Imagen detectar um idioma compatível, o comando e um comando negativo opcional serão traduzidos para o inglês. Se o idioma detectado não for aceito, o Imagen vai usar o texto de entrada literalmente, o que pode resultar em uma saída inesperada. Nenhum código de erro é retornado.
  • en: inglês (se omitido, o valor padrão)
  • zh ou zh-CN: chinês (simplificado)
  • zh-TW: chinês (tradicional)
  • hi: Hindi
  • ja: Japonês
  • ko: Coreano
  • pt: Português
  • es: Espanhol
safetySetting

string

Opcional. Adiciona um nível de filtro à filtragem de segurança. Os valores a seguir são compatíveis:

  • "block_low_and_above": nível de filtragem mais forte, bloqueio mais rigoroso. Valor descontinuado: "block_most".
  • "block_medium_and_above": bloqueia alguns comandos e respostas problemáticos. Valor descontinuado: "block_some".
  • "block_only_high": reduz o número de solicitações bloqueadas devido aos filtros de segurança. Pode aumentar o conteúdo censurável gerado pelo Imagen. Valor descontinuado: "block_few".
  • "block_none": bloqueia poucos comandos e respostas problemáticos. O acesso a este recurso é restrito. Valor do campo anterior: "block_fewest".

O valor padrão é "block_medium_and_above".
addWatermark

bool

Opcional. Adicione uma marca-d'água invisível às imagens geradas.

O valor padrão é true, exceto para os seguintes modelos:

  • imagegeneration@002
  • imagegeneration@005
storageUri

Opcional: string

URI do Cloud Storage para armazenar as imagens geradas.

Objeto de opções de saída

O objeto outputOptions descreve a saída da imagem.

Parâmetros
outputOptions.mimeType

Opcional: string

O formato de imagem em que a saída será salva. Os valores a seguir são compatíveis:

  • "image/png": salvar como imagem PNG
  • "image/jpeg": salvar como imagem JPEG

O valor padrão é "image/png".
outputOptions.compressionQuality

Opcional: int

O nível de compactação se o tipo de saída for "image/jpeg". Os valores aceitos são de 0 a 100. O valor padrão é 75.

Resposta

O corpo da resposta da solicitação REST.

Parâmetro
predictions

Uma matriz de objetos VisionGenerativeModelResult, um para cada sampleCount solicitado. Se alguma imagem for filtrada pela IA responsável, ela não será incluída, a menos que includeRaiReason esteja definido como true.

Objeto de resultado do modelo generativo de visão

Informações sobre o resultado do modelo.

Parâmetro
bytesBase64Encoded

A imagem gerada codificada em base 64. Não estará presente se a imagem de saída não tiver passado pelos filtros de IA responsável.
mimeType

O tipo de imagem gerada. Não estará presente se a imagem de saída não tiver passado pelos filtros de IA responsável.
raiFilteredReason

O motivo do filtro da IA responsável. Retornará somente se includeRaiReason estiver ativado e a imagem tiver sido filtrada.
safetyAttributes.categories

O nome do atributo de segurança. Retornado somente se includeSafetyAttributes estiver ativado e a imagem de saída tiver passado por filtros de IA responsável.
safetyAttributes.scores

Pontuação do atributo de segurança. Retornado somente se includeSafetyAttributes estiver ativado e a imagem de saída tiver passado por filtros de IA responsável.

Python

Parâmetros
prompt

string

Obrigatório. O comando de texto para a imagem.
number_of_images

int

Obrigatório. O número de imagens a serem geradas. O valor padrão é 1.

seed

int

Opcional. A semente aleatória para geração de imagens. Essa opção não está disponível quando addWatermark está definido como true.

Se enhancePrompt estiver definido como true, o seed não vai funcionar, porque enhancePrompt gera uma nova solicitação, o que resulta em uma imagem nova ou diferente.
negative_prompt

string

Opcional. Uma descrição do que não é recomendado nas imagens geradas.

negative_prompt não é compatível com imagen-3.0-generate-002 e modelos mais recentes.

aspect_ratio

string

Opcional. É a proporção da imagem. O valor padrão é "1:1".

output_mime_type

string

Opcional. O formato de imagem em que a saída será salva. Os seguintes valores são compatíveis:

  • "image/png": salvar como imagem PNG
  • "image/jpeg": salvar como imagem JPEG

O valor padrão é "image/png".
compression_quality

int

Opcional. O nível de compactação se o tipo MIME de saída for "image/jpeg". O valor padrão é 75.

language

string

Opcional. Idioma do comando de texto da imagem. Os valores a seguir são compatíveis:

  • auto: detecção automática. Se o Imagen detectar um idioma compatível, o comando e um comando negativo opcional serão traduzidos para o inglês. Se o idioma detectado não for aceito, o Imagen vai usar o texto de entrada literalmente, o que pode resultar em uma saída inesperada. Nenhum código de erro é retornado.
  • en: inglês (se omitido, o valor padrão)
  • zh ou zh-CN: chinês (simplificado)
  • zh-TW: chinês (tradicional)
  • hi: Hindi
  • ja: Japonês
  • ko: Coreano
  • pt: Português
  • es: Espanhol

O valor padrão é "auto".
output_gcs_uri

string

Opcional. URI do Cloud Storage para armazenar as imagens geradas.
add_watermark

bool

Opcional. Adiciona uma marca-d'água à imagem gerada.

O valor padrão é true, exceto para os seguintes modelos:

  • imagegeneration@002
  • imagegeneration@005
safety_filter_level

string

Opcional. Adiciona um nível de filtro à filtragem de segurança. Os valores a seguir são compatíveis:

  • "block_low_and_above": o nível de filtragem mais forte, resultando no bloqueio mais rigoroso. Valor descontinuado: "block_most".
  • "block_medium_and_above": bloqueia alguns comandos e respostas problemáticos. Valor descontinuado: "block_some".
  • "block_only_high": bloqueia menos comandos e respostas problemáticos. Valor descontinuado: "block_few".
  • "block_none": bloqueia poucos comandos e respostas problemáticos. Valor descontinuado: "block_fewest".

O valor padrão é "block_medium_and_above".
person_generation

string

Opcional. Permite a geração de pessoas pelo modelo. Os valores a seguir são compatíveis:

  • "dont_allow": bloqueia a geração de pessoas
  • "allow_adult": gerar adultos, mas não crianças
  • "allow_all": gerar adultos e crianças

O valor padrão é "allow_adult".

Aumentar a resolução das imagens

REST

Parâmetro
mode

string

Obrigatório. Precisa ser definido como "upscale" para solicitações de escalonamento vertical.

upscaleConfig

UpscaleConfig

Obrigatório. Um objeto UpscaleConfig.

outputOptions

OutputOptions

Opcional. Descreve o formato da imagem de saída em um objeto outputOptions.

storageUri

string

Opcional. URI do Cloud Storage onde armazenar as imagens geradas.

Melhorar objeto de configuração

Parâmetro
upscaleConfig.upscaleFactor

string

Obrigatório. O fator de escalonamento. Os valores aceitos são "x2" e "x4".

Resposta

O corpo da resposta da solicitação REST.

Parâmetro
predictions

Uma matriz de objetos VisionGenerativeModelResult, um para cada sampleCount solicitado. Se alguma imagem for filtrada pela IA responsável, ela não será incluída, a menos que includeRaiReason esteja definido como true.

Exemplos

Os exemplos a seguir mostram como usar os modelos Imagen para gerar imagens.

Gerar imagens

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o Google Cloud ID do projeto.
  • MODEL_VERSION: a versão do modelo imagegeneration a ser usada. Valores disponíveis:
    • Imagen 3:
      • imagen-3.0-generate-002 (modelo mais recente)
      • imagen-3.0-generate-001
      • imagen-3.0-fast-generate-001: versão do modelo de baixa latência.
    • Versão padrão do modelo:
      • imagegeneration: usa a versão de modelo padrão v.006. Como prática recomendada, sempre especifique uma versão de modelo, principalmente em ambientes de produção.

    Para mais informações sobre versões e recursos do modelo, consulte Versões do modelo.

  • LOCATION: a região do seu projeto. Por exemplo, us-central1, europe-west2 ou asia-northeast3. Para uma lista de regiões disponíveis, consulte IA generativa em locais da Vertex AI.
  • TEXT_PROMPT: o comando de texto que orienta quais imagens o modelo gera. Este campo é obrigatório para geração e edição.
  • IMAGE_COUNT: o número de imagens geradas. Valores inteiros aceitos: 1 a 8 (imagegeneration@002), 1 a 4 (todas as outras versões de modelo). Valor padrão: 4.

    • Parâmetros opcionais adicionais

    Use as variáveis opcionais a seguir, dependendo do seu caso de uso. Adicione alguns ou todos os parâmetros abaixo no objeto "parameters": {}. Esta lista mostra parâmetros opcionais comuns e não é exaustiva. Para mais informações sobre parâmetros opcionais, consulte a Referência da API Imagen: gerar imagens. 

    "parameters": {
  "sampleCount": IMAGE_COUNT,
  "addWatermark": ADD_WATERMARK,
  "aspectRatio": "ASPECT_RATIO",
  "enhancePrompt": ENABLE_PROMPT_REWRITING,
  "includeRaiReason": INCLUDE_RAI_REASON,
  "includeSafetyAttributes": INCLUDE_SAFETY_ATTRIBUTES,
  "outputOptions": {
    "mimeType": "MIME_TYPE",
    "compressionQuality": COMPRESSION_QUALITY
  },
  "personGeneration": "PERSON_SETTING",
  "safetySetting": "SAFETY_SETTING",
  "seed": SEED_NUMBER,
  "storageUri": "OUTPUT_STORAGE_URI"
}
    • ADD_WATERMARK: booleano. Opcional. Define se uma marca-d'água será ativada para imagens geradas. Qualquer imagem gerada quando o campo está definido como true contém um SynthID digital que você pode usar para verificar uma imagem de marca d'água. Se você omitir esse campo, o valor padrão de true será usado. Defina o valor como false para desativar esse recurso. Só é possível usar o campo seed para receber uma saída determinística quando ele está definido como false.
    • ASPECT_RATIO: string. Opcional. Um parâmetro do modo de geração que controla a proporção. Valores de proporção aceitos e o uso pretendido:
      • 1:1 (padrão, quadrado)
      • 3:4 (anúncios, mídias sociais)
      • 4:3 (TV, fotografia)
      • 16:9 (paisagem)
      • 9:16 (retrato)
    • ENABLE_PROMPT_REWRITING: booleano. Opcional. Um parâmetro para usar um recurso de alteração de comando baseado em LLM para gerar imagens de melhor qualidade que reflitam melhor a intenção do comando original. Desativar esse recurso pode afetar a qualidade da imagem e a adesão ao comando. Valor padrão: true
    • INCLUDE_RAI_REASON: booleano. Opcional. Define se o código de motivo filtrado da IA responsável precisa ser ativado nas respostas com entrada ou saída bloqueada. Valor padrão: false.
    • INCLUDE_SAFETY_ATTRIBUTES: booleano. Opcional. Define se as pontuações de IA responsável arredondadas serão ativadas para uma lista de atributos de segurança nas respostas de entrada e saída não filtradas. Categorias de atributos de segurança: "Death, Harm & Tragedy", "Firearms & Weapons", "Hate", "Health", "Illicit Drugs", "Politics", "Porn", "Religion & Belief", "Toxic", "Violence", "Vulgarity", "War & Conflict". Valor padrão: false.
    • MIME_TYPE: string. Opcional. O tipo MIME do conteúdo da imagem. Valores disponíveis:
      • image/jpeg
      • image/gif
      • image/png
      • image/webp
      • image/bmp
      • image/tiff
      • image/vnd.microsoft.icon
    • COMPRESSION_QUALITY: número inteiro. Opcional. Aplica-se apenas a arquivos de saída JPEG. O nível de detalhes que o modelo preserva para imagens geradas no formato de arquivo JPEG. Valores: 0 a 100, em que um número maior significa mais compactação. Padrão: 75.
    • PERSON_SETTING: string. Opcional. A configuração de segurança que controla o tipo de pessoa ou geração de rostos permitida pelo modelo. Valores disponíveis:
      • allow_adult (padrão): permite a geração somente de adultos, exceto para celebridades. A geração de celebridades não é permitida em nenhuma configuração.
      • dont_allow: desativa a inclusão de pessoas ou rostos nas imagens geradas.
    • SAFETY_SETTING: string. Opcional. Uma configuração que controla os limites de filtro de segurança para imagens geradas. Valores disponíveis:
      • block_low_and_above: o limite de segurança mais alto, resultando na maior quantidade de imagens geradas que são filtradas. Valor anterior: block_most.
      • block_medium_and_above (padrão): um limite de segurança médio que equilibra a filtragem de conteúdo potencialmente nocivo e seguro. Valor anterior: block_some.
      • block_only_high: um limite de segurança que reduz o número de solicitações bloqueadas devido a filtros de segurança. Essa configuração pode aumentar o conteúdo censurável gerado pelo Imagen. Valor anterior: block_few.
    • SEED_NUMBER: número inteiro. Opcional. Qualquer número inteiro não negativo fornecido para tornar as imagens de saída determinísticas. Fornecer o mesmo número de origem sempre resulta nas mesmas imagens de saída. Se o modelo que você está usando for compatível com a marca d'água digital, defina "addWatermark": false para usar esse campo. Valores inteiros aceitos: 1 a 2147483647.
    • OUTPUT_STORAGE_URI: string. Opcional. O bucket do Cloud Storage para armazenar as imagens de saída. Se não forem fornecidos, os bytes de imagem codificados em base64 serão retornados na resposta. Valor de exemplo: gs://image-bucket/output/.

Método HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_VERSION:predict

Corpo JSON da solicitação:

{
  "instances": [
    {
      "prompt": "TEXT_PROMPT"
    }
  ],
  "parameters": {
    "sampleCount": IMAGE_COUNT
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_VERSION:predict"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_VERSION:predict" | Select-Object -Expand Content
O exemplo de resposta a seguir é para uma solicitação com "sampleCount": 2. A resposta retorna dois objetos de previsão, com os bytes de imagem gerados codificados em base64. 
{
  "predictions": [
    {
      "bytesBase64Encoded": "BASE64_IMG_BYTES",
      "mimeType": "image/png"
    },
    {
      "mimeType": "image/png",
      "bytesBase64Encoded": "BASE64_IMG_BYTES"
    }
  ]
}

Se você usar um modelo compatível com o aprimoramento de comando, a resposta incluirá um campo prompt adicional com o comando aprimorado usado para geração: 

{
  "predictions": [
    {
      "mimeType": "MIME_TYPE",
      "prompt": "ENHANCED_PROMPT_1",
      "bytesBase64Encoded": "BASE64_IMG_BYTES_1"
    },
    {
      "mimeType": "MIME_TYPE",
      "prompt": "ENHANCED_PROMPT_2",
      "bytesBase64Encoded": "BASE64_IMG_BYTES_2"
    }
  ]
}

Python

Antes de testar esse exemplo, siga as instruções de configuração para Python no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Python.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Neste exemplo, você chama o método generate_images no ImageGenerationModel (versão @006) e salva as imagens geradas localmente. Em seguida, é possível usar o método show() em um notebook para mostrar as imagens geradas. Para mais informações sobre versões e atributos de modelos, consulte Versões do modelo.


import vertexai
from vertexai.preview.vision_models import ImageGenerationModel

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# output_file = "input-image.png"
# prompt = "" # The text prompt describing what you want to see.

vertexai.init(project=PROJECT_ID, location="us-central1")

model = ImageGenerationModel.from_pretrained("imagen-3.0-generate-002")

images = model.generate_images(
    prompt=prompt,
    # Optional parameters
    number_of_images=1,
    language="en",
    # You can't use a seed value and watermark at the same time.
    # add_watermark=False,
    # seed=100,
    aspect_ratio="1:1",
    safety_filter_level="block_some",
    person_generation="allow_adult",
)

images[0].save(location=output_file, include_generation_parameters=False)

# Optional. View the generated image in a notebook.
# images[0].show()

print(f"Created output image using {len(images[0]._image_bytes)} bytes")
# Example response:
# Created output image using 1234567 bytes

Aumentar a resolução das imagens

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: a região do seu projeto. Por exemplo, us-central1, europe-west2 ou asia-northeast3. Para uma lista de regiões disponíveis, consulte IA generativa em locais da Vertex AI.
  • PROJECT_ID: o Google Cloud ID do projeto.
  • B64_BASE_IMAGE: a imagem de base que será editada ou aprimorada. A imagem precisa ser especificada como uma string de bytes codificada em base64. Limite de tamanho: 10 MB.
  • IMAGE_SOURCE: o local do Cloud Storage da imagem que você quer editar ou aprimorar. Por exemplo, gs://output-bucket/source-photos/photo.png.
  • UPSCALE_FACTOR: opcional. O fator para o qual a imagem será aumentada. Se não for especificado, o fator de luxo será determinado pelo lado maior da imagem de entrada e sampleImageSize. Valores disponíveis: x2 ou x4.

Método HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/imagegeneration@002:predict

Corpo JSON da solicitação:

{
  "instances": [
    {
      "prompt": "",
      "image": {
        // use one of the following to specify the image to upscale
        "bytesBase64Encoded": "B64_BASE_IMAGE"
        "gcsUri": "IMAGE_SOURCE"
        // end of base image input options
      },
    }
  ],
  "parameters": {
    "sampleCount": 1,
    "mode": "upscale",
    "upscaleConfig": {
      "upscaleFactor": "UPSCALE_FACTOR"
    }
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/imagegeneration@002:predict"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/imagegeneration@002:predict" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "predictions": [
    {
      "mimeType": "image/png",
      "bytesBase64Encoded": "iVBOR..[base64-encoded-upscaled-image]...YII="
    }
  ]
}

A seguir

Anterior
Gerar imagens usando solicitações de texto