API atual/Referência completa/AI Builder

Gerar banners

Gera imagens de banner com o serviço de imagens configurado na loja.

As duas rotas chamam o serviço de geração de imagens definido em image_api_url nos ajustes. Sem ele configurado, usam um serviço padrão da plataforma que pode estar indisponível. As imagens voltam em base64 (data URI) ou por URL, conforme o serviço.

Gerar um banner

Gera uma imagem a partir de um texto descritivo. Informe position para usar as dimensões recomendadas daquela posição, ou width e height. O serviço é instruído a não desenhar letras na imagem.

POST/api/v1/admin/ai-builder/generate-bannerAdmin

Gerar um banner a partir de um texto

Requer o privilégio manage_theme.

Corpo da requisição

promptstringobrigatório

Descrição da imagem. Obrigatório.

positionstring

hero_fullhero_tallsquare_gridwide_cardsidebarcategory_headermobile_hero

Posição, que define o tamanho (vale sobre width e height): hero_full 1920x640, hero_tall 1920x800, square_grid 640x640, wide_card 800x400, sidebar 300x600, category_header 1920x400, mobile_hero 750x500.

widthintegerpadrão: 1920

Largura em pixels.

heightintegerpadrão: 640

Altura em pixels.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/generate-banner" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Fotografia de ceramicas artesanais sobre mesa de madeira, luz suave da manha",
    "position": "hero_full"
  }'

Resposta

200Imagem gerada

json

{
  "images": [
    "data:image/png;base64,iVBORw0KGgo..."
  ],
  "image": "data:image/png;base64,iVBORw0KGgo...",
  "url": ""
}

Campos da resposta

imagesstring[]

Imagens em base64 (data URI).

imagestring

A primeira imagem, quando o serviço a devolve.

urlstring

Endereço da imagem, quando o serviço a hospeda.

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`prompt` vazio.	`{"error":"prompt is required"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
500	O serviço de imagens falhou, estourou o tempo ou não devolveu imagens.	`{"error":"banner generation failed","detail":"banner API error 502: ..."}`

Gerar os 3 banners do tema

Gera em sequência três banners nas posições hero_full, square_grid e wide_card. O conjunto inteiro tem 10 segundos para terminar; se estourar, a rota responde 504. Banners que falham individualmente são pulados.

POST/api/v1/admin/ai-builder/generate-theme-bannersAdmin

Gerar o conjunto de 3 banners do tema

Requer o privilégio manage_theme.

Corpo da requisição

store_namestring

Nome da loja. Aceito, mas hoje não altera as imagens.

store_typestring

Tipo de loja. Aceito, mas hoje não altera as imagens.

primary_colorstring

Cor principal. Aceita, mas hoje não altera as imagens.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/generate-theme-banners" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "store_name": "Casa Aurora",
    "store_type": "artesanato",
    "primary_color": "#B45309"
  }'

Resposta

200Banners gerados

json

{
  "banners": [
    {
      "position": "hero_full",
      "prompt": "...",
      "width": 1920,
      "height": 640,
      "images": [
        "data:image/png;base64,..."
      ],
      "url": ""
    }
  ]
}

Campos da resposta

bannersobject[]

Banners que deram certo, cada um com position, prompt, width, height, images[] e url. Pode vir vazio ou com menos de 3.

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
500	Falha geral na geração.	`{"error":"banner generation failed","detail":"..."}`
504	O conjunto passou de 10 segundos.	`{"error":"banner generation timed out","detail":"context deadline exceeded"}`

Veja também

API atual/Referência completa/AI Builder

Gerar banners

Gera imagens de banner com o serviço de imagens configurado na loja.

Gerar um banner

POST/api/v1/admin/ai-builder/generate-bannerAdmin

Gerar um banner a partir de um texto

Requer o privilégio manage_theme.

Corpo da requisição

promptstringobrigatório

Descrição da imagem. Obrigatório.

positionstring

hero_fullhero_tallsquare_gridwide_cardsidebarcategory_headermobile_hero

widthintegerpadrão: 1920

Largura em pixels.

heightintegerpadrão: 640

Altura em pixels.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/generate-banner" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Fotografia de ceramicas artesanais sobre mesa de madeira, luz suave da manha",
    "position": "hero_full"
  }'

Resposta

200Imagem gerada

json

{
  "images": [
    "data:image/png;base64,iVBORw0KGgo..."
  ],
  "image": "data:image/png;base64,iVBORw0KGgo...",
  "url": ""
}

Campos da resposta

imagesstring[]

Imagens em base64 (data URI).

imagestring

A primeira imagem, quando o serviço a devolve.

urlstring

Endereço da imagem, quando o serviço a hospeda.

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`prompt` vazio.	`{"error":"prompt is required"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
500	O serviço de imagens falhou, estourou o tempo ou não devolveu imagens.	`{"error":"banner generation failed","detail":"banner API error 502: ..."}`

Gerar os 3 banners do tema

POST/api/v1/admin/ai-builder/generate-theme-bannersAdmin

Gerar o conjunto de 3 banners do tema

Requer o privilégio manage_theme.

Corpo da requisição

store_namestring

Nome da loja. Aceito, mas hoje não altera as imagens.

store_typestring

Tipo de loja. Aceito, mas hoje não altera as imagens.

primary_colorstring

Cor principal. Aceita, mas hoje não altera as imagens.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/generate-theme-banners" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "store_name": "Casa Aurora",
    "store_type": "artesanato",
    "primary_color": "#B45309"
  }'

Resposta

200Banners gerados

json

{
  "banners": [
    {
      "position": "hero_full",
      "prompt": "...",
      "width": 1920,
      "height": 640,
      "images": [
        "data:image/png;base64,..."
      ],
      "url": ""
    }
  ]
}

Campos da resposta

bannersobject[]

Banners que deram certo, cada um com position, prompt, width, height, images[] e url. Pode vir vazio ou com menos de 3.

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
500	Falha geral na geração.	`{"error":"banner generation failed","detail":"..."}`
504	O conjunto passou de 10 segundos.	`{"error":"banner generation timed out","detail":"context deadline exceeded"}`