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

# Treinar um estilo personalizado

> Treine estilos de imagem personalizados a partir dos seus próprios conjuntos de dados e gere resultados consistentes com orientações sobre curadoria, etiquetagem e boas práticas de iteração.

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="Treinar um estilo personalizado (LoRA)" description="Treine um estilo personalizado usando as suas próprias imagens para gerar arte IA com estéticas visuais consistentes." />

## Visão geral

LoRA (Low-Rank Adaptation) é uma técnica de afinamento que ensina um modelo de IA um novo estilo visual usando um pequeno conjunto de imagens de exemplo. Funciona injetando novos “pesos de estilo” num modelo existente, tornando o treino rápido e eficiente.

Este guia percorre o fluxo de trabalho completo:

<Steps>
  <Step title="Preparar imagens de treino" icon="images">
    Fazer curadoria e carregar imagens de alta qualidade que representem o estilo pretendido
  </Step>

  <Step title="Submeter tarefa de treino" icon="play">
    Enviar um pedido POST para `/styles/train` com os URLs das imagens e a configuração
  </Step>

  <Step title="Monitorizar progresso" icon="clock">
    Acompanhar o estado da tarefa de treino usando o `job_id` devolvido
  </Step>

  <Step title="Gerar com o seu estilo" icon="sparkles">
    Aplicar o estilo treinado à geração de imagens
  </Step>
</Steps>

***

## Preparar imagens de treino

### Curar o seu conjunto de dados

A qualidade das suas imagens de treino tem impacto direto nos resultados. Diferentes tipos de treino têm requisitos diferentes:

| Tipo          | Caso de uso                                  | Dicas                                   |
| ------------- | -------------------------------------------- | --------------------------------------- |
| **Style**     | Estilos artísticos, estéticas visuais        | Estilo consistente em diversos temas    |
| **Character** | Semelhança pessoal, personagens consistentes | Poses, expressões e iluminação variadas |
| **Object**    | Itens específicos, produtos                  | Vários ângulos, objeto consistente      |

### Quantas imagens?

A qualidade importa muito mais do que a quantidade. Um pequeno conjunto de imagens excelentes irá superar um grande conjunto de imagens medianas.

| Tamanho do conjunto | Orientação                                                         |
| ------------------- | ------------------------------------------------------------------ |
| **5 imagens**       | Mínimo viável. Pode funcionar para estilos simples e consistentes  |
| **10-30 imagens**   | Recomendado. Melhor equilíbrio entre qualidade e cobertura         |
| **50+ imagens**     | Retornos decrescentes, a não ser que o estilo tenha muita variação |

<Warning>
  **Qualidade > Quantidade**

  15 imagens de alta qualidade produzirão melhores resultados do que 50 de baixa qualidade. Dê prioridade a:

  * Alta resolução (mínimo 1024x1024)
  * Estilo consistente em todas as imagens
  * Sem marcas de água, texto sobreposto ou artefactos de compressão
  * Assuntos variados, mantendo a coerência de estilo
</Warning>

