Imagen API in Python gebruiken

Overzicht van de Imagen API

Imagen is het tekst-naar-beeldmodel van Google. Je benadert het programmatisch op twee manieren:

1. Vertex AI (aanbevolen voor productie): authenticatie via Google Cloud-credentials, hogere quota, edit- en upscale-functies. In dit artikel de hoofdroute.
2. Gemini API (voor lagere volumes en snelle proefjes): authenticatie met een API-key.

Sinds 2025 verloopt beide routes via dezelfde bibliotheek: de Google Gen AI SDK (google-genai, importnaam google.genai). Je kiest met een vlag of je tegen Vertex AI of de Gemini API praat. Eén codebasis, twee backends.

Welk model kies je

In juni 2026 is Imagen 4 de nieuwste generatie op Vertex AI. Veelgebruikte modelnamen:

Modelnamen en beschikbaarheid per regio veranderen regelmatig. Bevestig de naam die in jouw regio actief is in de Vertex AI-modeldocumentatie voor je hardcodeert.

Vereisten

Installatie

pip install google-genai pillow

Gebruik een vaste versie (pin) in je requirements.txt, bijvoorbeeld google-genai==1.* met een exacte patchversie, zodat builds reproduceerbaar blijven.

Authenticatie

Voor lokaal ontwikkelen met je eigen Google-account:

gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT="jouw-project-id"

In productie gebruik je een service account. Op Cloud Run, Cloud Functions of een VM met de juiste IAM-rol (roles/aiplatform.user) hoef je geen sleutelbestand mee te geven; de omgeving levert de credentials automatisch. Een sleutelbestand op schijf is een veiligheidsrisico en alleen nodig buiten Google Cloud:

import os
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/pad/naar/credentials.json"

Basisgebruik

from google import genai
from google.genai import types

client = genai.Client(
    vertexai=True,
    project="jouw-project-id",
    location="us-central1",
)

response = client.models.generate_images(
    model="imagen-4.0-generate-001",
    prompt="Een professionele workspacefoto van mensen die samenwerken op laptops, daglicht, fotorealistisch",
    config=types.GenerateImagesConfig(
        number_of_images=1,
        aspect_ratio="16:9",
        person_generation="allow_adult",
    ),
)

response.generated_images[0].image.save("output.png")
print("Afbeelding opgeslagen als output.png")

De image-objecten in response.generated_images hebben een save(pad)-methode en een attribuut image_bytes met de ruwe bytes, handig als je niet naar schijf wilt schrijven.

Veelgebruikte parameters

Je geeft parameters mee via types.GenerateImagesConfig(...):

Het genereren van afbeeldingen van kinderen is niet toegestaan, ook niet met allow_all. Welke parameters een model precies ondersteunt verschilt per modelversie; controleer de parameterdocumentatie bij twijfel.

Negatieve prompts

Met een negatieve prompt stuur je bij wat je juist wilt vermijden:

response = client.models.generate_images(
    model="imagen-4.0-generate-001",
    prompt="Professionele kantooromgeving met moderne meubels",
    config=types.GenerateImagesConfig(
        number_of_images=2,
        aspect_ratio="16:9",
        negative_prompt="rommel, slechte belichting, mensen, tekst, logo's",
    ),
)

Afbeelding verwerken met Pillow

Wil je de afbeelding nabewerken (formaat aanpassen, comprimeren naar WebP) zonder eerst naar schijf te schrijven, gebruik dan de ruwe bytes:

from PIL import Image
from io import BytesIO

for i, generated in enumerate(response.generated_images):
    pil_image = Image.open(BytesIO(generated.image.image_bytes)).convert("RGB")
    pil_image.thumbnail((1280, 720))
    pil_image.save(f"output_{i}.webp", "WEBP", quality=85)

Een afbeelding bewerken (inpainting)

Voor inpainting of het vervangen van een gebied gebruik je edit_image met referentiebeelden. Dit draait op het capability-model en is alleen op Vertex AI beschikbaar:

from google.genai import types

raw_ref = types.RawReferenceImage(
    reference_image=types.Image.from_file(location="referentie.jpg"),
    reference_id=0,
)

response = client.models.edit_image(
    model="imagen-3.0-capability-001",
    prompt="Vervang de achtergrond door een moderne kantooromgeving",
    reference_images=[raw_ref],
    config=types.EditImageConfig(
        edit_mode="EDIT_MODE_INPAINT_INSERTION",
        number_of_images=1,
    ),
)

response.generated_images[0].image.save("bewerkt.png")

Foutafhandeling

Vang quota- en validatiefouten apart af, zodat je gericht kunt reageren:

import time
from google.genai import errors

try:
    response = client.models.generate_images(
        model="imagen-4.0-generate-001",
        prompt=prompt,
        config=types.GenerateImagesConfig(number_of_images=1),
    )
except errors.ClientError as e:
    if e.code == 429:
        print(f"Quota overschreden, wacht en probeer opnieuw: {e}")
        time.sleep(60)
    else:
        print(f"Ongeldige aanvraag of geblokkeerde prompt: {e}")
except errors.ServerError as e:
    print(f"Serverfout aan Google-kant: {e}")
    raise

De SDK groepeert fouten in ClientError (4xx, zoals een geweigerde prompt of overschreden quota) en ServerError (5xx). Het HTTP-statusnummer staat in e.code.

Flask-endpoint als voorbeeld

Een eenvoudige REST-endpoint die Imagen aanroept en een WebP teruggeeft:

from flask import Flask, request, jsonify, send_file
from io import BytesIO
from google import genai
from google.genai import types

app = Flask(__name__)
client = genai.Client(vertexai=True, project="jouw-project-id", location="us-central1")

@app.route("/genereer", methods=["POST"])
def genereer():
    data = request.get_json(silent=True) or {}
    prompt = data.get("prompt", "").strip()
    if not prompt or len(prompt) > 2000:
        return jsonify({"fout": "Ongeldige prompt"}), 400

    response = client.models.generate_images(
        model="imagen-4.0-generate-001",
        prompt=prompt,
        config=types.GenerateImagesConfig(number_of_images=1, aspect_ratio="16:9"),
    )

    buffer = BytesIO(response.generated_images[0].image.image_bytes)
    buffer.seek(0)
    return send_file(buffer, mimetype="image/png")

if __name__ == "__main__":
    app.run(debug=False)

Verder kijken: Gemini-beeldmodellen

Naast Imagen biedt Google ook beeldgeneratie via de Gemini-modellen (informeel "Nano Banana" genoemd). Die zijn sterk in conversationeel bewerken en het combineren van tekst en beeld in één gesprek. Voor strakke, hoogwaardige tekst-naar-beeld blijft Imagen 4 doorgaans de eerste keuze. Weeg per use case af wat past, en houd de releasenotes in de gaten, want dit veld beweegt snel.