> ## Documentation Index
> Fetch the complete documentation index at: https://www.krea.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Addestra uno stile personalizzato

> Addestra stili di immagine personalizzati dai tuoi dataset e genera output coerenti con indicazioni su curation, tagging e buone pratiche di iterazione.

export const HeroHeader = ({image, video, title, description}) => {
  return <div className="relative aspect-[2/1] h-[30vh] w-full rounded-lg overflow-hidden mb-8">
      {}
      {video && <video autoPlay muted loop playsInline className="absolute top-0 left-0 w-full h-full object-cover hidden md:block m-0" style={{
    zIndex: 1,
    objectPosition: "20% 20%"
  }}>
          <source src={video} type="video/webm" />
        </video>}

      {}
      <img src={image} alt="" className={`absolute top-0 left-0 m-0 w-full h-full object-cover ${video ? "md:hidden" : "block"}`} style={{
    zIndex: 1,
    objectPosition: "20% 20%"
  }} />

      {}
      <div className="absolute inset-0 bg-gradient-to-t from-black/70 via-black/30 to-black/10 flex flex-col justify-end p-8 dark:hidden" style={{
    zIndex: 2
  }}>
        <h1 className="text-4xl font-bold text-white m-0 drop-shadow-[0_2px_4px_rgba(0,0,0,0.5)]">
          {title}
        </h1>
        <p className="text-lg text-white/95 mt-2 drop-shadow-[0_1px_2px_rgba(0,0,0,0.5)]">
          {description}
        </p>
      </div>

      {}
      <div className="absolute inset-0 bg-gradient-to-t from-black/80 via-black/40 to-black/20 hidden dark:flex flex-col justify-end p-8" style={{
    zIndex: 2
  }}>
        <h1 className="text-4xl font-bold text-white m-0 drop-shadow-[0_2px_4px_rgba(0,0,0,0.5)]">
          {title}
        </h1>
        <p className="text-lg text-white/95 mt-2 drop-shadow-[0_1px_2px_rgba(0,0,0,0.5)]">
          {description}
        </p>
      </div>
    </div>;
};

<HeroHeader image="https://s.krea.ai/docs-lora.webp" title="Addestra uno stile personalizzato (LoRA)" description="Addestra uno stile personalizzato usando le tue immagini per generare arte AI con un’estetica visiva coerente." />

## Panoramica

LoRA (Low-Rank Adaptation) è una tecnica di fine-tuning che insegna a un modello di IA un nuovo stile visivo utilizzando un piccolo insieme di immagini di esempio. Funziona iniettando nuovi “style weights” in un modello esistente, rendendo l’addestramento veloce ed efficiente.

Questa guida illustra il flusso completo:

<Steps>
  <Step title="Prepara le immagini di addestramento" icon="images">
    Cura e carica immagini di alta qualità che rappresentino lo stile desiderato
  </Step>

  <Step title="Invia il job di addestramento" icon="play">
    Invia una richiesta POST a `/styles/train` con gli URL delle tue immagini e la configurazione
  </Step>

  <Step title="Monitora i progressi" icon="clock">
    Traccia lo stato del tuo job di addestramento tramite il `job_id` restituito
  </Step>

  <Step title="Genera con il tuo stile" icon="sparkles">
    Applica lo stile addestrato alla generazione di immagini
  </Step>
</Steps>

***

## Prepara le immagini di addestramento

### Curare il tuo dataset

La qualità delle immagini di addestramento influisce direttamente sui risultati. Tipi di addestramento diversi hanno requisiti diversi:

| Tipo          | Caso d’uso                                 | Suggerimenti                             |
| ------------- | ------------------------------------------ | ---------------------------------------- |
| **Style**     | Stili artistici, estetiche visive          | Stile coerente su soggetti vari          |
| **Character** | Somiglianza personale, personaggi coerenti | Pose, espressioni, illuminazione variate |
| **Object**    | Oggetti specifici, prodotti                | Più angolazioni, oggetto coerente        |