<Info>
  **Exemplos de conjuntos de dados**

  * **Treino de personagem**: fotografias de uma pessoa com poses, expressões e iluminação variadas. Evite incluir outras pessoas nas imagens.
  * **Treino de estilo**: uma coleção de obras num estilo consistente. Por exemplo, [The Metropolitan Museum of Art Ukiyo-E Dataset](https://www.kaggle.com/datasets/kengoichiki/the-metropolitan-museum-of-art-ukiyoe-dataset) fornece xilogravuras japonesas ideais para treinar um estilo artístico.
</Info>

### Carregar imagens

Antes de treinar, carregue as suas imagens para obter URLs alojados. Use o 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>
  Guarde os valores de `image_url` devolvidos — irá passá-los ao endpoint de treino.
</Tip>

***

## Treinar o seu estilo

### Exemplo básico de treino

Submeta os seus URLs de imagens para começar o treino:

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

### Tipos de treino

O parâmetro `type` define predefinições inteligentes otimizadas para o seu caso de uso:

| Tipo        | Ideal para                                   |
| ----------- | -------------------------------------------- |
| `Style`     | Estilos artísticos, estéticas visuais        |
| `Character` | Semelhança pessoal, personagens consistentes |
| `Object`    | Itens específicos, produtos                  |
| `Default`   | Treino genérico                              |

### Parâmetros

#### Parâmetros obrigatórios

<ParamField path="name" type="string" required>
  Um nome descritivo para o seu estilo personalizado.

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

<ParamField path="urls" type="array" required>
  Array de URLs de imagens a usar para o treino. Inclua mais imagens para melhores resultados.
</ParamField>

#### Parâmetros opcionais

<ParamField path="model" type="string" default="flux_dev">
  Modelo base para treino:

  **Modelos de imagem:**

  * `flux_dev` - Alta qualidade, versátil
  * `flux_schnell` - Modelo em tempo real da BFL
  * `qwen` - Modelo da Alibaba
  * `z-image` - Modelo de imagem eficiente da Alibaba
  * `wan22` - Apenas geração de imagem

  **Modelos de vídeo:**

  * `wan` - Modelo de vídeo da Alibaba
</ParamField>

<ParamField path="type" type="string" default="Default">
  Categoria de treino: `Style`, `Object`, `Character` ou `Default`
</ParamField>

<ParamField path="trigger_word" type="string">
  Palavra personalizada para ativar este estilo nos prompts. Quando não especificada, é usado o nome do estilo.

  <Tip>Escolha palavras de ativação únicas que não apareçam em prompts típicos. Use underscores para gatilhos com várias palavras: `ukiyo_style`</Tip>
</ParamField>

<Accordion title="Parâmetros avançados" icon="sliders">
  <ParamField path="learning_rate" type="number">
    Controla a intensidade do treino. Valores mais altos treinam mais depressa, mas podem levar a overfitting.

    **Intervalo recomendado:** 0.0001 - 0.001
  </ParamField>

  <ParamField path="max_train_steps" type="integer">
    Iterações máximas de treino. Intervalo: 1-2000
  </ParamField>

  <ParamField path="batch_size" type="integer">
    Imagens processadas em simultâneo. Lotes maiores = treino mais rápido, mas mais memória.
  </ParamField>
</Accordion>

### Ajustar parâmetros avançados

Comece com as predefinições do campo `type` — funcionam bem na maioria dos casos. Só ajuste estes valores se estiver a ver problemas específicos:

<AccordionGroup>
  <Accordion title="Taxa de aprendizagem" icon="gauge">
    Controla o quão agressivamente o modelo se adapta às suas imagens de treino.

    | Valor                        | Quando usar                                                     |
    | ---------------------------- | --------------------------------------------------------------- |
    | **0.0001** (mais baixo)      | Problemas de overfitting, estilos complexos, conjuntos pequenos |
    | **0.0003** (predefinição)    | A maioria dos casos                                             |
    | **0.0005-0.001** (mais alto) | Treino mais rápido                                              |

    **Sinais de que precisa de ajustar:**

    * Os resultados parecem idênticos às imagens de treino → baixe a taxa
    * A influência do estilo é fraca após o treino → aumente ligeiramente a taxa
  </Accordion>

  <Accordion title="Passos de treino" icon="shoe-prints">
    Quanto tempo o modelo treina com as suas imagens.

    | Tamanho do conjunto | Passos recomendados |
    | ------------------- | ------------------- |
    | 5-10 imagens        | 300-500 passos      |
    | 15-30 imagens       | 500-800 passos      |
    | 50+ imagens         | 800-1500 passos     |

    **Sinais de que precisa de ajustar:**

    * Os resultados são demasiado rígidos, ignorando os prompts → reduza os passos
    * A influência do estilo é fraca → aumente os passos
    * As imagens geradas são iguais aos dados de treino → reduza os passos (overfitting)
  </Accordion>
</AccordionGroup>

<Tip>
  **Ajuste iterativo**

  Se a sua primeira tentativa de treino não produzir os resultados que quer:

  1. Comece por ajustar `max_train_steps` (correção mais comum)
  2. Depois experimente `learning_rate` se só os passos não ajudarem
</Tip>

### Formato da resposta

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

***

## Monitorizar o progresso do treino

O treino demora normalmente 5-15 minutos. Consulte a Jobs API para verificar o estado:

<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="Valores de estado da tarefa" icon="diagram-project">
  As tarefas de treino progridem por estes estados:

  1. **queued** - À espera na fila
  2. **processing** - Treino ativo
  3. **completed** - Treino concluído com sucesso
  4. **failed** - Treino encontrou um erro
  5. **cancelled** - Tarefa cancelada manualmente
</Accordion>

***

## Utilizar o seu estilo treinado

Assim que o treino terminar, aplique o seu estilo à geração de imagens usando o parâmetro `styles`:

<Warning>
  **Propriedade dos estilos entre a aplicação e a API**

  A API e a aplicação web da Krea operam como identidades de utilizador separadas dentro da sua workspace. Os estilos são privados do utilizador que os criou, portanto:

  * **Estilos treinados na aplicação** não são acessíveis via API, a menos que sejam partilhados
  * **Estilos treinados na API** não são acessíveis na aplicação, a menos que sejam partilhados

  Para partilhar um estilo com a sua workspace (funciona nos dois sentidos):

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

### Intensidade do estilo

O parâmetro `strength` (0.0-1.0) controla o quão fortemente o seu estilo é aplicado:

| Intensidade | Efeito                                                      |
| ----------- | ----------------------------------------------------------- |
| 0.5-0.7     | Influência subtil, mantém flexibilidade do prompt           |
| 0.8-0.9     | Aplicação forte do estilo, ponto de partida recomendado     |
| 0.95-1.0    | Aderência máxima ao estilo, pode reduzir resposta ao prompt |

<Tip>
  Comece com uma intensidade de `0.8` e ajuste com base nos resultados. Valores mais baixos dão mais liberdade criativa; valores mais altos impõem uma aderência mais estrita ao estilo.
</Tip>

### Combinar vários estilos

Aplique vários estilos adicionando-os ao array `styles`:

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

***

## Boas práticas

<AccordionGroup>
  <Accordion title="Seleção de imagens" icon="images">
    * Use tantas imagens de alta qualidade quantas tiver para resultados ideais
    * Assegure um estilo consistente em todas as imagens de treino
    * Inclua variedade de temas mantendo a coerência de estilo
    * Evite marcas de água, texto sobreposto ou artefactos
    * Use imagens com pelo menos 1024x1024 de resolução
  </Accordion>

  <Accordion title="Configuração do treino" icon="sliders">
    * Comece com os parâmetros predefinidos usando o campo `type`
    * Para estilos: 500-1000 passos são geralmente suficientes
    * Taxas de aprendizagem mais baixas (0.0001-0.0003) evitam overfitting
    * Aumente os passos se o estilo não for suficientemente forte
    * Reduza os passos se o resultado for demasiado rígido
  </Accordion>

  <Accordion title="Palavras de ativação" icon="wand-magic-sparkles">
    * Use a mesma palavra de ativação se planear combinar vários estilos
    * As palavras de ativação são injetadas automaticamente no prompt se incluir o estilo
    * Evite palavras comuns que apareçam em prompts típicos
    * Use underscores para gatilhos com várias palavras: `my_custom_style`
  </Accordion>
</AccordionGroup>