Tutorial FLUX.2 Klein: Membangun Aplikasi Generate-and-Edit Gambar dengan Gradio

Langkah 1: Menyiapkan lingkungan

Sebelum membangun aplikasi generasi dan pengeditan gambar, kita perlu menyiapkan lingkungan bersih dengan pustaka Diffusers terbaru. Untuk tutorial ini, kita akan menjalankan semuanya pada instance Google Colab dengan GPU A100 untuk generasi gambar yang lebih cepat. Meski begitu, setelan yang sama juga berfungsi pada GPU yang lebih sederhana, seperti T4, dengan performa sedikit lebih lambat.

Kita mulai dengan mencopot pemasangan versi Diffusers yang sudah ada untuk menghindari konflik versi, lalu memasang versi pengembangan terbaru langsung dari GitHub. Kita juga memasang pustaka pendukung yang diperlukan untuk memuat model, menangani checkpoint, dan akselerasi.

!pip -q uninstall -y diffusers
!pip -q install -U git+https://github.com/huggingface/diffusers.git
!pip -q install -U accelerate safetensors transformers huggingface_hub

Setelah pemasangan selesai, kita memeriksa versi Diffusers yang terpasang, lalu memastikan kelas Flux2KleinPipeline dapat diimpor dengan sukses.

import diffusers
print("diffusers:", diffusers.__version__)
from diffusers import Flux2KleinPipeline
print("Flux2KleinPipeline import OK")

Ini menegaskan bahwa lingkungan kita telah dikonfigurasi dengan benar. Pada langkah berikutnya, kita akan memuat model FLUX.2 Klein ke GPU dan menyiapkannya untuk generasi gambar lokal dan alur kerja pengeditan berbasis API.

Langkah 2: Memuat FLUX.2 Klein 4B 

Sebelum memuat model, Anda memerlukan kunci API dari Black Forest Labs. Untuk memulai, masuk ke akun Black Forest Labs Anda dan tambahkan kredit di tab Credits. Isi ulang minimum sekitar sepuluh dolar, yang memberikan kurang lebih seribu kredit. Setelah kredit ditambahkan, klik Create Key, beri nama yang deskriptif, dan simpan dengan aman.

Dengan kunci API siap, langkah selanjutnya adalah memuat model FLUX.2 Klein 4B dan menyiapkannya untuk dua mode penggunaan berbeda: generasi gambar lokal dan pengeditan gambar berbasis API. 

import os, time, base64, io, requests
import gradio as gr
import torch
import nest_asyncio
from PIL import Image
from diffusers import Flux2KleinPipeline
from google.colab import userdata
nest_asyncio.apply()
# =============================
# LOAD via API
# =============================
MODEL_ID = "black-forest-labs/FLUX.2-klein-4B"
BFL_API_KEY = userdata.get("BFL_API_KEY")
BFL_CREATE_URL = "https://api.bfl.ai/v1/flux-2-klein-4b"
print(f"Loading model to GPU: {torch.cuda.get_device_name(0)}")
# =============================
# LOAD via LOCAL HF PIPELINE
# =============================
dtype = torch.float16 
pipe = Flux2KleinPipeline.from_pretrained(MODEL_ID, torch_dtype=dtype).to("cuda")

Kita mulai dengan menyiapkan kunci API sebagai rahasia Colab, sehingga tidak pernah muncul di kode notebook. Kita juga mendefinisikan ID model dan endpoint pengeditan Klein yang akan kita panggil nanti. 

Selanjutnya, kita menerapkan nest_asyncio sebelum meluncurkan UI Gradio untuk menghindari konflik event loop.

Terakhir, muat pipeline FLUX.2 Klein lokal untuk generasi gambar dasar. Kita menggunakan Flux2KleinPipeline dengan float16 untuk kompatibilitas GPU yang luas (A100 dan T4 sama-sama berfungsi baik), lalu memindahkan pipeline ke CUDA untuk inferensi cepat. Pipeline lokal ini hanya digunakan untuk menghasilkan gambar awal, sementara edit ditangani melalui API.

