> ## 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 datasets e gere saídas consistentes com orientações sobre curadoria, marcação 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 suas próprias imagens para gerar arte com IA com uma estética visual consistente." />

## Visão geral

LoRA (Low-Rank Adaptation) é uma técnica de fine-tuning que ensina a um modelo de IA um novo estilo visual usando um pequeno conjunto de imagens de exemplo. Ela funciona injetando novos "pesos de estilo" em um modelo existente, tornando o treinamento rápido e eficiente.

Este guia percorre o fluxo completo:

<Steps>
  <Step title="Preparar imagens de treinamento" icon="images">
    Faça a curadoria e upload de imagens de alta qualidade que representem o estilo desejado
  </Step>

  <Step title="Enviar job de treinamento" icon="play">
    Envie uma requisição POST para `/styles/train` com as URLs das imagens e a configuração
  </Step>

  <Step title="Monitorar o progresso" icon="clock">
    Acompanhe o status do seu job de treinamento usando o `job_id` retornado
  </Step>

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

***

## Preparar imagens de treinamento

### Curando seu dataset

A qualidade das suas imagens de treinamento impacta diretamente os resultados. Diferentes tipos de treinamento têm requisitos distintos:

| Tipo           | Caso de uso                                 | Dicas                                   |
| -------------- | ------------------------------------------- | --------------------------------------- |
| **Estilo**     | Estilos artísticos, estéticas visuais       | Estilo consistente em assuntos variados |
| **Personagem** | Aparência pessoal, personagens consistentes | Poses, expressões e iluminação variadas |
| **Objeto**     | Itens específicos, produtos                 | Múltiplos ângulos, objeto consistente   |

### Quantas imagens?

Qualidade importa muito mais que quantidade. Um pequeno conjunto de imagens excelentes vai superar um grande conjunto de imagens medianas.

| Tamanho do dataset | 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 menos que o estilo tenha alta variação   |

<Warning>
  **Qualidade > Quantidade**

  15 imagens de alta qualidade produzirão melhores resultados que 50 de baixa qualidade. Priorize:

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

