API Image Generation

A API Imagen permite-lhe gerar imagens de alta qualidade em segundos, usando um comando de texto para orientar a geração.

Veja o cartão do modelo Imagen for Generation

Versões de modelos suportadas

A API Imagen suporta os seguintes modelos:

  • imagen-4.0-generate-001
  • imagen-4.0-fast-generate-001
  • imagen-4.0-ultra-generate-001
  • imagen-3.0-generate-002
  • imagen-3.0-generate-001
  • imagen-3.0-fast-generate-001
  • imagen-3.0-capability-001

Para mais informações sobre as funcionalidades suportadas por cada modelo, consulte os modelos do Imagen.

Sintaxe de exemplo

Sintaxe para criar uma imagem a partir de um comando 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()

Gerar imagens

REST

Parâmetros
addWatermark

bool

Opcional. Adicionar uma marca de água invisível às imagens geradas.

O valor predefinido é true.

aspectRatio

string

Opcional. O formato da imagem de saída gerada. O valor predefinido é "1:1".

enhancePrompt

boolean

Opcional. Um parâmetro opcional para usar uma funcionalidade de reescrita de comandos baseada em MDIs para fornecer imagens de maior qualidade que reflitam melhor a intenção do comando original. A desativação desta funcionalidade pode afetar a qualidade da imagem e a conformidade com os comandos.

language

string

Opcional. O código do idioma que corresponde ao idioma do comando de texto. Os seguintes valores são suportados:

  • auto: Deteção automática. Se o Imagen detetar um idioma suportado, o comando e um comando negativo opcional são traduzidos para inglês. Se o idioma detetado não for suportado, o Imagen usa o texto de entrada na íntegra, o que pode resultar num resultado inesperado. Não é devolvido nenhum código de erro.
  • en: inglês (se for omitido, o valor predefinido)
  • zh ou zh-CN: chinês (simplificado)
  • zh-TW: chinês (tradicional)
  • hi: hindi
  • ja: japonês
  • ko: coreano
  • pt: português
  • es: espanhol
negativePrompt

string

Opcional. Uma descrição do que deve ser evitado nas imagens geradas.

O negativePrompt não é suportado pelo imagen-3.0-generate-002 e modelos mais recentes.

outputOptions

outputOptions

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

prompt

string

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

string

Opcional. Permitir a geração de pessoas pelo modelo. Os seguintes valores são suportados:

  • "dont_allow": Não permitir a inclusão de pessoas ou rostos em imagens.
  • "allow_adult": permitir a geração de conteúdo apenas para adultos.
  • "allow_all": permitir a geração de pessoas de todas as idades.

O valor predefinido é "allow_adult".
safetySetting

string

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

  • "block_low_and_above": o nível de filtragem mais forte, o bloqueio mais restritivo. Valor descontinuado: "block_most".
  • "block_medium_and_above": Bloquear alguns comandos e respostas problemáticos. Valor descontinuado: "block_some".
  • "block_only_high": reduz o número de pedidos bloqueados devido a filtros de segurança. Pode aumentar o conteúdo censurado gerado pelo Imagen. Valor descontinuado: "block_few".
  • "block_none": bloquear muito poucos comandos e respostas problemáticos. O acesso a esta funcionalidade está restrito. Valor do campo anterior: "block_fewest".

O valor predefinido é "block_medium_and_above".
sampleCount

int

Obrigatório. O número de imagens a gerar. O valor predefinido é 4.
sampleImageSize

string

Opcional. Especifica a resolução de saída da imagem gerada. Os valores aceites são "1K" ou "2K". O valor predefinido é "1K".

seed

Uint32

Opcional. A semente aleatória para a geração de imagens. Esta 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 funciona porque enhancePrompt gera um novo comando, o que resulta numa imagem nova ou diferente.

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 no qual a saída deve ser guardada. Os seguintes valores são suportados:

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

O valor predefinido é "image/png".
outputOptions.compressionQuality

Opcional: int

O nível de compressão se o tipo de saída for "image/jpeg". Os valores aceites são de 0 a 100. O valor predefinido é 75.

