Way Back Home - Level 0: Identify Yourself

---

Signal de détresse

Durée : 1 minute

Votre capsule de sauvetage traverse l'atmosphère d'un monde inconnu. Des voyants d'avertissement clignotent sur chaque panneau. Le système de navigation est hors service. Les communications sont interrompues. Alors que les protocoles d'urgence de la capsule se mettent en place, l'assistant IA se réveille :

"Survivant détecté. L'atterrissage d'urgence a réussi. Lancement du protocole de balise de détresse…"

"AVERTISSEMENT : La validation de l'identité est requise. Le réseau de sauvetage galactique ne peut pas localiser les explorateurs non enregistrés. Veuillez valider votre identité pour activer votre balise."

Vous regardez par le viewport. Un paysage extraterrestre s'étend à l'horizon : d'étranges formations rocheuses, une végétation inconnue, un ciel aux couleurs étranges. D'autres survivants de votre mission sont dispersés à la surface de cette planète.

Mais tout d'abord, vous devez exister dans le système.

Objectifs de l'atelier

Dans ce niveau, vous allez créer votre propre identité d'explorateur spatial à l'aide de la génération d'images en plusieurs étapes avec les modèles de génération d'images Gemini de Google (également appelés Nano Banana 🍌). Votre avatar apparaîtra sur la carte mondiale des opérations de sauvetage, visible par tous les autres survivants lors de votre atelier.

Ce que vous allez apprendre

Concept	Description
Génération d'images multitour	Maintenir la cohérence des personnages sur plusieurs générations d'images à l'aide de sessions de chat
Prompt engineering pour les images	Rédiger des requêtes efficaces pour obtenir des résultats stylisés et cohérents avec des contraintes spécifiques
API Gemini Image (Nano Banana)	Utiliser les fonctionnalités de génération d'images natives de Gemini via le SDK Python
Sessions de chat	Exploiter le contexte de la conversation pour affiner de manière itérative et assurer la cohérence des personnages

À la fin de ce niveau, vous aurez :

✅ Vous avez généré un portrait de votre explorateur à l'aide de l'IA de conversion de texte en image.
✅ Vous avez créé une icône de carte cohérente à l'aide d'une conversation multitours.
✅ Vous avez enregistré votre identité auprès du réseau de secours.
✅ Vous êtes apparu sur la carte du monde en direct aux côtés d'autres explorateurs.

Ajoutons-vous à la carte ! 📍

Préparer votre environnement

Durée : 2 min

Accéder à Cloud Shell

Nous allons commencer par ouvrir Cloud Shell, un terminal basé sur navigateur avec le SDK Google Cloud et d'autres outils essentiels préinstallés.

Vous avez besoin de crédits Google Cloud ?

• Si vous participez à un atelier avec formateur : votre formateur vous fournira un code promotionnel. Veuillez utiliser celui qu'ils vous fournissent.
• Si vous suivez cet atelier de programmation par vous-même : vous pouvez bénéficier d'un crédit Google Cloud sans frais pour couvrir les frais de l'atelier. Cliquez sur ce lien pour obtenir un avoir et suivez la procédure décrite dans le guide vidéo ci-dessous pour l'appliquer à votre compte.

Cliquez sur Activer Cloud Shell en haut de la console Google Cloud (icône de terminal dans la barre de navigation en haut à droite).

Trouvez votre ID de projet Google Cloud :

• Ouvrez la console Google Cloud : https://console.cloud.google.com.
• Sélectionnez le projet que vous souhaitez utiliser pour cet atelier dans le menu déroulant en haut de la page.
• L'ID de votre projet est affiché dans la fiche "Informations sur le projet" du tableau de bord
  

Une fois Cloud Shell ouvert, vérifiez que vous êtes authentifié :

# Check that you are logged in
gcloud auth list

Votre compte devrait être listé comme (ACTIVE).

Configurer votre projet

Vérifiez que votre projet est correctement défini :

export PROJECT_ID=$(gcloud config get-value project)
echo "Using project: $PROJECT_ID"

Si aucun projet n'est défini ou si vous devez le modifier :

gcloud config set project YOUR_PROJECT_ID

Activer les API requises

Activez l'API Vertex AI pour la génération d'images :

gcloud services enable aiplatform.googleapis.com

Cloner le dépôt

Clonez le dépôt Way Back Home et accédez au projet :

git clone https://github.com/ayoisio/way-back-home.git
cd way-back-home

Installer des dépendances

Accédez au niveau 0 et installez les packages Python requis :

cd level_0
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Voici les principales dépendances :

Package	Objectif
google-genai	Client de l'API Gemini pour la génération d'images
requests	Client HTTP pour les appels d'API à Mission Control
Pillow	Traitement des images et gestion des fichiers

Vérifier la configuration

Effectuez une validation rapide pour vous assurer que tout est correctement configuré :

cd ~/way-back-home
python scripts/verify_setup.py

Vous devriez obtenir le résultat suivant :

✓ Google Cloud project configured: your-project-id
✓ Vertex AI API enabled
✓ Dependencies installed
✓ Ready to proceed!

Dépannage Si la validation échoue :

• Projet non configuré : exécutez gcloud config set project YOUR_PROJECT_ID
• API non activée : exécutez gcloud services enable aiplatform.googleapis.com
• Dépendances manquantes : assurez-vous d'avoir activé le venv : source level_0/.venv/bin/activate

Ce que vous venez de faire