Catatan: Pada titik ini, Anda mungkin bertanya-tanya mengapa kita memuat model secara lokal sekaligus mengonfigurasi akses API. Alasannya adalah pemisahan kapabilitas:

• Pipeline Hugging Face lokal ideal untuk generasi teks-ke-gambar iteratif dan kontrol penuh atas setelan inferensi.
• API Black Forest Labs mengekspos fitur pengeditan gambar tingkat lanjut untuk FLUX.2 Klein yang saat ini belum tersedia dalam implementasi bobot terbuka, seperti edit gambar berbasis prompt dengan beberapa gambar referensi.

Dengan menggabungkan kedua pendekatan, kita mendapatkan yang terbaik dari keduanya: kecepatan generasi lokal dan dukungan pengeditan.

Langkah 3: Fungsi pembantu

Sebelum menyambungkan semuanya ke antarmuka Gradio, kita memerlukan serangkaian kecil fungsi pembantu. Karena aplikasi kita menghasilkan gambar secara lokal tetapi mengeditnya melalui API, kita memerlukan cara untuk mengenkode gambar ke base64 untuk permintaan API, cara mengunduh gambar hasil edit yang dikembalikan sebagai URL, dan fungsi generasi lokal yang menghasilkan gambar dasar awal.

def pil_to_b64_png(img: Image.Image) -> str:
    buf = io.BytesIO()
    img.convert("RGB").save(buf, format="PNG")
    return base64.b64encode(buf.getvalue()).decode()
def url_to_pil(url: str) -> Image.Image:
    r = requests.get(url, timeout=60)
    r.raise_for_status()
    return Image.open(io.BytesIO(r.content)).convert("RGB")
def local_generate(prompt: str):
    if not prompt.strip():
        raise gr.Error("Prompt is empty.")
    out = pipe(
        prompt=prompt.strip(),
        width=1024,
        height=1024,
        num_inference_steps=4,
        guidance_scale=1.0,
        output_type="pil",
    )
    return out.images[0].convert("RGB")

Kode di atas mendefinisikan tiga fungsi pembantu utama:

• Fungsi pil_to_b64_png() mengonversi gambar PIL menjadi string PNG terenkode base64. Ini diperlukan karena API pengeditan FLUX.2 menerima gambar dasar dan gambar referensi sebagai URL atau string base64. 
• Fungsi url_to_pil() menangani arah sebaliknya. API pengeditan mengembalikan URL bertanda tangan untuk keluaran yang dihasilkan, jadi kita mengambil URL tersebut dengan requests, memvalidasi respons, dan mengonversi byte yang diunduh kembali menjadi gambar PIL. Ini memungkinkan hasil edit ditampilkan langsung di antarmuka Gradio dan disimpan dalam riwayat.
• Terakhir, fungsi local_generate() adalah pintu masuk teks-ke-gambar lokal kita. Ia memvalidasi bahwa prompt tidak kosong, lalu memanggil Flux2KleinPipeline lokal dengan setelan tetap seperti resolusi, jumlah langkah, dan skala panduan. Keluaran dikembalikan sebagai gambar PIL RGB yang bersih, yang menjadi gambar dasar untuk edit berikutnya.

Silakan bereksperimen dengan setelan pipeline Flux 2, seperti resolusi gambar, langkah difusi, dan skala panduan, untuk mengeksplorasi trade-off kualitas-kecepatan dan memahami bagaimana setiap parameter memengaruhi gambar akhir. 

Dokumentasi pengeditan gambar Flux 2 adalah tempat yang baik untuk memahami lebih lanjut tentang setelan ini.

Pada langkah berikutnya, kita akan menggunakan utilitas ini untuk menerapkan pengeditan gambar berbasis API dengan FLUX.2 Klein.

Langkah 4: Mengedit melalui BFL API

Langkah ini adalah perbedaan inti antara alur kerja Hugging Face murni dan pendekatan hibrida yang digunakan dalam tutorial ini. Alih-alih mencoba menjalankan pengeditan gambar secara lokal, kita mendelegasikan edit ke API, yang menangani edit berbasis prompt dan conditioning multi-referensi opsional secara andal.

