API de generación de imágenes

La API Imagen te permite generar imágenes de alta calidad en segundos mediante una petición de texto para guiar la generación.

Ver la tarjeta de modelo de Imagen para generación

Versiones de modelo admitidas

La API Imagen admite los siguientes 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 obtener más información sobre las funciones que admite cada modelo, consulta Modelos de Imagen.

Sintaxis de ejemplo

Sintaxis para crear una imagen a partir de una petición de texto.

Sintaxis

Sintaxis para generar una imagen.

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()

Generar imágenes

REST

Parámetros
addWatermark

bool

Opcional. Añade una marca de agua invisible a las imágenes generadas.

El valor predeterminado es true.

aspectRatio

string

Opcional. La relación de aspecto de la imagen de salida generada. El valor predeterminado es "1:1".

enhancePrompt

boolean

Opcional. Parámetro opcional para usar una función de reescritura de peticiones basada en LLMs con el fin de ofrecer imágenes de mayor calidad que reflejen mejor la intención de la petición original. Si inhabilitas esta función, puede que la calidad de las imágenes y la adecuación de las peticiones se vean afectadas.

language

string

Opcional. El código de idioma que corresponde al idioma de tu petición de texto. Se admiten los siguientes valores:

  • auto: detección automática. Si Imagen detecta un idioma admitido, la petición y una petición negativa opcional se traducen al inglés. Si el idioma detectado no es compatible, Imagen usa el texto de entrada tal cual, lo que puede dar lugar a un resultado inesperado. No se devuelve ningún código de error.
  • en: inglés (si se omite, se usa el valor predeterminado)
  • zh o zh-CN: chino (simplificado)
  • zh-TW: chino (tradicional)
  • hi: hindi
  • ja: japonés
  • ko: coreano
  • pt: portugués
  • es: español
negativePrompt

string

Opcional. Una descripción de lo que no debe aparecer en las imágenes generadas.

negativePrompt no es compatible con imagen-3.0-generate-002 ni con modelos más recientes.

outputOptions

outputOptions

Opcional. Describe el formato de la imagen de salida en un outputOptions objeto.

prompt

string

Obligatorio. La petición de texto de la imagen.
personGeneration

string

Opcional. Permitir que el modelo genere personas. Se admiten los siguientes valores:

  • "dont_allow": no permitir que se incluyan personas o caras en las imágenes.
  • "allow_adult": permite generar contenido solo para adultos.
  • "allow_all": permite generar imágenes de personas de todas las edades.

El valor predeterminado es "allow_adult".
safetySetting

string

Opcional. Añade un nivel de filtro al filtro de seguridad. Se admiten los siguientes valores:

  • "block_low_and_above": nivel de filtrado más alto, bloqueo más estricto. Valor obsoleto: "block_most".
  • "block_medium_and_above": bloquea algunas peticiones y respuestas problemáticas. Valor obsoleto: "block_some".
  • "block_only_high": reduce el número de solicitudes bloqueadas debido a los filtros de seguridad. Puede aumentar el contenido inapropiado generado por Imagen. Valor obsoleto: "block_few".
  • "block_none": bloquea muy pocas peticiones y respuestas problemáticas. El acceso a esta función está restringido. Valor del campo anterior: "block_fewest".

El valor predeterminado es "block_medium_and_above".
sampleCount

int

Obligatorio. Número de imágenes que se van a generar. El valor predeterminado es 4.
sampleImageSize

string

Opcional. Especifica la resolución de salida de la imagen generada. Los valores aceptados son "1K" y "2K". El valor predeterminado es "1K".

seed

Uint32

Opcional. Semilla aleatoria para la generación de imágenes. Esta opción no está disponible cuando addWatermark está configurado como true.

Si enhancePrompt se define como true, el parámetro seed no funcionará, ya que enhancePrompt genera una nueva petición, lo que da como resultado una imagen nueva o diferente.