### Quante immagini?

La qualità conta molto più della quantità. Un piccolo insieme di immagini eccellenti supererà un ampio insieme di immagini mediocri.

| Dimensione del dataset | Indicazioni                                                         |
| ---------------------- | ------------------------------------------------------------------- |
| **5 immagini**         | Minimo praticabile. Può funzionare per stili semplici e coerenti    |
| **10-30 immagini**     | Consigliato. Miglior equilibrio tra qualità e copertura             |
| **50+ immagini**       | Ritorni decrescenti a meno che lo stile non abbia grande variazione |

<Warning>
  **Qualità > Quantità**

  15 immagini di alta qualità produrranno risultati migliori di 50 di bassa qualità. Dai priorità a:

  * Alta risoluzione (minimo 1024x1024)
  * Stile coerente in tutte le immagini
  * Nessun watermark, sovrapposizione di testo o artefatti di compressione
  * Soggetti variati mantenendo coerenza stilistica
</Warning>

<Info>
  **Dataset di esempio**

  * **Addestramento di personaggi**: foto di una persona con pose, espressioni e condizioni di illuminazione variate. Evita di includere altre persone nelle immagini.
  * **Addestramento di stile**: una collezione di opere d’arte in uno stile coerente. Ad esempio, [The Metropolitan Museum of Art Ukiyo-E Dataset](https://www.kaggle.com/datasets/kengoichiki/the-metropolitan-museum-of-art-ukiyoe-dataset) fornisce stampe xilografiche giapponesi ideali per addestrare uno stile artistico.
</Info>

### Carica le immagini

Prima dell’addestramento, carica le tue immagini per ottenere URL ospitati. Usa l’endpoint `/assets`:

<CodeGroup>
  ```python Python theme={null}
  import requests
  import os
  from dotenv import load_dotenv
  import mimetypes

  load_dotenv()

  API_BASE = "https://api.krea.ai"
  API_TOKEN = os.getenv("API_TOKEN")

  image_dir = "training_images"
  uploaded_urls = []

  for filename in os.listdir(image_dir):
      if filename.lower().endswith(('.jpg', '.jpeg', '.png', '.webp')):
          filepath = os.path.join(image_dir, filename)
          mime_type, _ = mimetypes.guess_type(filepath)

          with open(filepath, 'rb') as f:
              response = requests.post(
                  f"{API_BASE}/assets",
                  headers={"Authorization": f"Bearer {API_TOKEN}"},
                  files={"file": (filename, f, mime_type)},
                  data={"description": f"Training image: {filename}"}
              )

          if response.ok:
              data = response.json()
              uploaded_urls.append(data["image_url"])
              print(f"Uploaded: {filename}")
          else:
              print(f"Failed: {filename}")

  print(f"\nUploaded {len(uploaded_urls)} images")
  ```

  ```bash cURL theme={null}
  # Upload a single image
  curl -X POST https://api.krea.ai/assets \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -F "file=@/path/to/image.jpg" \
    -F "description=Training image"

  # Response: {"id": "...", "image_url": "https://..."}
  ```
</CodeGroup>

<Tip>
  Salva i valori `image_url` restituiti — li passerai all’endpoint di addestramento.
</Tip>

***

## Addestra il tuo stile

### Esempio di addestramento base

Invia gli URL delle tue immagini per iniziare l’addestramento:

<CodeGroup>
  ```python Python theme={null}
  import requests
  import os
  from dotenv import load_dotenv

  load_dotenv()

  API_BASE = "https://api.krea.ai"
  API_TOKEN = os.getenv("API_TOKEN")

  # Training URLs from the upload step
  urls = [
      "https://krea.ai/assets/img1.jpg",
      "https://krea.ai/assets/img2.jpg",
      "https://krea.ai/assets/img3.jpg",
      # ... more images
  ]

  response = requests.post(
      f"{API_BASE}/styles/train",
      headers={
          "Authorization": f"Bearer {API_TOKEN}",
          "Content-Type": "application/json"
      },
      json={
          "name": "Ukiyo-E Style",
          "urls": urls,
          "model": "flux_dev",
          "type": "Style",
          "max_train_steps": 500
      }
  )

  response.raise_for_status()
  job = response.json()
  print(f"Training started! Job ID: {job['job_id']}")
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.krea.ai/styles/train \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Ukiyo-E Style",
      "urls": [
        "https://krea.ai/assets/img1.jpg",
        "https://krea.ai/assets/img2.jpg",
        "https://krea.ai/assets/img3.jpg"
      ],
      "model": "flux_dev",
      "type": "Style",
      "max_train_steps": 500
    }'
  ```
</CodeGroup>

### Tipi di addestramento

Il parametro `type` imposta valori predefiniti intelligenti ottimizzati per il tuo caso d’uso:

| Tipo        | Ideale per                                 |
| ----------- | ------------------------------------------ |
| `Style`     | Stili artistici, estetiche visive          |
| `Character` | Somiglianza personale, personaggi coerenti |
| `Object`    | Oggetti specifici, prodotti                |
| `Default`   | Addestramento generico                     |

### Parametri

#### Parametri obbligatori

<ParamField path="name" type="string" required>
  Un nome descrittivo per il tuo stile personalizzato.

  **Esempio:** `"Ukiyo-E Style"`, `"Product Photos"`
</ParamField>

<ParamField path="urls" type="array" required>
  Array di URL di immagini su cui addestrare. Includi più immagini per risultati migliori.
</ParamField>

#### Parametri opzionali

<ParamField path="model" type="string" default="flux_dev">
  Modello di base per l’addestramento:

  **Modelli di immagini:**

  * `flux_dev` - Alta qualità, versatile
  * `flux_schnell` - Modello realtime di BFL
  * `qwen` - Modello di Alibaba
  * `z-image` - Modello di immagini efficiente di Alibaba
  * `wan22` - Solo generazione di immagini

  **Modelli video:**

  * `wan` - Modello video di Alibaba
</ParamField>

<ParamField path="type" type="string" default="Default">
  Categoria di addestramento: `Style`, `Object`, `Character` o `Default`
</ParamField>

<ParamField path="trigger_word" type="string">
  Parola personalizzata per attivare questo stile nei prompt. Se non specificata, viene utilizzato il nome dello stile.

  <Tip>Scegli trigger word uniche che non compaiano nei prompt tipici. Usa underscore per trigger di più parole: `ukiyo_style`</Tip>
</ParamField>

<Accordion title="Parametri avanzati" icon="sliders">
  <ParamField path="learning_rate" type="number">
    Controlla l’intensità dell’addestramento. Valori più alti addestrano più velocemente ma possono causare overfitting.

    **Intervallo consigliato:** 0.0001 - 0.001
  </ParamField>

  <ParamField path="max_train_steps" type="integer">
    Iterazioni massime di addestramento. Intervallo: 1-2000
  </ParamField>

  <ParamField path="batch_size" type="integer">
    Immagini elaborate simultaneamente. Batch più grandi = addestramento più veloce ma più memoria.
  </ParamField>
</Accordion>

### Ottimizzare i parametri avanzati

Inizia con i valori predefiniti impostati dal campo `type`: funzionano bene per la maggior parte dei casi. Modificali solo se noti problemi specifici:

<AccordionGroup>
  <Accordion title="Learning Rate" icon="gauge">
    Controlla con quanta aggressività il modello si adatta alle tue immagini di addestramento.

    | Valore                      | Quando usarlo                                             |
    | --------------------------- | --------------------------------------------------------- |
    | **0.0001** (più basso)      | Problemi di overfitting, stili complessi, dataset piccoli |
    | **0.0003** (predefinito)    | La maggior parte dei casi d’uso                           |
    | **0.0005-0.001** (più alto) | Addestramento più rapido                                  |

    **Segnali che indicano di regolare:**

    * Gli output sembrano identici alle immagini di addestramento → abbassa il valore
    * L’influenza dello stile è debole dopo l’addestramento → aumenta leggermente il valore
  </Accordion>

  <Accordion title="Training Steps" icon="shoe-prints">
    Per quanto tempo il modello viene addestrato sulle tue immagini.

    | Dimensione del dataset | Step consigliati |
    | ---------------------- | ---------------- |
    | 5-10 immagini          | 300-500 step     |
    | 15-30 immagini         | 500-800 step     |
    | 50+ immagini           | 800-1500 step    |

    **Segnali che indicano di regolare:**

    * Gli output sono troppo rigidi, ignorano i prompt → riduci gli step
    * L’influenza dello stile è debole → aumenta gli step
    * Le immagini generate somigliano esattamente ai dati di addestramento → riduci gli step (overfitting)
  </Accordion>
</AccordionGroup>

<Tip>
  **Ottimizzazione iterativa**

  Se il primo tentativo di addestramento non produce i risultati desiderati:

  1. Inizia regolando `max_train_steps` (la correzione più comune)
  2. Poi prova `learning_rate` se gli step da soli non aiutano
</Tip>

### Formato della risposta

```json theme={null}
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "created_at": "2024-01-15T10:30:00Z"
}
```

***

## Monitora i progressi dell’addestramento

L’addestramento richiede tipicamente 5-15 minuti. Effettua polling sull’API Jobs per verificare lo stato:

<CodeGroup>
  ```python Python theme={null}
  import requests
  import time
  import os
  from dotenv import load_dotenv

  load_dotenv()

  API_BASE = "https://api.krea.ai"
  API_TOKEN = os.getenv("API_TOKEN")
  job_id = "your-job-id"

  while True:
      response = requests.get(
          f"{API_BASE}/jobs/{job_id}",
          headers={"Authorization": f"Bearer {API_TOKEN}"}
      )
      job = response.json()
      status = job["status"]

      print(f"Status: {status}")

      if status == "completed":
          style_id = job["result"]["style_id"]
          print(f"Training complete! Style ID: {style_id}")
          break
      elif status in ["failed", "cancelled"]:
          print(f"Training {status}")
          break

      time.sleep(30)
  ```

  ```bash cURL theme={null}
  # Check job status (repeat until completed)
  curl -X GET https://api.krea.ai/jobs/YOUR_JOB_ID \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```
</CodeGroup>

<Accordion title="Valori di stato del job" icon="diagram-project">
  I job di addestramento attraversano questi stati:

  1. **queued** - In attesa in coda
  2. **processing** - Addestramento attivo
  3. **completed** - Addestramento terminato con successo
  4. **failed** - L’addestramento ha riscontrato un errore
  5. **cancelled** - Job cancellato manualmente
</Accordion>

***

## Usa il tuo stile addestrato

Una volta completato l’addestramento, applica il tuo stile alla generazione di immagini usando il parametro `styles`:

<Warning>
  **Proprietà degli stili tra app e API**

  L’API e la web app di Krea operano come identità utente separate all’interno del tuo workspace. Gli stili sono privati per l’utente che li ha creati, quindi:

  * **Gli stili addestrati dall’app** non sono accessibili tramite l’API a meno che non vengano condivisi
  * **Gli stili addestrati dall’API** non sono accessibili nell’app a meno che non vengano condivisi

  Per condividere uno stile con il tuo workspace (funziona in entrambe le direzioni):

  ```bash theme={null}
  curl -X POST https://api.krea.ai/styles/YOUR_STYLE_ID/share/workspace \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```
</Warning>

<CodeGroup>
  ```python Python theme={null}
  import requests
  import time
  import os
  from dotenv import load_dotenv

  load_dotenv()

  API_BASE = "https://api.krea.ai"
  API_TOKEN = os.getenv("API_TOKEN")
  STYLE_ID = "w29t6pvy0"

  response = requests.post(
      f"{API_BASE}/generate/image/krea/krea-2/medium",
      headers={
          "Authorization": f"Bearer {API_TOKEN}",
          "Content-Type": "application/json"
      },
      json={
          "prompt": "An abstract, colorful, surreal composition of symmetry and balance. Swirling colors, imagery of trees and coalescing patterns converge. The lantern of light and death. It is as if the world was at once dark, and yet again lit.",
          "aspect_ratio": "1:1",
          "resolution": "1K",
          "styles": [
              {
                  "id": STYLE_ID,
                  "strength": 0.95
              }
          ]
      }
  )

  job = response.json()
  job_id = job["job_id"]
  print(f"Generation started! Job ID: {job_id}")

  # Poll for completion
  while True:
      check = requests.get(
          f"{API_BASE}/jobs/{job_id}",
          headers={"Authorization": f"Bearer {API_TOKEN}"}
      )
      status_data = check.json()

      if status_data["status"] == "completed":
          image_url = status_data["result"]["urls"][0]
          print(f"Image ready: {image_url}")
          break
      elif status_data["status"] == "failed":
          print("Generation failed")
          break

      time.sleep(2)
  ```

  ```bash cURL theme={null}
  # Generate with style
  curl -X POST https://api.krea.ai/generate/image/krea/krea-2/medium \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "An abstract, colorful, surreal composition of symmetry and balance. Swirling colors, imagery of trees and coalescing patterns converge. The lantern of light and death. It is as if the world was at once dark, and yet again lit.",
      "aspect_ratio": "1:1",
      "resolution": "1K",
      "styles": [
        {
          "id": "w29t6pvy0",
          "strength": 0.95
        }
      ]
    }'

  # Then poll /jobs/{job_id} for the result
  ```
</CodeGroup>

### Intensità dello stile

Il parametro `strength` (0.0-1.0) controlla quanto fortemente viene applicato il tuo stile:

| Intensità | Effetto                                                          |
| --------- | ---------------------------------------------------------------- |
| 0.5-0.7   | Influenza sottile, mantiene flessibilità del prompt              |
| 0.8-0.9   | Applicazione forte dello stile, punto di partenza consigliato    |
| 0.95-1.0  | Massima aderenza allo stile, può ridurre la reattività al prompt |

<Tip>
  Inizia con un’intensità di `0.8` e regola in base ai risultati. Valori più bassi offrono maggiore libertà creativa; valori più alti impongono un’aderenza più stretta allo stile.
</Tip>

### Combinare più stili

Applica più stili aggiungendoli all’array `styles`:

```python theme={null}
"styles": [
    {"id": "style-id-1", "strength": 0.6},
    {"id": "style-id-2", "strength": 0.4}
]
```

***

## Buone pratiche

<AccordionGroup>
  <Accordion title="Selezione delle immagini" icon="images">
    * Usa quante più immagini di alta qualità hai per risultati ottimali
    * Assicura uno stile coerente in tutte le immagini di addestramento
    * Includi varietà nei soggetti mantenendo coerenza stilistica
    * Evita watermark, sovrapposizioni di testo o artefatti
    * Usa immagini di almeno 1024x1024 di risoluzione
  </Accordion>

  <Accordion title="Configurazione dell’addestramento" icon="sliders">
    * Inizia con i parametri predefiniti usando il campo `type`
    * Per gli stili: 500-1000 step sono di solito sufficienti
    * Learning rate più bassi (0.0001-0.0003) prevengono l’overfitting
    * Aumenta gli step se lo stile non è abbastanza forte
    * Riduci gli step se l’output è troppo rigido
  </Accordion>

  <Accordion title="Trigger word" icon="wand-magic-sparkles">
    * Usa la stessa trigger word se prevedi di combinare più stili
    * Le trigger word vengono iniettate automaticamente nel prompt se includi lo stile
    * Evita parole comuni che compaiono nei prompt tipici
    * Usa underscore per trigger di più parole: `my_custom_style`
  </Accordion>
</AccordionGroup>