Como salvar artefatos no armazenamento S3 usando Instant API

Visão geral

Por padrão, Instant API (modo não persistente) não salva nenhum dado em lugar nenhum – os resultados da análise são retornados imediatamente na resposta HTTP, e nada é armazenado. A partir da API 6.4.1, um recurso opcional permite salvar artefatos de análise em armazenamento externo para depuração e investigação de incidentes.

Instant API retorna os resultados ao cliente independentemente de o salvamento ter êxito ou falhar – o processo de salvamento é isolado do fluxo principal de análise.

O que é salvo

Quando ativado, os seguintes artefatos são salvos por solicitação de análise em uma pasta identificada por folder_id:

Arquivo	Padrão de nomenclatura	Descrição
Dados iniciais do contêiner (para o fluxo de contêiner)	init_container.dat	Dados iniciais do contêiner
Resposta do engine	{source_media_id}_engine_response.json	Resposta bruta do engine (um arquivo por mídia analisada)
Payload da solicitação	payload.json	O corpo original da solicitação
Resposta da API	response.json	Resposta completa do Instant API (incluindo image_b64 para best shot e, a partir da versão 6.6.1, action shot)
<original_name>	Sem padrão	Nome original do arquivo de mídia

Contêineres inválidos (aqueles que falham na validação) também são salvos.

Para o modo Instant, original_url e thumb_url na resposta da API permanecem null mesmo quando o salvamento está ativado. Os dados salvos são um dump apenas para armazenamento; não há endpoint de API para recuperá-los.

Configuração

Ativando o recurso

O salvamento está desativado por padrão. Para ativá-lo, defina OZ_INSTANT_SAVING_ARTIFACTS_ENABLED como true (padrão: false). Quando ativado, os artefatos são salvos de acordo com o OZ_FILE_STORAGE_TYPE valor (LOCAL ou S3), não exclusivamente em S3.

Tipo de armazenamento

Exemplo (armazenamento em S3):

OZ_FILE_STORAGE_TYPE: "S3"
OZ_LOCAL_STORAGE_SUPPORT_ENABLE: "true"
OZ_S3_STORAGE_SUPPORT_ENABLE: "true"

• OZ_FILE_STORAGE_TYPE – LOCAL ou S3. Determina onde os artefatos são gravados.

• OZ_S3_STORAGE_SUPPORT_ENABLE – deve ser definido como true para que o S3 funcione; derivado de OZ_FILE_STORAGE_TYPE.

• OZ_LOCAL_STORAGE_SUPPORT_ENABLE – habilita suporte a armazenamento local. No SaaS, o suporte local e o suporte a S3 são habilitados simultaneamente, então isso deve ser definido como true também.

Para uma configuração adequada, dependendo do método de instalação utilizado, consulte a documentação fornecida com o pacote de instalação.

Parâmetros de conexão com S3

Para OZ_FILE_STORAGE_TYPE=S3.

Obrigatório

Parâmetro	Descrição
OZ_STATIC_S3_BASE_URL	URL base para construir links públicos para arquivos estáticos
OZ_STATIC_S3_BUCKET	Nome do bucket S3
OZ_STATIC_S3_ENDPOINT_URL	URL do endpoint do S3

Opcional

Parâmetro	Descrição	Padrão
OZ_STATIC_S3_SUFFIX	Prefixo do caminho dentro do bucket	oz-media
OZ_STATIC_S3_BUCKET_URL	URL do bucket S3 (pode ser deixada vazia a partir de 6.5.0)	""
OZ_STATIC_S3_ACCESS_KEY	Chave de acesso do S3	Nenhum
OZ_STATIC_S3_SECRET_KEY	Chave secreta do S3	Nenhum
OZ_STATIC_S3_REGION_NAME	Nome da região da AWS	Nenhum

Formatação do caminho

• OZ_MEDIA_STATIC_FOLDER_FORMAT – strftime formato para a parte da data do caminho de armazenamento (padrão: %Y/%m/%d/%H)

Permissões do bucket S3

As seguintes ações do S3 são necessárias para a função ou usuário do IAM que acessa o bucket:

• s3:ListBucket (no recurso do bucket)

• s3:GetObject (nos objetos dentro do bucket)

• s3:PutObject (nos objetos dentro do bucket)

• s3:DeleteObject (nos objetos dentro do bucket)

ListBucket é usado durante a exclusão: a API lista todos os objetos sob o prefixo da pasta e, em seguida, os exclui individualmente. O S3 não tem uma operação nativa de "excluir pasta".

Exemplo de política do IAM da AWS:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListBucket",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME"
    },
    {
      "Sid": "ObjectOperations",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*"
    }
  ]
}

Impacto da autorização

• OZ_AUTHORIZE_DISABLED_STATELESS – quando true (típico do Instant), company_id no caminho de armazenamento é definido como 00000000-0000-0000-0000-000000000000. Se false, company_id é obtido do JWT.

Exemplo de execução com Docker

sudo docker run -d -it \\
  --name instant \\
  -p 8081:8080 \\
  -e OZ_INSTANT_SAVING_ARTIFACTS_ENABLED=true \\
  -e OZ_STATIC_S3_SUFFIX=instant \\
  -e OZ_STATIC_S3_BUCKET=<bucket> \\
  -e OZ_STATIC_S3_ACCESS_KEY=<key> \\
  -e OZ_STATIC_S3_SECRET_KEY=<secret> \\
  -e OZ_STATIC_S3_ENDPOINT_URL=<endpoint_url> \\
  -e OZ_STATIC_S3_BUCKET_URL=<bucket_url> \\
  -e OZ_STATIC_S3_REGION_NAME=<region> \\
  -e OZ_STATIC_S3_BASE_URL=<base_url> \\
  -e OZ_FILE_STORAGE_TYPE=S3 \\
  <api-instant-image>:<tag>

Caminho de armazenamento

s3://{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/{company_id}/{OZ_MEDIA_STATIC_FOLDER_FORMAT}/{folder_id}/

Onde:

• OZ_MEDIA_STATIC_FOLDER_FORMAT padrão: %Y/%m/%d/%H (por exemplo, 2025/12/18/09)

• company_id = 00000000-0000-0000-0000-000000000000. Quando a autorização está ativada (OZ_AUTHORIZE_DISABLED_STATELESS=false), company_id é obtido da empresa do usuário autenticado.

Exemplo: s3://{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/00000000-0000-0000-0000-000000000000/2025/12/18/09/11111111-1111-1111-1111-111111111111/

Formato do caminho no Full API (para referência)

No modo Full API, o banco de dados armazena o caminho completo do S3, incluindo bucket e sufixo:

s3://{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/11111111-.../2026/04/09/09/.../media_id.jpeg

Na resposta da API, s3:// é substituído por uma URL pública:

{PROTOCOL}://{API_HOSTNAME}/static/{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/...

Para armazenamento local, a substituição se torna {PROTOCOL}://{API_HOSTNAME}/static/.

Instant vs. Full API – comparação do comportamento de armazenamento

Aspecto	Instant API	API completa
Armazenamento por padrão	Nada é armazenado	Todas as mídias e os resultados armazenados no banco de dados + armazenamento de arquivos
Alternância necessária	Sim (OZ_INSTANT_SAVING_ARTIFACTS_ENABLED)	Não (o armazenamento é uma função central)
O que é salvo	mídia, payload, resposta, engine_response	mídia, resultados da análise, miniaturas, best shots, action shots
original_url na resposta	Sempre null	URL pública para arquivo estático
thumb_url na resposta	Sempre null	URL pública para miniatura
Registros no banco de dados	Nenhum (sem estado)	Registros completos de pasta/mídia/análise
Caminho de armazenamento	s3://{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/{company_id}/{OZ_MEDIA_STATIC_FOLDER_FORMAT}/{folder_id}/; não retornado ao cliente	Armazenado no banco de dados como s3://{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/...; resolvido para {PROTOCOL}://{API_HOSTNAME}/static/... na resposta
Exclusão de dados via API	Não aplicável	DELETE /api/folders/{id} remove do banco de dados e do armazenamento