✅ Vous avez ouvert Cloud Shell
✅ Vous avez configuré votre projet Google Cloud
✅ Vous avez activé les API Vertex AI
✅ Vous avez cloné le dépôt de l'atelier de programmation
✅ Vous avez installé les dépendances Python
✅ Vous avez vérifié votre configuration

Étape suivante : Connectez-vous à Mission Control et revendiquez votre nom d'explorateur.

Se connecter à Mission Control

Durée : 2 min

Exécuter le script d'installation

Le script de configuration vous connecte au réseau de secours Way Back Home et réserve votre identité d'explorateur. Exécutez-le à partir de la racine du projet :

cd ~/way-back-home
chmod +x scripts/setup.sh
./scripts/setup.sh

Vous serez invité à fournir deux informations.

Saisissez votre code d'événement

Le code d'événement identifie l'événement de l'atelier auquel vous participez.

Si vous participez à un atelier : saisissez le code de l'événement à partir du code QR, de la diapositive ou de votre instructeur.

🚀 Welcome to Way Back Home!

Enter event code (from QR/slide): devfest-nyc-26
Validating event...
✓ Connected to: DevFest NYC 2026

Si vous apprenez seul : saisissez sandbox pour rejoindre l'environnement d'apprentissage public.

🚀 Welcome to Way Back Home!

Enter event code (from QR/slide): sandbox
Validating event...
✓ Connected to: Way Back Home Sandbox

L'environnement de bac à sable L'événement sandbox est un environnement public permanent pour les personnes qui apprennent par elles-mêmes. Vous partagerez la carte avec d'autres apprenants du monde entier. C'est un excellent moyen de voir que vous n'êtes pas seul dans cette aventure ! Le bac à sable est réinitialisé chaque semaine. Vous n'avez donc pas à vous soucier de l'encombrer.

Événement introuvable ? Vérifiez votre code d'événement. Elle est sensible à la casse et suit généralement un modèle tel que city-event-year. Si vous participez à un atelier, demandez à votre instructeur. Si vous apprenez seul, utilisez sandbox.

Fonctionnement de la validation des événements Lorsque vous saisissez votre code d'événement, le script de configuration appelle l'API Mission Control pour vérifier que l'événement existe : GET https://api.waybackhome.dev/events/devfest-nyc-26 L'API vérifie une base de données des événements d'atelier actifs. Si elle est valide, elle renvoie le nom et la configuration de l'événement. Vous vous assurez ainsi de vous connecter à une session d'atelier réelle et active.

Choisir votre nom d'explorateur

Choisissez un nom unique pour votre explorateur. Voici comment vous apparaîtrez sur la carte du monde et dans le classement.

Choose your explorer name: AstroAyo
✓ Username available!

Si le nom que vous avez choisi est déjà utilisé par un autre participant au même événement :

Choose your explorer name: SpaceExplorer
⚠️  That name is taken. Try another.
Choose your explorer name: SpaceExplorer42
✓ Username available!

Configuration terminée

Une fois l'opération terminée, un message de confirmation s'affiche :

Initializing your explorer profile...

✓ Environment configured!
  Explorer ID: a1b2c3d4
  Starting coordinates: (47, 23)

Next: cd level_0 && python customize.py

Que s'est-il passé ? Le script de configuration a effectué plusieurs appels d'API à Mission Control : 1. Vous avez validé votre code d'événement : vous avez confirmé que l'événement de l'atelier existe et est actif. 2. Vérification de la disponibilité du nom d'utilisateur : nous nous sommes assurés qu'aucune autre personne participant à votre événement n'avait déjà revendiqué ce nom. Vous avez réservé votre identité : vous avez créé un emplacement pour un participant avec un ID unique. 4. Coordonnées de départ attribuées : vous êtes placé à un endroit aléatoire à la surface de la planète. 5. Configuration enregistrée : tous les détails ont été écrits dans config.json à la racine du projet.

Accéder au niveau 0

Accédez maintenant au répertoire de niveau 0 (vos dépendances sont déjà installées depuis le module 2) :

cd level_0

Rappel concernant l'environnement virtuel Si vous avez ouvert un nouveau terminal ou si votre invite n'affiche pas (.venv), réactivez l'environnement virtuel : source .venv/bin/activate

Examiner votre configuration

Examinez ce qui a été enregistré (config.json se trouve à la racine du projet) :

cat ../config.json

{
    "event_code": "devfest-nyc-26",
    "event_name": "DevFest NYC 2026",
    "username": "AstroAyo",
    "participant_id": "a1b2c3d4",
    "starting_x": 47,
    "starting_y": 23,
    "api_base": "https://api.waybackhome.dev",
    "project_id": "your-project-id"
}

Ce fichier de configuration sera utilisé par les scripts suivants pour vous identifier auprès du réseau Rescue.

Ce que vous venez de faire

✓ Connecté à l'API Mission Control
✓ Nom d'explorateur unique réservé
✓ ID de participant et coordonnées de départ reçus
✓ Configuration enregistrée pour les étapes suivantes

Suivant : Personnalisez l'apparence de l'explorateur.

Personnaliser l'explorateur

Durée : 1 minute

Exécuter le script de personnalisation

Avant de générer votre avatar, vous devez faire quelques choix concernant l'apparence de votre explorateur :

python customize.py

Sélectionner la couleur de votre costume

Choisissez une couleur pour la combinaison spatiale de votre explorateur :

🎨 Let's create your explorer identity!