Secara garis besar, API pengeditan FLUX.2 Klein mengharapkan prompt teks yang mendeskripsikan edit, gambar dasar untuk dimodifikasi, dan gambar referensi opsional yang diberikan sebagai masukan tambahan. API berjalan secara asinkron, artinya kita mengirim permintaan lalu mem-poll URL yang dikembalikan hingga gambar hasil edit siap.

POLL_INTERVAL_S = 1.0
POLL_TIMEOUT_S = 120
def bfl_edit(edit_prompt, base_img, ref_imgs=None):
    if not BFL_API_KEY:
        raise gr.Error("Missing BFL_API_KEY in Colab Secrets.") 
    payload = {
        "prompt": edit_prompt.strip(),
        "input_image": pil_to_b64_png(base_img),
        "output_format": "png",
    }
    if ref_imgs:
        for i, ref in enumerate(ref_imgs[:3], start=2):
            payload[f"input_image_{i}"] = pil_to_b64_png(ref)
    create = requests.post(
        BFL_CREATE_URL,
        headers={"x-key": BFL_API_KEY, "accept": "application/json"},
        json=payload,
        timeout=60,
    )
    create.raise_for_status()
    job = create.json()
    polling_url = job.get("polling_url")
    if not polling_url:
        raise gr.Error(f"API Error: {job}")
    t0 = time.time()
    while True:
        if time.time() - t0 > POLL_TIMEOUT_S:
            raise gr.Error("BFL API polling timed out.")  
        time.sleep(POLL_INTERVAL_S)
        res = requests.get(polling_url, headers={"x-key": BFL_API_KEY})
        res.raise_for_status()
        j = res.json()
        if j["status"] == "Ready":
            return url_to_pil(j["result"]["sample"])
        if j["status"] in ("Error", "Failed"):
            raise gr.Error(f"Generation Failed: {j}")

Fungsi bfl_edit() melakukan tiga hal penting:

• Menerima tiga masukan, termasuk prompt edit, gambar dasar yang ingin dimodifikasi, dan daftar gambar referensi opsional. 
• Kita membangun payload JSON dengan prompt edit dan gambar dasar yang dikodekan sebagai PNG base64. Jika gambar referensi disediakan, kita lampirkan menggunakan format berindeks API. Ini memungkinkan kita menyediakan hingga tiga gambar referensi bersama gambar dasar, yang cukup untuk banyak alur kerja praktis seperti transfer palet warna, penjangkaran gaya, atau grounding objek.
• Berikutnya, kita mengirim permintaan ke endpoint API dan mengurai responsnya. API mengembalikan polling_url yang harus kita kueri berulang hingga pekerjaan selesai. Kita menerapkannya menggunakan loop polling sederhana dengan dua pagar pengaman: interval polling untuk menghindari permintaan berlebihan, dan batas waktu agar notebook tidak menunggu tanpa batas.

Setelah status menjadi Ready, respons API berisi URL bertanda tangan ke gambar keluaran. Kita mengunduh gambar tersebut menggunakan fungsi pembantu url_to_pil() sebelumnya dan mengembalikannya sebagai gambar PIL.

Pada langkah berikutnya, kita akan menerapkan riwayat sesi sehingga pengguna dapat meninjau ulang keluaran apa pun yang dihasilkan atau diedit.

Langkah 5: Menambahkan riwayat 

Pada titik ini, bagian terakhir yang kita butuhkan sebelum membangun UI adalah lapisan memori sesi ringan agar pengguna dapat meninjau keluaran sebelumnya. Kita menerapkan riwayat menggunakan dua objek state Gradio:

• base_img_state menyimpan gambar kerja saat ini (gambar yang akan diterapkan edit di masa depan).
• history_state menyimpan setiap versi yang dihasilkan atau diedit sebagai daftar kamus, masing-masing berisi gambar dan label singkat.

def update_history(history):
    choices = [f"{i}: {h['label']}" for i, h in enumerate(history or [])]
    return gr.update(choices=choices, value=choices[-1] if choices else None)