storageUri

Opcional: string

URI de Cloud Storage para almacenar las imágenes generadas.

Objeto de opciones de salida

El objeto outputOptions describe la salida de la imagen.

Parámetros
outputOptions.mimeType

Opcional: string

El formato de imagen en el que se debe guardar la salida. Se admiten los siguientes valores:

  • "image/png": guardar como imagen PNG
  • "image/jpeg": guardar como imagen JPEG

El valor predeterminado es "image/png".
outputOptions.compressionQuality

Opcional: int

El nivel de compresión si el tipo de salida es "image/jpeg". Los valores aceptados van del 0 al 100. El valor predeterminado es 75.

Respuesta

Cuerpo de la respuesta de la solicitud REST.

Parámetro
predictions Matriz de objetos VisionGenerativeModelResult, uno por cada sampleCount solicitado. Si la IA responsable filtra alguna imagen, no se incluirá, a menos que includeRaiReason se defina como true.

Objeto de resultado del modelo generativo de Vision

Información sobre el resultado del modelo.

Parámetro
bytesBase64Encoded

Imagen generada codificada en base64. No está presente si la imagen de salida no ha superado los filtros de IA responsable.
mimeType

El tipo de imagen generada. No está presente si la imagen de salida no ha superado los filtros de IA responsable.
raiFilteredReason

Motivo del filtro de IA responsable. Solo se devuelve si includeRaiReason está habilitado y esta imagen se ha filtrado.
safetyAttributes.categories

Nombre del atributo de seguridad. Solo se devuelve si includeSafetyAttributes está habilitado y la imagen de salida ha superado los filtros de IA responsable.
safetyAttributes.scores

Puntuación del atributo de seguridad. Solo se devuelve si includeSafetyAttributes está habilitado y la imagen de salida ha superado los filtros de IA responsable.

Python

Parámetros
add_watermark

bool

Opcional. Añade una marca de agua a la imagen generada.

El valor predeterminado es true.

aspect_ratio

string

Opcional. La relación de aspecto de la imagen de salida generada. El valor predeterminado es "1:1".

compression_quality

int

Opcional. El nivel de compresión si el tipo MIME de salida es "image/jpeg". El valor predeterminado es 75.

language

string

Opcional. El idioma de la petición de texto de la imagen. Se admiten los siguientes valores:

  • auto: detección automática. Si Imagen detecta un idioma admitido, la petición y una petición negativa opcional se traducen al inglés. Si el idioma detectado no es compatible, Imagen usa el texto de entrada tal cual, lo que puede dar lugar a un resultado inesperado. No se devuelve ningún código de error.
  • en: inglés (si se omite, se usa el valor predeterminado)
  • zh o zh-CN: chino (simplificado)
  • zh-TW: chino (tradicional)
  • hi: hindi
  • ja: japonés
  • ko: coreano
  • pt: portugués
  • es: español

El valor predeterminado es "auto".
negative_prompt

string

Opcional. Una descripción de lo que no debe aparecer en las imágenes generadas.

negative_prompt no es compatible con imagen-3.0-generate-002 ni con modelos posteriores.

number_of_images

int

Obligatorio. Número de imágenes que se van a generar. El valor predeterminado es 1.

output_gcs_uri

string

Opcional. URI de Cloud Storage para almacenar las imágenes generadas.
output_mime_type

string

Opcional. El formato de imagen en el que se debe guardar la salida. Se admiten los siguientes valores:

  • "image/png": guardar como imagen PNG
  • "image/jpeg": guardar como imagen JPEG

El valor predeterminado es "image/png".
prompt

string

Obligatorio. La petición de texto de la imagen.
person_generation

string

Opcional. Permitir que el modelo genere personas. Se admiten los siguientes valores:

  • "dont_allow": bloquear la generación de personas
  • "allow_adult": genera adultos, pero no niños
  • "allow_all": generar adultos y niños

