Imagens

O módulo de imagens é o coração da central de mídia do seu blog. Ele gerencia o processamento, armazenamento e a entrega de arquivos, integrando-se diretamente com os provedores de armazenamento (WorkspaceStorage) configurados no seu ambiente.

Pré-requisitos

Para que o upload de imagens funcione corretamente, certifique-se de que:

1. O blog está devidamente vinculado a um Workspace.
2. Um Provedor de Armazenamento foi configurado e selecionado nas definições do blog.
3. O arquivo enviado respeita os tipos de mídia (Mimes) autorizados pelo provedor.

---

Listar Imagens

Este endpoint recupera uma lista paginada de todas as imagens que foram enviadas para o blog, ordenadas pela mais recente.

Requisição HTTP

GET /v1/blog/images

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
page	number	Não	O número da página para visualização (Padrão: 1).
perPage	number	Não	Quantidade de itens por página (Padrão: 20).

Exemplo de Requisição

curl -X GET "https://api.seusite.com/v1/blog/images?page=1&perPage=20" \
  -H "Authorization: Bearer {token}"

Respostas da API

Sucesso (200 OK)

Retorna um objeto contendo a lista de imagens e os metadados de paginação.

{
  "meta": {
    "total": 3,
    "perPage": 20,
    "currentPage": 1,
    "lastPage": 1,
    "firstPage": 1,
    "firstPageUrl": "/?page=1",
    "lastPageUrl": "/?page=1",
    "nextPageUrl": null,
    "previousPageUrl": null
  },
  "data": [
    {
      "id": "7",
      "hash": "4efdbdfa-b867-4821-aa63-8e135eac8bb2",
      "name": "banner-topo.jpg",
      "extension": "jpg",
      "size": 595318,
      "mime": "image/jpeg",
      "uri": "https://storage.provider.com/images/4efdbdfa.jpg",
      "uriThumb": "https://storage.provider.com/images/4efdbdfa_thumb.jpg",
      "createdAt": "2026-03-25T10:43:25.224-03:00"
    }
  ]
}

---

Upload de Imagem

Envia um novo arquivo de imagem para o provedor de armazenamento e registra as referências necessárias no banco de dados.

Requisição HTTP

POST /v1/blog/images

Parâmetros (Multipart/Form-Data)

Atributo	Tipo	Obrigatório	Descrição
image	file	Sim	O arquivo de imagem a ser enviado (Máx: 5MB).

Importante

O sistema valida se a extensão do arquivo (ex: .jpg, .png, .webp) está permitida nas configurações do seu WorkspaceStorage. Se não estiver, a requisição será rejeitada.

Exemplo de Requisição

const formData = new FormData();
formData.append('image', imageFile);

fetch('https://api.seusite.com/v1/blog/images', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {token}'
  },
  body: formData
})
.then(response => response.json());

Respostas da API

Sucesso (201 Created)

A imagem foi processada e armazenada com sucesso.

{
  "id": "9",
  "uri": "https://storage.provider.com/images/c02539de.jpg",
  "uriThumb": "https://storage.provider.com/images/c02539de_thumb.jpg"
}

Erro de Validação (422 Unprocessable Entity)

Ocorre quando o arquivo é muito grande, ausente ou possui uma extensão não permitida.

{
  "errors": [
    { "message": "Arquivo de imagem é obrigatório" }
  ]
}

---

Obter Detalhes da Imagem

Recupera todas as informações técnicas de uma imagem específica através do seu identificador único.

Requisição HTTP

GET /v1/blog/images/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	O ID da imagem que deseja consultar.

Exemplo de Requisição

curl -X GET "https://api.seusite.com/v1/blog/images/9" \
  -H "Authorization: Bearer {token}"

Respostas da API

Sucesso (200 OK)

Retorna o objeto completo da imagem.

{
  "id": "9",
  "hash": "c02539de-d804-474e-868a-96771673018e",
  "name": "paisagem.jpg",
  "extension": "jpg",
  "size": 14692,
  "mime": "image/jpeg",
  "uri": "https://storage.provider.com/images/c02539de.jpg",
  "uriThumb": "https://storage.provider.com/images/c02539de_thumb.jpg",
  "createdAt": "2026-03-25T15:38:23.804-03:00"
}

---

Remover Imagem

Exclui o registro da imagem do sistema. Dependendo da configuração do seu provedor de armazenamento, o arquivo físico também poderá ser removido do storage.

Requisição HTTP

DELETE /v1/blog/images/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	O ID da imagem que deseja remover.

Comportamento de Exclusão

Se o seu WorkspaceStorage estiver com a opção destroyOnDelete ativa, o arquivo físico (incluindo thumbnails) será permanentemente apagado do provedor (S3, Cloud Storage, etc.).

Exemplo de Requisição

fetch('https://api.seusite.com/v1/blog/images/9', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer {token}'
  }
})
.then(response => {
  if (response.status === 204) console.log('Removido com sucesso');
});

Respostas da API

Sucesso (204 No Content)

A imagem foi removida com sucesso. Não há corpo na resposta.

Erro (404 Not Found)

Ocorre caso o ID informado não exista ou não pertença ao seu blog.