Select suit color:
  1. Deep Blue
  2. Crimson Red
  3. Forest Green
  4. Royal Purple
  5. Solar Gold
  6. Silver

Choice [1-6, default=6]: 1
✓ Deep Blue selected

Décrivez votre explorateur (facultatif)

Vous pouvez fournir une brève description de l'apparence de votre explorateur ou appuyer sur Entrée pour une attribution aléatoire :

Brief description of your explorer (or Enter for random):
Example: 'short dark hair, glasses, friendly smile'
> short dark hair, glasses, determined expression

✓ Preferences saved!

Si vous appuyez sur Entrée sans rien saisir, des traits aléatoires seront générés :

> 
✓ Random traits: confident expression, short styled hair

Conseils pour rédiger de bonnes descriptions Concentrez-vous sur les traits physiques visibles :

• Correct : "cheveux roux bouclés, taches de rousseur, sourire chaleureux"
• Bonne : "cheveux argentés en chignon, yeux perçants, visage ridé"
• À éviter : les longs historiques ou les traits non visuels

L'IA interprétera votre description lors de la génération du portrait. Il est donc préférable de fournir des détails visuels clairs.

Configuration mise à jour

Vos préférences sont désormais enregistrées :

✓ Preferences saved!
Next: Open generator.py and follow the codelab instructions
Then run: python create_identity.py

Vérifiez la configuration mise à jour :

cat ../config.json

Vos préférences s'affichent :

{
    "event_code": "devfest-nyc-26",
    "event_name": "DevFest NYC 2026",
    "username": "AstroAyo",
    "participant_id": "a1b2c3d4",
    "starting_x": 47,
    "starting_y": 23,
    "api_base": "https://api.waybackhome.dev",
    "project_id": "your-project-id",
    "suit_color": "deep blue with silver accents",
    "appearance": "short dark hair, glasses, determined expression"
}

Ce que vous venez de faire

✓ Vous avez sélectionné la couleur de votre combinaison
✓ Vous avez défini l'apparence de votre explorateur
✓ Configuration prête pour la génération d'images

Suivant : l'événement principal : écrire le code de génération d'images !

Créer le générateur d'avatars

Durée : 4 min

Il s'agit du module d'apprentissage principal. Vous allez écrire du code Python qui génère votre propre avatar d'explorateur à l'aide des fonctionnalités de génération d'images en plusieurs tours de Gemini (Nano Banana).

Ouvrir le fichier du générateur

Ouvrez le générateur d'avatars dans l'éditeur Cloud Shell :

cloudshell edit generator.py

Vous pouvez également cliquer sur Ouvrir l'éditeur dans Cloud Shell et accéder à generator.py dans le dossier level_0.

Comprendre la structure des fichiers

Le fichier contient un code de démarrage et trois sections d'espace réservé dans lesquelles vous ajouterez votre implémentation :

"""
Level 0: Avatar Generator

This module generates your unique space explorer avatar using
multi-turn image generation with Gemini (Nano Banana) for
character consistency across portrait and icon.
"""

from google import genai
from google.genai import types
from PIL import Image
import json
import os
import io

# Load configuration from setup (config.json is in project root)
CONFIG_PATH = "../config.json"

with open(CONFIG_PATH) as f:
    config = json.load(f)

USERNAME = config["username"]
SUIT_COLOR = config["suit_color"]
APPEARANCE = config["appearance"]

# Initialize the Gemini client for Vertex AI
client = genai.Client(
    vertexai=True,
    project=os.environ.get("GOOGLE_CLOUD_PROJECT", config.get("project_id")),
    location="us-central1"
)


def generate_explorer_avatar() -> dict:
    """
    Generate portrait and icon using multi-turn chat for consistency.
    
    The key technique here is using a CHAT SESSION rather than independent
    API calls. This allows Gemini to "remember" the character it created
    in the first turn, ensuring the icon matches the portrait.
    
    Returns:
        dict with portrait_path and icon_path
    """
    
    # MODULE_5_STEP_1_CREATE_CHAT_SESSION
    # TODO: Create a chat session for multi-turn generation
    chat = None  # Replace this line
    
    # MODULE_5_STEP_2_GENERATE_PORTRAIT
    # TODO: Generate the explorer portrait
    portrait_image = None  # Replace this section
    
    # MODULE_5_STEP_3_GENERATE_ICON
    # TODO: Generate a consistent map icon
    icon_image = None  # Replace this section
    
    return {
        "portrait_path": "outputs/portrait.png",
        "icon_path": "outputs/icon.png"
    }


if __name__ == "__main__":
    # Create outputs directory if it doesn't exist
    os.makedirs("outputs", exist_ok=True)
    
    print(f"Generating avatar for {USERNAME}...")
    result = generate_explorer_avatar()
    print(f"✅ Avatar created!")
    print(f"   Portrait: {result['portrait_path']}")
    print(f"   Icon: {result['icon_path']}")

Vous remplacerez les trois sections TODO par votre implémentation.

Concept clé : chat multitour pour la cohérence des personnages Pour générer des personnages cohérents dans plusieurs images, vous devez utiliser une session de chat. Lorsque vous générez une image dans une discussion, Gemini se souvient de ce qu'il a créé. Les messages suivants dans le même chat peuvent faire référence à "ce personnage" ou à "la même personne", et Gemini conservera la cohérence visuelle. Cette approche est fondamentalement différente de celle qui consiste à effectuer des appels d'API distincts et indépendants. Dans ce cas, les caractères générés seraient différents à chaque fois, car il n'y aurait pas de contexte partagé.