El valor predeterminado es "allow_adult".
safety_filter_level

string

Opcional. Añade un nivel de filtro al filtro de seguridad. Se admiten los siguientes valores:

  • "block_low_and_above": el nivel de filtrado más alto, que da como resultado el bloqueo más estricto. Valor obsoleto: "block_most".
  • "block_medium_and_above": bloquea algunas peticiones y respuestas problemáticas. Valor obsoleto: "block_some".
  • "block_only_high": bloquea menos peticiones y respuestas problemáticas. Valor obsoleto: "block_few".
  • "block_none": bloquea muy pocas peticiones y respuestas problemáticas. Valor obsoleto: "block_fewest".

El valor predeterminado es "block_medium_and_above".
sample_image_size

string

Opcional. Especifica la resolución de salida de la imagen generada. Los valores aceptados son "1K" y "2K". El valor predeterminado es "1K".

seed

int

Opcional. Semilla aleatoria para la generación de imágenes. Esta opción no está disponible cuando addWatermark está configurado como true.

Si enhancePrompt se define como true, seed no funcionará, ya que enhancePrompt genera una nueva petición, lo que da como resultado una imagen nueva o diferente.

Ejemplos

En los siguientes ejemplos se muestra cómo usar los modelos de Imagen para generar imágenes.