<Info>
  **Datasets de exemplo**

  * **Treinamento de personagem**: fotos de uma pessoa com poses, expressões e condições de iluminação variadas. Evite incluir outras pessoas nas imagens.
  * **Treinamento de estilo**: uma coleção de obras de arte em um estilo consistente. Por exemplo, o [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>

### Fazer upload das imagens

Antes do treinamento, faça upload das suas imagens para obter URLs hospedadas. 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>
  Salve os valores de `image_url` retornados — você os passará para o endpoint de treinamento.
</Tip>

***

## Treinar seu estilo

### Exemplo básico de treinamento

Envie as URLs das suas imagens para iniciar o treinamento:

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

O parâmetro `type` define padrões inteligentes otimizados para seu caso de uso:

| Tipo        | Melhor para                                 |
| ----------- | ------------------------------------------- |
| `Style`     | Estilos artísticos, estéticas visuais       |
| `Character` | Aparência pessoal, personagens consistentes |
| `Object`    | Itens específicos, produtos                 |
| `Default`   | Treinamento genérico                        |

### Parâmetros

#### Parâmetros obrigatórios

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

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

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

#### Parâmetros opcionais

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

  **Modelos de imagem:**

  * `flux_dev` - Alta qualidade, versátil
  * `flux_schnell` - Modelo em tempo real da BFL
  * `qwen` - Modelo da Alibaba
  * `z-image` - Modelo eficiente de imagem 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 treinamento: `Style`, `Object`, `Character` ou `Default`
</ParamField>

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

  <Tip>Escolha palavras-gatilho únicas que não apareçam em prompts típicos. Use underscores para gatilhos com múltiplas palavras: `ukiyo_style`</Tip>
</ParamField>

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

    **Faixa recomendada:** 0.0001 - 0.001
  </ParamField>

  <ParamField path="max_train_steps" type="integer">
    Máximo de iterações de treinamento. Faixa: 1-2000
  </ParamField>

  <ParamField path="batch_size" type="integer">
    Imagens processadas simultaneamente. Lotes maiores = treinamento mais rápido, mas mais memória.
  </ParamField>
</Accordion>

### Ajustando parâmetros avançados

Comece com os padrões definidos pelo campo `type` — eles funcionam bem para a maioria dos casos. Ajuste-os apenas se você observar problemas específicos:

<AccordionGroup>
  <Accordion title="Learning rate" icon="gauge">
    Controla o quão agressivamente o modelo se adapta às suas imagens de treinamento.

    | Valor                    | Quando usar                                                    |
    | ------------------------ | -------------------------------------------------------------- |
    | **0.0001** (menor)       | Problemas de overfitting, estilos complexos, datasets pequenos |
    | **0.0003** (padrão)      | Maioria dos casos                                              |
    | **0.0005-0.001** (maior) | Treinamento mais rápido                                        |

    **Sinais de que você precisa ajustar:**

    * As saídas parecem idênticas às imagens de treinamento → reduza a taxa
    * A influência do estilo está fraca após o treinamento → aumente a taxa levemente
  </Accordion>

  <Accordion title="Passos de treinamento" icon="shoe-prints">
    Por quanto tempo o modelo treina nas suas imagens.

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

    **Sinais de que você precisa ajustar:**

    * Saídas muito rígidas, ignorando os prompts → reduza os passos
    * Influência do estilo fraca → aumente os passos
    * Imagens geradas ficam exatamente iguais aos dados de treinamento → reduza os passos (overfitting)
  </Accordion>
</AccordionGroup>

<Tip>
  **Ajuste iterativo**

  Se sua primeira tentativa de treinamento não produzir os resultados desejados:

  1. Comece ajustando `max_train_steps` (correção mais comum)
  2. Depois tente `learning_rate` se os passos sozinhos 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"
}
```

***

## Monitorar o progresso do treinamento

O treinamento normalmente leva de 5 a 15 minutos. Faça polling na Jobs API para verificar o status:

<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 status do job" icon="diagram-project">
  Jobs de treinamento passam por estes estados:

  1. **queued** - Aguardando na fila
  2. **processing** - Treinamento ativo
  3. **completed** - Treinamento concluído com sucesso
  4. **failed** - Treinamento encontrou um erro
  5. **cancelled** - Job cancelado manualmente
</Accordion>

***

## Usar seu estilo treinado

Assim que o treinamento for concluído, aplique seu estilo à geração de imagens usando o parâmetro `styles`:

<Warning>
  **Propriedade do estilo entre o app e a API**

  A API e o webapp da Krea operam como identidades de usuário separadas dentro do seu workspace. Estilos são privados do usuário que os criou, portanto:

  * **Estilos treinados no app** não são acessíveis pela API, a menos que sejam compartilhados
  * **Estilos treinados na API** não são acessíveis no app, a menos que sejam compartilhados

  Para compartilhar um estilo com seu 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>

### Força do estilo

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

| Força    | Efeito                                                            |
| -------- | ----------------------------------------------------------------- |
| 0.5-0.7  | Influência sutil, 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 responsividade ao prompt |

<Tip>
  Comece com força `0.8` e ajuste com base nos resultados. Valores menores dão mais liberdade criativa; valores maiores impõem aderência mais estrita ao estilo.
</Tip>

### Combinando múltiplos 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 quantas imagens de alta qualidade você tiver para melhores resultados
    * Garanta estilo consistente em todas as imagens de treinamento
    * Inclua variedade nos assuntos mantendo a coerência de estilo
    * Evite marcas d'água, sobreposições de texto ou artefatos
    * Use imagens com pelo menos 1024x1024 de resolução
  </Accordion>

  <Accordion title="Configuração de treinamento" icon="sliders">
    * Comece com os parâmetros padrão usando o campo `type`
    * Para estilos: 500-1000 passos costumam ser suficientes
    * Learning rates menores (0.0001-0.0003) previnem overfitting
    * Aumente os passos se o estilo não estiver forte o suficiente
    * Diminua os passos se a saída estiver muito rígida
  </Accordion>

  <Accordion title="Palavras-gatilho" icon="wand-magic-sparkles">
    * Use a mesma palavra-gatilho se você planeja combinar múltiplos estilos
    * As palavras-gatilho são injetadas automaticamente no prompt se você incluir o estilo
    * Evite palavras comuns que aparecem em prompts típicos
    * Use underscores para gatilhos com múltiplas palavras: `my_custom_style`
  </Accordion>
</AccordionGroup>