Independent calls:           Chat session:
┌─────────┐                  ┌─────────┐
│ Call 1  │ → Person A       │ Turn 1  │ → Person A
└─────────┘                  │         │
┌─────────┐                  │ Turn 2  │ → Person A (same!)
│ Call 2  │ → Person B       │         │
└─────────┘   (different!)   └─────────┘

Étape 1 : Créez la session de chat

Recherchez l'espace réservé MODULE_5_STEP_1_CREATE_CHAT_SESSION et remplacez la ligne chat = None # Replace this line par :

    # MODULE_5_STEP_1_CREATE_CHAT_SESSION
    # Create a chat session to maintain character consistency across generations.
    # The chat session preserves context between turns, so Gemini "remembers"
    # what it generated and can create consistent variations.
    chat = client.chats.create(
        model="gemini-2.5-flash-image",  # Nano Banana - Gemini with image generation
        config=types.GenerateContentConfig(
            response_modalities=["TEXT", "IMAGE"]
        )
    )

Comprendre le code

• client.chats.create() : crée une session de conversation qui conserve le contexte sur plusieurs tours.
• model="gemini-2.5-flash-image" : utilise le modèle Gemini 2.5 Flash avec la génération d'images native (Nano Banana)
• response_modalities=["TEXT", "IMAGE"] : indique à Gemini que nous souhaitons obtenir à la fois des explications textuelles et des images générées dans les réponses. Cette étape est obligatoire pour la génération d'images.

Étape 2 : Générer le portrait

Recherchez MODULE_5_STEP_2_GENERATE_PORTRAIT et remplacez portrait_image = None # Replace this section par le code suivant :

    # MODULE_5_STEP_2_GENERATE_PORTRAIT
    # First turn: Generate the explorer portrait.
    # This establishes the character that will be referenced in subsequent turns.
    portrait_prompt = f"""Create a stylized space explorer portrait.

Character appearance: {APPEARANCE}
Name on suit patch: "{USERNAME}"
Suit color: {SUIT_COLOR}

CRITICAL STYLE REQUIREMENTS:
- Digital illustration style, clean lines, vibrant saturated colors
- Futuristic but weathered space suit with visible mission patches
- Background: Pure solid white (#FFFFFF) - absolutely no gradients, patterns, or elements
- Frame: Head and shoulders only, 3/4 view facing slightly left
- Lighting: Soft diffused studio lighting, no harsh shadows
- Expression: Determined but approachable
- Art style: Modern animated movie character portrait (similar to Pixar or Dreamworks style)

The white background is essential - the avatar will be composited onto a map."""

    print("🎨 Generating your portrait...")
    portrait_response = chat.send_message(portrait_prompt)
    
    # Extract the image from the response.
    # Gemini returns a response with multiple "parts" - we need to find the image part.
    portrait_image = None
    for part in portrait_response.candidates[0].content.parts:
        if part.inline_data is not None:
            # Found the image! Convert from bytes to PIL Image and save.
            image_bytes = part.inline_data.data
            portrait_image = Image.open(io.BytesIO(image_bytes))
            portrait_image.save("outputs/portrait.png")
            break
    
    if portrait_image is None:
        raise Exception("Failed to generate portrait - no image in response")
    
    print("✓ Portrait generated!")

Conseils pour l'ingénierie des prompts Remarquez comment le prompt est soigneusement structuré : 1. Définition du sujet : "Crée un portrait stylisé d'un explorateur spatial" indique précisément à Gemini ce que nous voulons. 2. Injection de variables : nous insérons les choix de l'utilisateur ({APPEARANCE}, {USERNAME}, {SUIT_COLOR}) 3. Exigences de style : direction artistique spécifique ("illustration numérique", "style Pixar ou Dreamworks") 4. Contraintes techniques : arrière-plan blanc, cadrage et éclairage spécifiques La contrainte d'arrière-plan blanc pur est essentielle pour l'expérience Retour à la maison. Elle permet de composer proprement les avatars sur la carte, sans conflit de couleurs ni artefacts de frange.

Comprendre l'analyse des réponses La réponse de Gemini contient plusieurs "parties" :

• Parties de texte : commentaires ou explications du modèle
• Parties d'image : images générées sous forme de données binaires (inline_data)

Nous parcourons les différentes parties à la recherche de inline_data, qui contient les octets bruts de l'image. Nous convertissons ensuite ces octets en image PIL pour l'enregistrer.

Étape 3 : Générer l'icône de carte

Recherchez MODULE_5_STEP_3_GENERATE_ICON et remplacez icon_image = None # Replace this section par :

    # MODULE_5_STEP_3_GENERATE_ICON
    # Second turn: Generate a consistent icon for the map.
    # Because we're in the same chat session, Gemini remembers the character
    # from the portrait and will maintain visual consistency.
    icon_prompt = """Now create a circular map icon of this SAME character.

CRITICAL REQUIREMENTS:
- SAME person, SAME face, SAME expression, SAME suit — maintain perfect consistency with the portrait
- Tighter crop: just the head and very top of shoulders
- Background: Pure solid white (#FFFFFF)
- Optimized for small display sizes (will be used as a 64px map marker)
- Keep the exact same art style, colors, and lighting as the portrait
- Square 1:1 aspect ratio

This icon must be immediately recognizable as the same character from the portrait."""

    print("🖼️  Creating map icon...")
    icon_response = chat.send_message(icon_prompt)
    
    # Extract the icon image from the response
    icon_image = None
    for part in icon_response.candidates[0].content.parts:
        if part.inline_data is not None:
            image_bytes = part.inline_data.data
            icon_image = Image.open(io.BytesIO(image_bytes))
            icon_image.save("outputs/icon.png")
            break
    
    if icon_image is None:
        raise Exception("Failed to generate icon - no image in response")
    
    print("✓ Icon generated!")