Generar imágenes

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • REGION: la región en la que se encuentra tu proyecto. Para obtener más información sobre las regiones admitidas, consulta las ubicaciones de la IA generativa en Vertex AI.
  • PROJECT_ID: tu Google Cloud ID de proyecto.

  • MODEL_VERSION: la versión del modelo Imagen que se va a usar. Para obtener más información sobre los modelos disponibles, consulta Modelos de Imagen.

  • TEXT_PROMPT: la petición de texto que indica qué imágenes debe generar el modelo. Este campo es obligatorio tanto para generar como para editar.
  • IMAGE_COUNT: número de imágenes que se van a generar. El intervalo de valores aceptado es de 1 a 4.

    • Parámetros opcionales adicionales

    Usa las siguientes variables opcionales según tu caso práctico. Añade algunos o todos los parámetros siguientes en el objeto "parameters": {}. Esta lista muestra parámetros opcionales habituales y no es exhaustiva. Para obtener más información sobre los parámetros opcionales, consulta la referencia de la API Imagen: generar imágenes. 

    "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. Si quieres habilitar una marca de agua en las imágenes generadas. Las imágenes generadas cuando el campo se define como true contienen una marca de agua digital SynthID que puedes usar para verificar una imagen con marca de agua. Si omite este campo, se usará el valor predeterminado true. Para inhabilitar esta función, debe asignar el valor false. Puede usar el campo seed para obtener resultados deterministas solo cuando este campo tenga el valor false.
    • ASPECT_RATIO: cadena. Opcional. Un parámetro del modo de generación que controla la relación de aspecto. Valores de relación de aspecto admitidos y su uso previsto:
      • 1:1 (predeterminado, cuadrado)
      • 3:4 (anuncios, redes sociales)
      • 4:3 (televisión, fotografía)
      • 16:9 (horizontal)
      • 9:16 (vertical)
    • ENABLE_PROMPT_REWRITING: booleano. Opcional. Parámetro para usar una función de reescritura de peticiones basada en LLMs para ofrecer imágenes de mayor calidad que reflejen mejor la intención de la petición original. Si inhabilitas esta función, puede que la calidad de la imagen y la adecuación a la petición se vean afectadas. Valor predeterminado: true.
    • INCLUDE_RAI_REASON: booleano. Opcional. Indica si se debe habilitar el código de motivo filtrado de IA responsable en las respuestas con entradas o salidas bloqueadas. Valor predeterminado: true.
    • INCLUDE_SAFETY_ATTRIBUTES: booleano. Opcional. Indica si se deben habilitar las puntuaciones de IA responsable redondeadas para una lista de atributos de seguridad en las respuestas de entrada y salida sin filtrar. Categorías de atributos de seguridad: "Death, Harm & Tragedy", "Firearms & Weapons", "Hate", "Health", "Illicit Drugs", "Politics", "Porn", "Religion & Belief", "Toxic", "Violence", "Vulgarity" y "War & Conflict". Valor predeterminado: false.
    • MIME_TYPE: cadena. Opcional. Tipo MIME del contenido de la imagen. Valores disponibles:
      • image/jpeg
      • image/gif
      • image/png
      • image/webp
      • image/bmp
      • image/tiff
      • image/vnd.microsoft.icon
    • COMPRESSION_QUALITY: número entero. Opcional. Solo se aplica a los archivos de salida JPEG. El nivel de detalle que conserva el modelo en las imágenes generadas en formato de archivo JPEG. Valores: 0 a 100, donde un número más alto significa más compresión. Predeterminado: 75.
    • PERSON_SETTING: cadena. Opcional. El ajuste de seguridad que controla el tipo de personas o la generación de caras que permite el modelo. Valores disponibles:
      • allow_adult (valor predeterminado): permite generar contenido solo para adultos, excepto si se trata de famosos. No se permite generar imágenes de famosos en ningún ajuste.
      • dont_allow: inhabilita la inclusión de personas o caras en las imágenes generadas.
    • SAFETY_SETTING: cadena. Opcional. Un ajuste que controla los umbrales del filtro de seguridad de las imágenes generadas. Valores disponibles:
      • block_low_and_above: el umbral de seguridad más alto, lo que da como resultado la mayor cantidad de imágenes generadas que se filtran. Valor anterior: block_most.
      • block_medium_and_above (opción predeterminada): umbral de seguridad medio que equilibra el filtrado de contenido potencialmente dañino y seguro. Valor anterior: block_some.
      • block_only_high: umbral de seguridad que reduce el número de solicitudes bloqueadas debido a los filtros de seguridad. Este ajuste puede aumentar el contenido inapropiado generado por Imagen. Valor anterior: block_few.
    • SEED_NUMBER: número entero. Opcional. Cualquier número entero no negativo que proporciones para que las imágenes de salida sean deterministas. Si se proporciona el mismo número de semilla, siempre se obtendrán las mismas imágenes. Si el modelo que estás usando admite marcas de agua digitales, debes definir "addWatermark": false para usar este campo. Valores enteros aceptados: 1 - 2147483647.
    • OUTPUT_STORAGE_URI: cadena. Opcional. El segmento de Cloud Storage donde se almacenarán las imágenes de salida. Si no se proporciona, se devuelven bytes de imagen codificados en Base64 en la respuesta. Valor de ejemplo: gs://image-bucket/output/.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud: 

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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
La siguiente respuesta de ejemplo corresponde a una solicitud con "sampleCount": 2. La respuesta devuelve dos objetos de predicción con los bytes de la imagen generada codificados en Base64. 
{
  "predictions": [
    {
      "bytesBase64Encoded": "BASE64_IMG_BYTES",
      "mimeType": "image/png"
    },
    {
      "mimeType": "image/png",
      "bytesBase64Encoded": "BASE64_IMG_BYTES"
    }
  ]
}

Si usas un modelo que admite la mejora de las peticiones, la respuesta incluye un campo prompt adicional con la petición mejorada que se ha usado para la generación: 

{
  "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 probar este ejemplo, sigue las instrucciones de configuración de Python que se indican en la guía de inicio rápido de Vertex AI con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de Vertex AI.

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.

En este ejemplo, se llama al método generate_images en ImageGenerationModel (versión @006) y se guardan las imágenes generadas de forma local. Después, puedes usar el método show() en un cuaderno para ver las imágenes generadas. Para obtener más información sobre las versiones y las funciones de los modelos, consulta Versiones de los 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

Siguientes pasos