def on_generate(prompt, history):
    img = local_generate(prompt)
    new_history = list(history or [])
    new_history.append({"img": img, "label": "Generated Base"})
    return img, img, new_history, update_history(new_history), "Base image generated."
def on_edit(edit_prompt, ref2, ref3, ref4, base_img, history):
    if base_img is None:
        raise gr.Error("Please generate a base image first.")
    refs = [r.convert("RGB") for r in (ref2, ref3, ref4) if r is not None]
    out = bfl_edit(edit_prompt, base_img, refs)
    new_history = list(history or [])
    new_history.append({"img": out, "label": f"Edit: {edit_prompt[:20]}..."})
    return out, out, new_history, update_history(new_history), "Edit successful."
def on_load(choice, history):
    if not history or not choice:
        return None, None, "No history to load."
    idx = int(choice.split(":")[0])
    img = history[idx]["img"]
    return img, img, f"Loaded entry #{idx}."
def on_clear():
    return None, None, [], gr.update(choices=[], value=None), "Cleared everything."

Fungsi-fungsi di atas membentuk logika inti untuk mempertahankan riwayat gambar dalam demo kita:

• Fungsi update_history() memformat riwayat sesi menjadi dropdown. Setiap entri diberi label dengan indeks dan deskripsi singkat, dan dropdown otomatis memilih item terbaru secara default. Ini menjaga UI tetap sinkron tanpa memerlukan logika penyegaran manual.
• Callback on_generate() menjalankan local_generate() untuk membuat gambar dasar awal. Lalu menambahkan hasil ke riwayat sebagai {"img": img, "label": "Generated Base"}. Fungsi mengembalikan gambar dan state riwayat yang diperbarui, bersama pembaruan dropdown agar entri baru langsung terlihat.
• Callback on_edit() serupa, tetapi memanggil bfl_edit(). Ia mengambil gambar kerja saat ini dan beberapa gambar referensi opsional, menerapkan edit melalui API, dan menambahkan keluaran ke riwayat. Ia juga mengembalikan keluaran edit sebagai base_img_state baru, artinya edit berikutnya diterapkan pada gambar paling baru kecuali pengguna secara eksplisit memuat versi yang lebih lama.
• Callback on_load() mengurai entri dropdown yang dipilih, mengambil gambar terkait dari history_state, dan menjadikan gambar tersebut sebagai gambar kerja aktif lagi. Ini memungkinkan pengguna untuk memecah cabang edit dari titik pemeriksaan sebelumnya.
• Terakhir, fungsi on_clear() mereset semuanya. Ia menghapus keluaran, mengosongkan state gambar dasar, mereset daftar riwayat, dan mengosongkan pilihan dropdown.

Mari sambungkan fungsi-fungsi ini ke antarmuka Gradio dengan dua kotak teks, unggahan referensi opsional, dan alur kerja riwayat.

Langkah 6: UI Gradio

Langkah ini menghubungkan logika generasi, pengeditan, dan riwayat kita ke antarmuka Gradio sederhana. Antarmuka dibangun dengan gr.Blocks, yang memberi kita kontrol tata letak yang lebih rinci. 

with gr.Blocks() as demo:
    gr.Markdown("## FLUX.2 Klein: Generate & Edit Images")
    with gr.Row():
        with gr.Column(scale=1):
            gen_prompt = gr.Textbox(label="1. Generate Base Image", placeholder="A young boy riding a scooter...")
            gen_btn = gr.Button("Generate Base Image", variant="primary")
            edit_prompt = gr.Textbox(label="2. Describe Edits", placeholder="Add the red hat and yellow glasses from the references...")
            with gr.Accordion("Reference Images (Optional)", open=False):
                r2 = gr.Image(label="Ref 1", type="pil")
                r3 = gr.Image(label="Ref 2", type="pil")
                r4 = gr.Image(label="Ref 3", type="pil")
            edit_btn = gr.Button("Apply Edit", variant="secondary") 
            history_dd = gr.Dropdown(label="Session History", choices=[])
            with gr.Row():
                load_btn = gr.Button("Load Selected")
                clear_btn = gr.Button("Clear All")
            status = gr.Textbox(label="Status", interactive=False)
        with gr.Column(scale=1):
            output_view = gr.Image(label="Current Image", type="pil")
    base_img_state = gr.State(None)
    history_state = gr.State([])
    gen_btn.click(
        on_generate, 
        [gen_prompt, history_state], 
        [output_view, base_img_state, history_state, history_dd, status]
    ) 
    edit_btn.click(
        on_edit, 
        [edit_prompt, r2, r3, r4, base_img_state, history_state], 
        [output_view, base_img_state, history_state, history_dd, status]
    ) 
    load_btn.click(
        on_load, 
        [history_dd, history_state], 
        [output_view, base_img_state, status]
    )
    clear_btn.click(
        on_clear, 
        None, 
        [output_view, base_img_state, history_state, history_dd, status]
    )