Concept clé : cohérence grâce au contexte Remarquez que la requête d'icône indique "ce MÊME personnage" et insiste sur "MÊME personne, MÊME visage, MÊME expression, MÊME costume". Comme nous sommes dans la même session de chat, Gemini sait exactement à quel personnage nous faisons référence : celui qu'il vient de créer au tour précédent. Le modèle conserve ce contexte automatiquement. Si nous avions lancé une nouvelle session de chat ou effectué un appel d'API indépendant, Gemini aurait généré une personne à l'apparence complètement différente, car il n'aurait eu aucun souvenir de la génération précédente.

Votre code terminé

Une fois les trois sections ajoutées, votre fonction generate_explorer_avatar() devrait se présenter comme suit :

def generate_explorer_avatar() -> dict:
    """
    Generate portrait and icon using multi-turn chat for consistency.
    
    The key technique here is using a CHAT SESSION rather than independent
    API calls. This allows Gemini to "remember" the character it created
    in the first turn, ensuring the icon matches the portrait.
    
    Returns:
        dict with portrait_path and icon_path
    """
    
    # MODULE_5_STEP_1_CREATE_CHAT_SESSION
    # Create a chat session to maintain character consistency across generations.
    # The chat session preserves context between turns, so Gemini "remembers"
    # what it generated and can create consistent variations.
    chat = client.chats.create(
        model="gemini-2.5-flash-image",  # Nano Banana - Gemini with image generation
        config=types.GenerateContentConfig(
            response_modalities=["TEXT", "IMAGE"]
        )
    )
    
    # MODULE_5_STEP_2_GENERATE_PORTRAIT
    # First turn: Generate the explorer portrait.
    # This establishes the character that will be referenced in subsequent turns.
    portrait_prompt = f"""Create a stylized space explorer portrait.

Character appearance: {APPEARANCE}
Name on suit patch: "{USERNAME}"
Suit color: {SUIT_COLOR}

CRITICAL STYLE REQUIREMENTS:
- Digital illustration style, clean lines, vibrant saturated colors
- Futuristic but weathered space suit with visible mission patches
- Background: Pure solid white (#FFFFFF) - absolutely no gradients, patterns, or elements
- Frame: Head and shoulders only, 3/4 view facing slightly left
- Lighting: Soft diffused studio lighting, no harsh shadows
- Expression: Determined but approachable
- Art style: Modern animated movie character portrait (similar to Pixar or Dreamworks style)

The white background is essential - the avatar will be composited onto a map."""

    print("🎨 Generating your portrait...")
    portrait_response = chat.send_message(portrait_prompt)
    
    # Extract the image from the response.
    # Gemini returns a response with multiple "parts" - we need to find the image part.
    portrait_image = None
    for part in portrait_response.candidates[0].content.parts:
        if part.inline_data is not None:
            # Found the image! Convert from bytes to PIL Image and save.
            image_bytes = part.inline_data.data
            portrait_image = Image.open(io.BytesIO(image_bytes))
            portrait_image.save("outputs/portrait.png")
            break
    
    if portrait_image is None:
        raise Exception("Failed to generate portrait - no image in response")
    
    print("✓ Portrait generated!")
    
    # MODULE_5_STEP_3_GENERATE_ICON
    # Second turn: Generate a consistent icon for the map.
    # Because we're in the same chat session, Gemini remembers the character
    # from the portrait and will maintain visual consistency.
    icon_prompt = """Now create a circular map icon of this SAME character.

CRITICAL REQUIREMENTS:
- SAME person, SAME face, SAME expression, SAME suit — maintain perfect consistency with the portrait
- Tighter crop: just the head and very top of shoulders
- Background: Pure solid white (#FFFFFF)
- Optimized for small display sizes (will be used as a 64px map marker)
- Keep the exact same art style, colors, and lighting as the portrait
- Square 1:1 aspect ratio

This icon must be immediately recognizable as the same character from the portrait."""

    print("🖼️  Creating map icon...")
    icon_response = chat.send_message(icon_prompt)
    
    # Extract the icon image from the response
    icon_image = None
    for part in icon_response.candidates[0].content.parts:
        if part.inline_data is not None:
            image_bytes = part.inline_data.data
            icon_image = Image.open(io.BytesIO(image_bytes))
            icon_image.save("outputs/icon.png")
            break
    
    if icon_image is None:
        raise Exception("Failed to generate icon - no image in response")
    
    print("✓ Icon generated!")
    
    return {
        "portrait_path": "outputs/portrait.png",
        "icon_path": "outputs/icon.png"
    }

Enregistrer votre fichier

Veillez à enregistrer generator.py :

• Éditeur Cloud Shell : Ctrl+S (Windows/Linux) ou Cmd+S (Mac)
• vim : appuyez sur Échap, puis saisissez :wq et appuyez sur Entrée.

Ce que vous venez de créer

