API atual/Referência completa/Venddor Intelligence: ferramentas de IA

Banners por IA

Gera uma imagem de banner a partir de uma descrição, opcionalmente cria o rascunho do banner, e lista o histórico com o custo.

A VI desenha o banner (título e botão renderizados na própria imagem) e guarda a imagem na loja. Cada geração tem custo, registrado em centavos. Com create_banner_draft, a plataforma também cria um banner inativo com a imagem, pronto para o administrador revisar e ativar.

Gerar um banner

Gera a imagem e a devolve já guardada. A chamada só volta quando a imagem está pronta, o que pode levar dezenas de segundos.

POST/api/v1/admin/intelligence/banners/generateAdmin

Gerar um banner

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

promptstringobrigatório

Descrição da imagem, incluindo o texto que deve aparecer nela.

sizestringpadrão: 1536x1024

Tamanho LARGURAxALTURA em pixels, por exemplo 1536x1024. A plataforma ajusta para múltiplos de 16, proporção máxima 3:1 e um limite de área; o padrão é 1536x1024.

qualitystring

lowmediumhighxhighmaxautohdstandard

Qualidade. hd equivale a high; standard ou vazio usa o padrão da loja.

stylestring

Reservado. Aceito, sem efeito garantido.

purposestringpadrão: banner

Finalidade registrada no histórico. Padrão banner.

create_banner_draftbooleanpadrão: false

true cria também um banner inativo com a imagem.

banner_namestring

Nome do rascunho. Padrão AI: mais o início da descrição (até 200 caracteres).

banner_alt_textstring

Texto alternativo do rascunho. Padrão a descrição (até 500 caracteres).

channelsarray

sitevenddor_appclient_app

Onde o rascunho aparece: site, venddor_app, client_app. Sem valor, em todos.

devicesarray

mobiletabletdesktop

Dispositivos do rascunho: mobile, tablet, desktop. Sem valor, todos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/banners/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Banner horizontal de topo, campanha de Natal, título \"Natal com 20% OFF\", botão \"Ver campanha\"",
    "size": "1536x512",
    "create_banner_draft": true,
    "banner_name": "Natal 2026",
    "channels": [
      "site"
    ],
    "devices": [
      "desktop",
      "mobile"
    ]
  }'

Resposta

201Imagem gerada

json

{
  "id": "52587fc7-5efe-493a-b8ac-466465b5916c",
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "purpose": "banner",
  "provider": "image-generator",
  "prompt": "Banner horizontal de topo, campanha de Natal, tons de vermelho e dourado",
  "image_url": "",
  "storage_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/intelligence/ai-banner-8c473118b9337e8b.png",
  "banner_id": "0f9e8d7c-6b5a-4c3b-a291-807f6e5d4c3b",
  "cost_centavos": 94,
  "created_at": "2026-09-09T20:22:36.625538Z"
}

Campos da resposta

iduuid

Id da imagem gerada.

user_iduuid

Quem gerou.

purposestring

Finalidade (banner por padrão).

providerstring

Identificador do gerador. Informativo.

promptstring

Descrição enviada.

revised_promptstring

Descrição ajustada pelo gerador, quando houve. Pode faltar.

image_urlstring

Endereço temporário no gerador. Pode estar vazio; prefira storage_url.

storage_urlstring

Caminho da cópia guardada na loja. Use este.

cost_centavosinteger

Custo da geração, em centavos de real. Veja cost_desconhecido.

cost_desconhecidoboolean

true quando o custo não é conhecido: nesse caso cost_centavos 0 não significa de graça.

generation_idstring

Id da geração no gerador, para conferir com a fatura dele. Pode faltar.

banner_iduuid

Rascunho de banner criado (só na geração, quando pedido e bem-sucedido).

created_atstring

RFC 3339.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","intelligence_generate_images","manage_settings","manage_content"]}`
400	`prompt` vazio ou corpo ilegível.	`{"error":"prompt is required"}`
403	Geração de banners desligada na loja.	`{"error":"__module_disabled__","detail":"enable_ai_banner_generation is OFF"}`
500	Sem gerador de imagem configurado, ou falha na geração.	`{"error":"intelligence: ..."}`

Histórico

Lista as imagens geradas por quem chama, da mais nova para a mais antiga, com o custo total. Com generation_id, devolve as linhas daquela geração, de qualquer usuário, para conferir a fatura do gerador.

GET/api/v1/admin/intelligence/banners/historyAdmin

Histórico de banners gerados

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de consulta

limitintegerpadrão: 50

Quantidade. Padrão 50.

generation_idstring

Id da geração no gerador. Quando enviado, limit e o filtro por usuário são ignorados.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/banners/history?limit=10" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Imagens

json

{
  "images": [
    {
      "id": "52587fc7-5efe-493a-b8ac-466465b5916c",
      "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "purpose": "banner",
      "provider": "image-generator",
      "prompt": "Banner horizontal de topo, campanha de Natal, tons de vermelho e dourado",
      "image_url": "",
      "storage_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/intelligence/ai-banner-8c473118b9337e8b.png",
      "cost_centavos": 94,
      "created_at": "2026-09-09T20:22:36.625538Z"
    }
  ],
  "total": 1,
  "total_cost_centavos": 94
}

Campos da resposta

imagesarray

Imagens, com os campos da geração.

totalinteger

Quantidade devolvida.