demo.launch(share=True, inline=True, debug = True)

Kita mengatur UI menjadi dua kolom, sehingga kolom kiri berisi input dan tindakan, sedangkan kolom kanan menampilkan gambar saat ini. Berikut cara kita membangun aplikasi Gradio:

• Kotak teks pertama mengumpulkan prompt generasi, dan tombol Generate Base Image memicu fungsi on_generate(). Callback ini menjalankan generasi lokal, menyimpan keluaran ke riwayat, dan memperbarui gambar yang ditampilkan serta gambar kerja saat ini yang disimpan di base_img_state.
• Kotak teks kedua mengumpulkan prompt instruksi edit. Ketika pengguna mengeklik Apply Edit, kita memanggil fungsi on_edit(), yang menggunakan gambar kerja saat ini sebagai gambar dasar dan mengembalikan keluaran edit. Keluaran edit juga ditambahkan ke riwayat dan menjadi gambar kerja baru untuk edit selanjutnya.
• Untuk membuat alur kerja sadar sesi, kita juga menyertakan dropdown Session History sehingga setiap entri sesuai dengan versi tersimpan dari gambar. Tombol Load Selected memicu on_load(), yang memulihkan gambar riwayat yang dipilih dan menjadikannya gambar kerja saat ini lagi. 
• Terakhir, tombol Clear All mereset semuanya melalui fungsi on_clear(), termasuk tampilan keluaran, state gambar dasar, dan riwayat yang tersimpan.

Dua objek State Gradio berikut menjaga semuanya tetap konsisten:

• base_img_state memastikan setiap edit diterapkan pada gambar yang benar.
• history_state menyimpan garis waktu lengkap keluaran untuk pemutaran ulang dan pemecahan cabang.

Terakhir, demo.launch() meluncurkan aplikasi di Colab, menyediakan tautan yang dapat dibagikan, merendernya secara inline, dan mengaktifkan log debug untuk membantu mendiagnosis masalah selama pengembangan.

Contoh dan Observasi FLUX.2 Klein

Untuk memahami bagaimana FLUX.2 Klein berperilaku dalam praktik, saya menjalankan serangkaian eksperimen kecil menggunakan aplikasi Generate and Edit final. Saya menguji tiga pola interaksi utama: generasi gambar dasar, pengeditan hanya dengan prompt, dan pengeditan berbasis referensi menggunakan satu atau lebih gambar. Saya juga memvalidasi alur kerja riwayat sesi untuk memastikan saya dapat memulihkan keluaran sebelumnya dan terus mengedit dari titik tersebut.

Generasi gambar

Saya memulai dengan prompt generasi sederhana untuk membuat gambar dasar yang bersih. Model menghasilkan subjek yang koheren dengan pencahayaan konsisten, detail wajah tajam, dan tata letak adegan stabil. Gambar dasar yang dihasilkan terlihat kuat dan berguna untuk modifikasi selanjutnya alih-alih regenerasi.

Pengeditan gambar dengan satu gambar referensi

Selanjutnya, saya menguji satu gambar referensi sebagai sumber warna, dan menggunakan instruksi edit seperti “Ubah warna gaun menjadi warna dari gambar referensi.” Edit tersebut berhasil mentransfer warna yang diinginkan sambil mempertahankan sebagian besar struktur adegan asli.