✓ Création d'une session de chat pour la génération d'images en plusieurs étapes
✓ Élaboration d'une requête détaillée pour la génération de portraits avec des contraintes de style
✓ Génération d'une icône de carte cohérente à l'aide du contexte de la conversation
✓ Apprentissage de l'analyse des données d'image à partir des réponses de Gemini

Concepts clés maîtrisés :

Concept	Ce que vous avez appris
Sessions de chat	client.chats.create() conserve le contexte sur plusieurs tours.
Modalités de réponse	["TEXT", "IMAGE"] permet de générer des images dans les réponses.
Structure des requêtes	Sujet → Variables → Style → Contraintes techniques
Cohérence des personnages	Même session de chat = même personnage dans les images
Analyse de la réponse	Extraire des images de inline_data dans les parties de réponse

Suivant : Exécutez votre code et voyez-vous sur la carte !

Générer et enregistrer

Durée : 2 min

Définir l'ID de votre projet

Assurez-vous que l'ID de votre projet est disponible en tant que variable d'environnement :

export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)

Exécuter Identity Creator

Exécutez maintenant le script principal qui orchestre la génération, l'importation et l'enregistrement :

python create_identity.py

La progression de la génération s'affiche en temps réel :

🚀 Creating identity for AstroAyo...

🎨 Generating your portrait...
✓ Portrait generated!
🖼️  Creating map icon...
✓ Icon generated!

☁️  Uploading to mission database...
✓ Avatar uploaded!

📍 Registering with rescue network...
✓ Registration complete!

╔═══════════════════════════════════════════════════════════════╗
║                    ✅ IDENTITY CONFIRMED!                      ║
╠═══════════════════════════════════════════════════════════════╣
║                                                               ║
║  Explorer: AstroAyo                                           ║
║  Location: (47, 23) — unconfirmed                             ║
║                                                               ║
║  🗺️  You're now on the map!                                   ║
║  https://waybackhome.dev/e/devfest-nyc-26                     ║
║                                                               ║
║  NEXT: Proceed to Level 1 to pinpoint your exact location!   ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Que s'est-il passé ? Le script create_identity.py (fourni) a effectué plusieurs étapes : 1. Votre code a été appelé : generate_explorer_avatar() a été exécuté à partir de generator.py 2. Images importées : vous avez envoyé votre portrait et votre icône à l'API Mission Control. Identité enregistrée : mise à jour de l'enregistrement du participant avec les URL des avatars 4. Confirmation : votre avatar est désormais visible sur la carte du monde. Vous avez écrit la logique de génération d'images. Le script a géré la mise en réseau et l'enregistrement à votre place.

Afficher votre avatar généré

Consultez vos images générées en local :

# List the generated files
ls -la outputs/

# Download to view on your local machine
cloudshell download outputs/portrait.png
cloudshell download outputs/icon.png

Vous pouvez également les afficher directement dans l'éditeur Cloud Shell en accédant au dossier outputs/ et en cliquant sur les fichiers image.

Le portrait et l'icône générés ressembleront à ces images :

Visualisez votre position sur la carte !

Ouvrez l'URL de la carte du monde affichée dans le résultat :

https://waybackhome.dev/e/{your-event-code}

Par exemple : https://waybackhome.dev/e/devfest-nyc-26

Trouvez votre avatar sur la carte ! Cette page vous indique les informations suivantes :

• Votre icône indiquant votre position à la surface de la planète
• Votre nom d'explorateur sous forme de libellé sous votre icône
• Une balise atténuée qui clignote lentement autour de votre repère

Cliquez sur votre repère pour afficher votre portrait complet dans la fiche d'informations.

Pourquoi le voyant est-il faible ? Votre position est actuellement "non confirmée". Vous vous trouvez quelque part dans la région des coordonnées (47, 23), mais le réseau de secours ne connaît pas encore votre position exact. Vous vous souvenez, vous avez fait un atterrissage forcé ? Dans Niveau 1 : Déterminez votre position exacte, vous analyserez votre environnement à l'aide d'un système multi-agent pour confirmer vos coordonnées précises. Une fois confirmé, votre balise s'allumera pour que les équipes de secours puissent vous trouver.

Votre avatar ne vous plaît pas ? Regénérer !

Si vous souhaitez un autre avatar, vous pouvez le regénérer :

# Option 1: Change your appearance settings first
python customize.py

# Option 2: Just regenerate with current settings
python create_identity.py

Chaque fois que vous exécutez create_identity.py, un avatar entièrement nouveau est généré (nouvelle session de chat = nouveau personnage) et votre inscription est mise à jour. N'hésitez pas à recommencer jusqu'à ce que le résultat vous convienne.

Pourquoi chaque exécution crée-t-elle un personnage différent ? Lorsque vous exécutez create_identity.py à nouveau, une nouvelle session de chat est créée. Comme il n'y a pas de contexte précédent, Gemini génère un nouveau personnage. C'est en fait souhaitable ici, car cela vous permet de générer à nouveau si le premier résultat ne vous plaît pas. La technique de cohérence (chat multitours) garantit que le portrait et l'icône correspondent au sein d'une même exécution, mais chaque exécution produit un personnage unique.

Dépannage

Problèmes courants "Échec de la génération du portrait : aucune image dans la réponse"

• Le modèle a peut-être refusé de générer l'image en raison des règles relatives au contenu. Réessayez.
• Vérifiez que la description de votre apparence ne contient pas de contenu soumis à restriction.
• Assurez-vous d'utiliser un modèle compatible avec la génération d'images (gemini-2.5-flash-image).