Resposta

O corpo da resposta do pedido REST.

Parâmetro
predictions Uma matriz de objetos VisionGenerativeModelResult, um para cada sampleCount pedido. Se alguma imagem for filtrada pela IA responsável, não é 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 base64. Não está presente se a imagem de saída não tiver passado nos filtros de IA responsável.
mimeType

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

O motivo do filtro de IA responsável. Só é devolvido se includeRaiReason estiver ativado e esta imagem tiver sido filtrada.
safetyAttributes.categories

O nome do atributo de segurança. Só é devolvido se includeSafetyAttributes estiver ativado e a imagem de saída tiver passado nos filtros de IA responsável.
safetyAttributes.scores

A pontuação do atributo de segurança. Só é devolvido se includeSafetyAttributes estiver ativado e a imagem de saída tiver passado nos filtros de IA responsável.

Python

Parâmetros
add_watermark

bool

Opcional. Adicionar uma marca de água à imagem gerada.

O valor predefinido é true.

aspect_ratio

string

Opcional. O formato da imagem de saída gerada. O valor predefinido é "1:1".

compression_quality

int

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

language

string

Opcional. O idioma do comando de texto para a imagem. Os seguintes valores são suportados:

  • auto: Deteção automática. Se o Imagen detetar um idioma suportado, o comando e um comando negativo opcional são traduzidos para inglês. Se o idioma detetado não for suportado, o Imagen usa o texto de entrada na íntegra, o que pode resultar num resultado inesperado. Não é devolvido nenhum código de erro.
  • en: inglês (se for omitido, o valor predefinido)
  • 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 predefinido é "auto".
negative_prompt

string

Opcional. Uma descrição do que deve ser evitado nas imagens geradas.

O negative_prompt não é suportado pelo imagen-3.0-generate-002 e modelos mais recentes.

number_of_images

int

Obrigatório. O número de imagens a gerar. O valor predefinido é 1.

output_gcs_uri

string

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

string

Opcional. O formato de imagem no qual a saída deve ser guardada. Os seguintes valores são suportados:

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

O valor predefinido é "image/png".
prompt

string

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

string

Opcional. Permitir a geração de pessoas pelo modelo. Os seguintes valores são suportados:

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

O valor predefinido é "allow_adult".
safety_filter_level

string

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

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

O valor predefinido é "block_medium_and_above".
sample_image_size

string

Opcional. Especifica a resolução de saída da imagem gerada. Os valores aceites são "1K" ou "2K". O valor predefinido é "1K".

seed

int

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

Se enhancePrompt estiver definido como true, o comando seed não funciona, porque enhancePrompt gera um novo comando, o que resulta numa imagem nova ou diferente.

Exemplos

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