Menurut pengamatan saya, edit satu referensi bekerja paling baik ketika prompt sempit dan terikat. Transfer warna dan pewarnaan ulang pakaian sangat andal karena tidak memerlukan perubahan geometri besar. Ketika instruksi edit tetap fokus pada satu atribut, identitas subjek dan detail latar belakang tetap stabil.

Pengeditan gambar dengan satu prompt

Kemudian saya mencoba pengeditan hanya dengan prompt dengan perubahan semantik, seperti “Ganti latar belakang dengan pantai.” Model menangani penggantian latar belakang dengan rapi, sambil menjaga subjek tetap kurang lebih konsisten. 

Saat latar belakang berubah, model sering menyesuaikan suhu warna dan intensitas bayangan untuk menjaga hasil tetap fotorealistik. Ini biasanya menjadi keunggulan, tetapi berarti gambar edit mungkin terlihat seperti sesi pemotretan yang berbeda alih-alih potong-tempel sederhana.

Pemandu pose

Saya menguji edit berbasis pose menggunakan gambar referensi yang menyiratkan posisi tubuh, digabungkan dengan prompt seperti “Cocokkan pose dari gambar referensi.” Gambar hasilnya menggeser pose subjek sambil tetap mempertahankan identitas dan penataan yang serupa.

Berikut gambar referensi yang saya gunakan untuk pemandu pose:

Edit pose memungkinkan, tetapi lebih sensitif daripada edit warna. Perubahan pose apa pun dapat memicu perubahan sekunder seperti jatuhnya kain, penempatan anggota tubuh, dan pembingkaian kamera. Saya butuh beberapa percobaan untuk mendapatkan pose ini dengan tepat, dan masih ada kendala pada penempatan kaki.

Pengeditan gambar dengan banyak gambar referensi

Terakhir, saya menguji edit multi-referensi menggunakan beberapa masukan, seperti referensi palet warna dan prompt edit yang secara eksplisit menyatakan “Hanya ubah warna latar belakang menggunakan palet dari gambar referensi. Jangan ganti latar belakang dengan gambar referensi.” 

Mengejutkan saya, pengeditan multi-referensi

paling efektif saat setiap gambar referensi memiliki peran yang jelas. 

Referensi palet bekerja baik ketika prompt secara eksplisit mengatakan hanya palet dan menghindari instruksi agar model menggunakan konten referensi sebagai pengganti. 

Ketika referensi ambigu, model mungkin meminjam tekstur atau isyarat tata letak alih-alih hanya warna.  Dalam percobaan saya, saya melihat beberapa artefak kecil di mana elemen yang menyerupai gambar referensi sedikit menyusup ke adegan, tetapi hasil keseluruhan tetap terlihat kuat dan konsisten secara visual.

Keuntungan praktis dari demo ini adalah setiap gambar yang dihasilkan dan diedit disimpan dalam riwayat sesi. Anda dapat memuat entri sebelumnya dan terus mengedit dari titik pemeriksaan yang sama persis. Ini membuat eksperimen jauh lebih cepat. Anda dapat memecah cabang edit dari versi sebelumnya, membandingkan beberapa arah edit, dan menghindari kehilangan hasil antara yang bagus. 

Kesimpulan

Dalam tutorial ini, kita membangun alur kerja lengkap untuk generasi dan pengeditan gambar menggunakan FLUX.2 Klein 4B. Dengan menggabungkan generasi teks-ke-gambar lokal melalui Diffusers dengan API pengeditan yang di-host oleh Black Forest Labs, kita berhasil membuat editor gambar interaktif.

Latensi rendah, kemampuan generasi dan pengeditan yang terpadu, serta dukungan multi-referensi dari FLUX.2 Klein membuatnya sangat cocok untuk alur kerja interaktif seperti ini. Dari sini, Anda bisa memperluas aplikasi dengan pengeditan batch, kontrol parameter, persistensi lintas sesi, atau bahkan agen berbasis LLM yang mengusulkan edit secara otomatis.