"ModuleNotFoundError: No module named 'google.genai'"

• Assurez-vous d'avoir activé l'environnement virtuel : source .venv/bin/activate
• Relancer : pip install -r requirements.txt

Erreurs d'authentification ou "Autorisation refusée"

• Assurez-vous que votre projet est défini : export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
• Vérifiez que l'API Vertex AI est activée : gcloud services enable aiplatform.googleapis.com

Erreur d'importation ou erreurs d'API

• Vérifiez votre connexion Internet dans Cloud Shell.
• Vérifiez que l'événement est toujours actif (les événements expirent à la fin de l'atelier).
• Demandez à votre instructeur d'atelier si l'API Mission Control est opérationnelle.

L'avatar n'apparaît pas sur la carte

• Patientez cinq à dix secondes. La carte recherche régulièrement les mises à jour.
• Forcez l'actualisation de la page (Ctrl+Maj+R ou Cmd+Maj+R).
• Vérifiez que l'enregistrement s'est terminé sans erreur dans la sortie du terminal.

Ce que vous venez de faire

✓ Vous avez généré votre portrait d'explorateur unique.
✓ Vous avez créé une icône de carte cohérente.
✓ Vous avez importé des éléments dans Mission Control.
✓ Vous avez enregistré votre identité auprès du réseau de sauvetage.
✓ Vous êtes apparu sur la carte du monde en direct.

Félicitations, explorateur ! Vous faites désormais partie du réseau de dépannage. Votre balise est active (mais faiblement lumineuse) et les autres survivants peuvent vous voir sur la carte.

Conclusion

Durée : 1 minute

Ce que vous avez créé

En seulement 10 minutes, vous avez créé un système complet de génération d'avatars à l'aide de la génération d'images par IA multitours :

┌─────────────────────────────────────────────────────────────┐
│                     Your Creation                            │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   📝 Input                       🖼️  Output                  │
│   ──────────                     ────────                    │
│   • Explorer name                • Stylized portrait         │
│   • Suit color                   • Consistent map icon       │
│   • Appearance description       • Live map presence         │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   🧠 Techniques You Used                                     │
│   ──────────────────────                                     │
│   • Multi-turn chat sessions for character consistency      │
│   • Structured prompt engineering with style constraints    │
│   • Response parsing to extract generated images            │
│   • API integration for cloud registration                  │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Points clés à retenir

Leçon	Pourquoi est-ce important ?
Les sessions de chat conservent le contexte	Essentiel pour générer des personnages cohérents dans plusieurs images sans dérive de variation
La structure des requêtes est importante	Des contraintes claires (fond blanc, style spécifique, cadrage) produisent des résultats prévisibles et prêts pour la production.
Les conversations multitours sont plus efficaces que les appels indépendants	Chaque message d'une discussion s'appuie sur le contexte précédent, ce qui permet un affinement itératif et une cohérence.
Les modalités de réponse contrôlent la sortie	Le paramètre ["TEXT", "IMAGE"] est obligatoire pour générer des images. Sans lui, vous n'obtiendrez que du texte.

Récapitulatif des coûts

Pour ce niveau, vous avez généré deux images à l'aide de Gemini 2.5 Flash (Nano Banana) :

Élément	Jetons	Coût
Portrait (1 024 x 1 024)	~1 290 jetons de sortie	~0,039 $
Icône (1 024 x 1 024)	~1 290 jetons de sortie	~0,039 $
Total	~2 580 jetons	~ 0,08$

Alternative : Nano Banana Pro Pour obtenir des résultats de meilleure qualité, vous pouvez utiliser gemini-3-pro-image-preview (Nano Banana Pro). Cela permet de générer des images plus détaillées et plus fidèles, mais coûte environ 0,27$ pour un portrait et une icône (en résolution 1K). Pour les ateliers avec de nombreux participants, Nano Banana (Gemini 2.5 Flash) offre un excellent rapport qualité/prix.

Le voyage continue

Votre identité d'explorateur a été confirmée, mais un problème est survenu : votre position n'a pas été confirmée.

Regardez la carte du monde : votre balise est faible et clignote lentement. Le réseau de secours sait que vous existez, mais pas exactement où vous vous trouvez. Vous pouvez vous trouver n'importe où dans une vaste région de la surface de la planète.

Dans Niveau 1 : Déterminez votre position, vous allez :