total_cost_centavosinteger

Soma de cost_centavos das linhas devolvidas. Linhas com cost_desconhecido entram como 0: o total pode ser menor que o real.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","intelligence_generate_images","manage_settings","manage_content"]}`

Veja também

API atual/Referência completa/Venddor Intelligence: ferramentas de IA

Banners por IA

Gera uma imagem de banner a partir de uma descrição, opcionalmente cria o rascunho do banner, e lista o histórico com o custo.

Gerar um banner

Gera a imagem e a devolve já guardada. A chamada só volta quando a imagem está pronta, o que pode levar dezenas de segundos.

POST/api/v1/admin/intelligence/banners/generateAdmin

Gerar um banner

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

promptstringobrigatório

Descrição da imagem, incluindo o texto que deve aparecer nela.

sizestringpadrão: 1536x1024

Tamanho LARGURAxALTURA em pixels, por exemplo 1536x1024. A plataforma ajusta para múltiplos de 16, proporção máxima 3:1 e um limite de área; o padrão é 1536x1024.

qualitystring

lowmediumhighxhighmaxautohdstandard

Qualidade. hd equivale a high; standard ou vazio usa o padrão da loja.

stylestring

Reservado. Aceito, sem efeito garantido.

purposestringpadrão: banner

Finalidade registrada no histórico. Padrão banner.

create_banner_draftbooleanpadrão: false

true cria também um banner inativo com a imagem.

banner_namestring

Nome do rascunho. Padrão AI: mais o início da descrição (até 200 caracteres).

banner_alt_textstring

Texto alternativo do rascunho. Padrão a descrição (até 500 caracteres).

channelsarray

sitevenddor_appclient_app

Onde o rascunho aparece: site, venddor_app, client_app. Sem valor, em todos.

devicesarray

mobiletabletdesktop

Dispositivos do rascunho: mobile, tablet, desktop. Sem valor, todos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/banners/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Banner horizontal de topo, campanha de Natal, título \"Natal com 20% OFF\", botão \"Ver campanha\"",
    "size": "1536x512",
    "create_banner_draft": true,
    "banner_name": "Natal 2026",
    "channels": [
      "site"
    ],
    "devices": [
      "desktop",
      "mobile"
    ]
  }'

Resposta

201Imagem gerada

json

{
  "id": "52587fc7-5efe-493a-b8ac-466465b5916c",
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "purpose": "banner",
  "provider": "image-generator",
  "prompt": "Banner horizontal de topo, campanha de Natal, tons de vermelho e dourado",
  "image_url": "",
  "storage_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/intelligence/ai-banner-8c473118b9337e8b.png",
  "banner_id": "0f9e8d7c-6b5a-4c3b-a291-807f6e5d4c3b",
  "cost_centavos": 94,
  "created_at": "2026-09-09T20:22:36.625538Z"
}

Campos da resposta

iduuid

Id da imagem gerada.

user_iduuid

Quem gerou.

purposestring

Finalidade (banner por padrão).

providerstring

Identificador do gerador. Informativo.

promptstring

Descrição enviada.

revised_promptstring

Descrição ajustada pelo gerador, quando houve. Pode faltar.

image_urlstring

Endereço temporário no gerador. Pode estar vazio; prefira storage_url.

storage_urlstring

Caminho da cópia guardada na loja. Use este.

cost_centavosinteger

Custo da geração, em centavos de real. Veja cost_desconhecido.

cost_desconhecidoboolean

true quando o custo não é conhecido: nesse caso cost_centavos 0 não significa de graça.

generation_idstring

Id da geração no gerador, para conferir com a fatura dele. Pode faltar.

banner_iduuid

Rascunho de banner criado (só na geração, quando pedido e bem-sucedido).

created_atstring

RFC 3339.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","intelligence_generate_images","manage_settings","manage_content"]}`
400	`prompt` vazio ou corpo ilegível.	`{"error":"prompt is required"}`
403	Geração de banners desligada na loja.	`{"error":"__module_disabled__","detail":"enable_ai_banner_generation is OFF"}`
500	Sem gerador de imagem configurado, ou falha na geração.	`{"error":"intelligence: ..."}`

Histórico

GET/api/v1/admin/intelligence/banners/historyAdmin

Histórico de banners gerados

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de consulta

limitintegerpadrão: 50

Quantidade. Padrão 50.

generation_idstring

Id da geração no gerador. Quando enviado, limit e o filtro por usuário são ignorados.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/banners/history?limit=10" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Imagens

json

{
  "images": [
    {
      "id": "52587fc7-5efe-493a-b8ac-466465b5916c",
      "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "purpose": "banner",
      "provider": "image-generator",
      "prompt": "Banner horizontal de topo, campanha de Natal, tons de vermelho e dourado",
      "image_url": "",
      "storage_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/intelligence/ai-banner-8c473118b9337e8b.png",
      "cost_centavos": 94,
      "created_at": "2026-09-09T20:22:36.625538Z"
    }
  ],
  "total": 1,
  "total_cost_centavos": 94
}

Campos da resposta

imagesarray

Imagens, com os campos da geração.

totalinteger

Quantidade devolvida.

total_cost_centavosinteger

Soma de cost_centavos das linhas devolvidas. Linhas com cost_desconhecido entram como 0: o total pode ser menor que o real.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","intelligence_generate_images","manage_settings","manage_content"]}`