# Imagen API in Python gebruiken

[[TOC]]

## 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.

:::warn title="De oude SDK is uitgefaseerd"
De oudere modules `vertexai.vision_models` en `vertexai.preview.vision_models` (met `ImageGenerationModel.from_pretrained(...)` en modelnamen als `imagegeneration@006`) zijn vervangen door de Google Gen AI SDK en stoppen rond 24 juni 2026. Nieuwe code schrijf je met `from google import genai`. Bestaande code migreer je. Controleer de actuele situatie in de [migratiegids van Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/deprecations/genai-vertexai-sdk).
:::

## Welk model kies je

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

| Modelnaam | Wanneer |
|---|---|
| `imagen-4.0-generate-001` | Nieuwste, hoogste kwaliteit |
| `imagen-3.0-generate-002` | Stabiele vorige generatie |
| `imagen-3.0-capability-001` | Voor edit- en inpainting-taken |

Modelnamen en beschikbaarheid per regio veranderen regelmatig. Bevestig de naam die in jouw regio actief is in de [Vertex AI-modeldocumentatie](https://cloud.google.com/vertex-ai/generative-ai/docs/models) voor je hardcodeert.

## Vereisten

### Installatie

```bash
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:

```bash
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:

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

:::tip title="Houd sleutels uit je repository"
Commit nooit een service-account-sleutel of API-key. Zet ze in een secret manager of in omgevingsvariabelen, en voeg `*.json`-sleutels toe aan je `.gitignore`.
:::

## Basisgebruik

```python
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(...)`:

| Parameter | Type | Beschrijving |
|---|---|---|
| `number_of_images` | int | Aantal varianten, 1 tot 4 |
| `aspect_ratio` | str | "1:1", "3:4", "4:3", "9:16" of "16:9" |
| `image_size` | str | "1K" of "2K" (resolutie, modelafhankelijk) |
| `person_generation` | str | "dont_allow", "allow_adult" of "allow_all" |
| `negative_prompt` | str | Wat er niet in de afbeelding mag |
| `seed` | int | Vaste zaadwaarde voor reproduceerbare resultaten |
| `output_mime_type` | str | "image/png" of "image/jpeg" |

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](https://cloud.google.com/vertex-ai/generative-ai/docs/image/generate-images) bij twijfel.

## Negatieve prompts

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

```python
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:

```python
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:

```python
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")
```

:::info title="Edit-modi verschillen per model"
Welke `edit_mode`-waarden (zoals `EDIT_MODE_INPAINT_INSERTION` of `EDIT_MODE_OUTPAINT`) en welke referentietypes beschikbaar zijn, hangt af van het model en de versie. Raadpleeg de actuele documentatie voor de geldige combinaties.
:::

## Foutafhandeling

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

```python
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:

```python
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)
```

:::warn title="Bescherm een publieke generatie-endpoint"
Beeldgeneratie kost geld per afbeelding. Zet zo'n endpoint nooit onbeveiligd online: voeg authenticatie, een rate limit en een maximumlengte op de prompt toe, en valideer de invoer. Anders kan iemand jouw quota en factuur opstoken.
:::

## 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.

:::faq
### Welke Imagen-modelversie moet ik gebruiken?
In juni 2026 is `imagen-4.0-generate-001` de nieuwste generatie en doorgaans de beste keuze. Wil je stabiliteit boven nieuwste features, dan is `imagen-3.0-generate-002` een degelijk alternatief. Controleer welke modellen in jouw regio beschikbaar zijn voor je een naam hardcodeert.

### Moet ik de oude vertexai-vision_models-code herschrijven?
Ja. Die modules zijn uitgefaseerd en stoppen rond 24 juni 2026. Vervang `ImageGenerationModel.from_pretrained(...)` door een `genai.Client(vertexai=True, ...)` en `client.models.generate_images(...)`. De parameters zijn grotendeels vergelijkbaar, maar zitten nu in een `GenerateImagesConfig`-object.

### Hoe hoog zijn de kosten per afbeelding?
Vertex AI rekent per gegenereerde afbeelding, met een tarief dat afhangt van model en resolutie. Bekijk de actuele bedragen in de Google Cloud-prijslijst voor Vertex AI, want prijzen wijzigen los van deze handleiding.

### Kan ik dit draaien vanuit Cloud Run of Cloud Functions?
Ja. De Google Gen AI SDK werkt prima serverless. Geef het draaiende account de rol `roles/aiplatform.user`, dan hoef je geen apart sleutelbestand mee te leveren; de omgeving levert de credentials.

### Wat doe ik bij een rate limit of quota-fout?
Een quota-overschrijding komt terug als een `ClientError` met code 429. Bouw een retry met wachttijd (backoff) in, en vraag indien nodig een hoger quotum aan via de Google Cloud Console.

### Werkt dezelfde code ook tegen de Gemini API in plaats van Vertex AI?
Grotendeels wel. Maak de client dan zonder `vertexai=True` en geef een API-key mee in plaats van project en locatie. De Gemini-route heeft minder configuratieopties en lagere quota, en is bedoeld voor kleinere volumes of prototypes.
:::