• Créer un système multi-agents à l'aide d'Agent Development Kit (ADK) de Google
• Créer des serveurs MCP pour les analyses géologiques, botaniques et astronomiques
• Traiter les entrées multimodales (images de votre site de l'accident)
• Générez une carte topographique de votre position confirmée à l'aide de l'IA.
• Allumez votre balise pour de vrai afin que les équipes de secours puissent vous trouver.

Le niveau 1 présente des concepts beaucoup plus avancés : l'orchestration multi-agents, le protocole MCP (Model Context Protocol) et les modèles de déploiement en production. Vous passerez de l'utilisation d'une seule fonctionnalité de modèle à la création d'un système agentique complet.

Nettoyer (facultatif)

Si vous souhaitez nettoyer les fichiers locaux (exécutés à partir du répertoire level_0) :

rm -rf outputs/
rm ../config.json
deactivate  # Exit virtual environment

Votre inscription au réseau de sauvetage est conservée. Vous apparaissez toujours sur la carte, même après avoir supprimé les fichiers locaux. Les images sont stockées dans le cloud, et non localement.

Ressources

• Documentation sur la génération d'images Gemini
• Guide du prompt engineering pour les images
• Blog d'annonce de Nano Banana
• Dépôt Way Back Home
• Niveau 1 : Localisez-vous

---

Votre balise est en attente de confirmation. À bientôt au niveau 1, explorateur. 🚀

Bonus : Avatar basé sur une photo (facultatif)

Durée : 3 min

Section facultative Ce module bonus vous montre comment utiliser une photo réelle comme base pour votre avatar, en la transformant en un explorateur spatial stylisé grâce aux fonctionnalités image-à-image de Gemini. Ignorez cette étape si vous êtes satisfait de votre avatar généré à partir de texte.

Quand utiliser la fonctionnalité Photo-to-Avatar ?

Vous pouvez préférer cette approche si :

• Vous souhaitez que votre avatar vous ressemble vraiment.
• Vous avez une photo spécifique que vous souhaitez styliser.
• Vous souhaitez explorer les capacités de transformation d'image à image de Gemini.

Fonctionnement

Au lieu de générer un personnage à partir d'une description textuelle, vous fournissez une photo et demandez à Gemini de la transformer tout en préservant l'apparence de la personne :

Importer votre photo

Tout d'abord, importez une photo dans Cloud Shell :

1. Dans Cloud Shell, cliquez sur le menu à trois points (⋮) dans la barre d'outils du terminal.
2. Sélectionnez Importer.
3. Choisissez un portrait photo net (au format JPEG ou PNG).
4. Notez le chemin d'accès importé (par exemple, /home/your-username/my_photo.jpg)

Modifier le générateur

Pour utiliser une photo, vous devez modifier l'étape de génération de portrait dans generator.py. Remplacez la requête textuelle par une requête multimodale incluant votre photo :

    # MODULE_5_STEP_2_GENERATE_PORTRAIT (Photo-based version)
    
    # Load your photo
    photo_path = "/home/your-username/my_photo.jpg"  # Update this path!
    user_photo = Image.open(photo_path)
    
    # Convert photo to bytes for the API
    photo_buffer = io.BytesIO()
    user_photo.save(photo_buffer, format="JPEG")
    photo_bytes = photo_buffer.getvalue()
    
    portrait_prompt = f"""Transform this person into a stylized space explorer portrait.

PRESERVE from the original photo:
- The person's facial features, face shape, and likeness
- Their general expression and personality
- Any distinctive features (glasses, facial hair, etc.)

TRANSFORM with this style:
- Digital illustration style, clean lines, vibrant saturated colors
- Add a futuristic space suit with the name "{USERNAME}" on a shoulder patch
- Suit color: {SUIT_COLOR}
- Background: Pure solid white (#FFFFFF) - no gradients or elements
- Frame: Head and shoulders, 3/4 view
- Lighting: Soft diffused studio lighting
- Art style: Modern animated movie character (Pixar/Dreamworks aesthetic)

The result should be clearly recognizable as THIS specific person, but illustrated as a heroic space explorer."""

    print("🎨 Transforming your photo into an explorer portrait...")
    
    # Send both the prompt AND the image
    portrait_response = chat.send_message([
        portrait_prompt,
        types.Part.from_bytes(data=photo_bytes, mime_type="image/jpeg")
    ])
    
    # Rest of the extraction code stays the same...

La cohérence multitours fonctionne toujours

L'approche multitour fonctionne de la même manière avec la génération basée sur des photos :

• Tour 1 : photo + requête → portrait stylisé (votre image, illustrée)
• Tour 2 : "Crée une icône de ce MÊME personnage" → Icône cohérente

Étant donné que la session de chat se souvient de la version stylisée qu'elle a créée (et non de la photo d'origine), l'icône correspondra parfaitement au portrait transformé.

Considérations liées à la confidentialité

Remarque sur la confidentialité Lorsque vous importez une photo :

• La photo est envoyée à Vertex AI (Google Cloud) pour traitement.
• Le résultat stylisé (et non votre photo d'origine) est stocké sur le réseau de récupération.
• N'utilisez que des photos que vous acceptez de faire traiter par des services d'IA.
• La génération basée sur du texte (sans photo) est toujours disponible comme alternative respectueuse de la confidentialité.

Essayer dans Vertex AI Studio

Vous pouvez également tester la transformation de photos de manière interactive dans la console Google Cloud avant d'écrire du code :

1. Accédez à Vertex AI Studio.
2. Sélectionner un modèle Gemini avec des fonctionnalités d'image
3. Importez votre photo à l'aide du bouton de pièce jointe.
4. Saisissez le prompt de transformation
5. Affinez le style jusqu'à obtenir le résultat souhaité.
6. Téléchargez le résultat et enregistrez-le au format outputs/portrait.png.
7. Exécutez python create_identity.py --skip-generation (si cet indicateur est compatible) pour importer les images générées manuellement.

Cette approche interactive est idéale pour tester des requêtes et voir les résultats en temps réel avant de s'engager dans le code.

Ce que vous avez appris (bonus)

✓ Utiliser la transformation d'image à image avec Gemini
✓ Envoyer du contenu multimodal (texte + image) dans un seul message
✓ Préserver la ressemblance tout en appliquant le transfert de style artistique
✓ Considérations relatives à la confidentialité pour la génération d'IA basée sur des photos