Gerar imagens

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • REGION: a região onde o seu projeto está localizado. Para mais informações sobre as regiões suportadas, consulte as localizações da IA generativa no Vertex AI.
  • PROJECT_ID: O seu Google Cloud ID do projeto.

  • MODEL_VERSION: a versão do modelo Imagen a usar. Para mais informações sobre os modelos disponíveis, consulte os modelos Imagen.

  • TEXT_PROMPT: o comando de texto que orienta as imagens que o modelo gera. Este campo é obrigatório para a geração e a edição.
  • IMAGE_COUNT: o número de imagens a gerar. O intervalo de valores aceite é de 1 a 4.

    • Parâmetros opcionais adicionais

    Use as seguintes variáveis opcionais consoante o seu exemplo de utilização. Adicione alguns ou todos os seguintes parâmetros no objeto "parameters": {}. Esta lista mostra parâmetros opcionais comuns e não se destina a ser 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. Se deve ativar uma marca de água para imagens geradas. Qualquer imagem gerada quando o campo está definido como true contém um SynthID digital que pode usar para validar uma imagem com marca de água. Se omitir este campo, é usado o valor predefinido de true. Tem de definir o valor como false para desativar esta funcionalidade. Pode usar o campo seed para obter um resultado determinístico apenas quando este campo estiver definido como false.
    • ASPECT_RATIO: string. Opcional. Um parâmetro do modo de geração que controla o formato. Valores de proporção suportados e a respetiva utilização prevista:
      • 1:1 (predefinição, quadrada)
      • 3:4 (anúncios, redes sociais)
      • 4:3 (TV, fotografia)
      • 16:9 (horizontal)
      • 9:16 (vertical)
    • ENABLE_PROMPT_REWRITING: booleano. Opcional. Um parâmetro para usar uma funcionalidade de reescrita de comandos baseada em MDIs para fornecer imagens de maior qualidade que reflitam melhor a intenção do comando original. A desativação desta funcionalidade pode afetar a qualidade da imagem e a conformidade com os comandos. Valor predefinido: true.
    • INCLUDE_RAI_REASON: booleano. Opcional. Se deve ativar o código do motivo filtrado da IA responsável em respostas com entrada ou saída bloqueada. Valor predefinido: true.
    • INCLUDE_SAFETY_ATTRIBUTES: booleano. Opcional. Se deve ativar as pontuações de IA responsável arredondadas para uma lista de atributos de segurança nas respostas para 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" e "War & Conflict". Valor predefinido: 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 ficheiros de saída JPEG. O nível de detalhe que o modelo preserva para imagens geradas no formato de ficheiro JPEG. Valores: 0 a 100, em que um número mais elevado significa mais compressão. Predefinição: 75.
    • PERSON_SETTING: string. Opcional. A definição de segurança que controla o tipo de pessoas ou geração de rostos que o modelo permite. Valores disponíveis:
      • allow_adult (predefinição): permitir a geração de conteúdo apenas para adultos, exceto a geração de conteúdo com celebridades. A geração de celebridades não é permitida para nenhuma definição.
      • dont_allow: desative a inclusão de pessoas ou rostos em imagens geradas.
    • SAFETY_SETTING: string. Opcional. Uma definição que controla os limites dos filtros de segurança para imagens geradas. Valores disponíveis:
      • block_low_and_above: o limite de segurança mais elevado, o que resulta na maior quantidade de imagens geradas filtradas. Valor anterior: block_most.
      • block_medium_and_above (predefinição): um limite de segurança médio que equilibra a filtragem de conteúdo potencialmente prejudicial e seguro. Valor anterior: block_some.
      • block_only_high: um limite de segurança que reduz o número de pedidos bloqueados devido a filtros de segurança. Esta definiçã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 que fornecer para tornar as imagens de saída determinísticas. Indicar o mesmo número aleatório resulta sempre nas mesmas imagens de saída. Se o modelo que está a usar suportar marcas de água digitais, tem de definir "addWatermark": false para usar este campo. Valores inteiros aceites: 1 a 2147483647.
    • OUTPUT_STORAGE_URI: string. Opcional. O contentor do Cloud Storage para armazenar as imagens de saída. Se não for fornecido, os bytes da imagem codificados em base64 são devolvidos na resposta. Valor de exemplo: gs://image-bucket/output/.

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

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

PowerShell

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$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://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/MODEL_VERSION:predict" | Select-Object -Expand Content
A seguinte resposta de exemplo destina-se a um pedido com "sampleCount": 2. A resposta devolve dois objetos de previsão, com os bytes da imagem gerada codificados em base64. 
{
  "predictions": [
    {
      "bytesBase64Encoded": "BASE64_IMG_BYTES",
      "mimeType": "image/png"
    },
    {
      "mimeType": "image/png",
      "bytesBase64Encoded": "BASE64_IMG_BYTES"
    }
  ]
}

Se usar um modelo que suporte o melhoramento de comandos, a resposta inclui um campo prompt adicional com o comando melhorado usado para a 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 experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Python Vertex AI.

Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

Neste exemplo, chama o método generate_images no ImageGenerationModel (versão @006) e guarda as imagens geradas localmente. Em seguida, pode usar opcionalmente o método show() num bloco de notas para ver as imagens geradas. Para mais informações sobre as versões e as funcionalidades dos modelos, consulte o artigo Versões dos modelos.


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

O que se segue?