Ir para o conteúdo

Fazer upload de um ativo para a biblioteca de mídia

post

/media_library/create

Use este endpoint para adicionar um ativo à biblioteca de mídia da Braze usando uma URL hospedada externamente (asset_url) ou dados de arquivo binário enviados no corpo da solicitação (asset_file). Este endpoint aceita imagens, documentos e arquivos ZIP que os contenham. Para ver a lista completa, consulte Tipos de arquivo suportados.

Tipos de arquivo suportados

Este endpoint aceita os seguintes tipos de arquivo, seja no upload via asset_url ou via asset_file.

Tipo de ativo Tipos de arquivo suportados Tamanho máximo
Imagem GIF, ICO, JPEG, JPG, PNG, WebP 5 MB
Imagem vetorial SVG 5 MB
Documento DOC, DOCX, PDF, PPT, PPTX, XLS, XLSX 5 MB
Arquivo compactado ZIP 50 MB no total, 5 MB por arquivo dentro do ZIP

Se você fizer upload de um tipo de arquivo que não está listado aqui, o endpoint retornará um erro UNSUPPORTED_FILE_TYPE.

Para arquivos ZIP, cada arquivo dentro do arquivo compactado também precisa ser de um dos tipos suportados listados aqui. Além disso, todos os arquivos devem estar na raiz do ZIP (sem subdiretórios). Qualquer arquivo não suportado é ignorado e retornado no array errors da resposta, e o restante do arquivo compactado é enviado normalmente.

Pré-requisitos

Para usar este endpoint, você precisará de uma chave de API com a permissão media_library.create.

Limite de frequência

Esse endpoint tem um limite de frequência de 100 solicitações por hora, conforme documentado em Limites de frequência da API.

Corpo da solicitação

Quando você inclui asset_url, o endpoint baixa o arquivo da URL. Quando você inclui asset_file, o endpoint usa os dados binários do corpo da solicitação.

Exemplo de corpo da solicitação para asset_url:

{
  "asset_url": "https://cdn.example.com/assets/cat.jpg",
  "name": "Cat Graphic"
}

Exemplo de corpo da solicitação para asset_file:

{
  "asset_file": <BINARY FILE DATA>,
  "name": "Cat Graphic"
}

O corpo da solicitação inclui os seguintes parâmetros:

Parâmetro Obrigatório Tipo de dados Descrição
asset_url Opcional String Uma URL acessível publicamente do ativo que será enviado para a Braze.
asset_file Opcional Binário Dados de arquivo binário.
name Opcional String Um nome a ser exibido na biblioteca de mídia para este ativo.

Nomes de arquivos enviados

Esta seção explica como o endpoint atribui nomes aos arquivos enviados, dependendo de você incluir ou não o parâmetro name.

Envios de arquivo único

Cenário Resultado
name fornecido O valor de name é usado como o nome do ativo na biblioteca de mídia.
name excluído É usado o nome original do arquivo da URL ou do arquivo enviado.

Envios de arquivos ZIP

Cenário Resultado
name fornecido O valor de name é usado como prefixo, com um número incremental anexado como sufixo (por exemplo, “My File 1”, “My File 2”, “My File 3”).
name excluído Cada arquivo mantém o nome original que tinha dentro do arquivo ZIP.

Exemplo de solicitação

Esta seção inclui dois exemplos de solicitações curl: uma para adicionar um ativo usando uma URL e outra usando dados de arquivo binário.

Esta solicitação mostra um exemplo de como adicionar um ativo à biblioteca de mídia usando asset_url.

curl -X POST --location 'https://rest.iad-01.braze.com/media_library/create' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--header 'Content-Type: application/json' \
--data '{"asset_url": "https://cdn.example.com/assets/cat.jpg", "name": "Cat Graphic"}'

Esta solicitação mostra um exemplo de como adicionar um ativo à biblioteca de mídia usando asset_file.

curl -X POST --location 'https://rest.iad-01.braze.com/media_library/create' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--header 'Content-Type: application/json' \
--data '{"asset_file":<BINARY FILE DATA>, "name":"Cat Graphic"}'

Respostas de erro

Esta seção lista os possíveis erros, com as mensagens e descrições correspondentes.

Erros de validação

Erros de validação retornam uma estrutura como esta:

{
  "message": (String) Human-readable error description
}

Esta tabela lista os possíveis erros de validação.

Status HTTP Mensagem Descrição
400 “Either asset_url or asset_file must be provided.” Nenhum parâmetro de ativo foi fornecido na solicitação.
400 “Both asset_url and asset_file cannot be provided. Please provide only one.” Os dois parâmetros de ativo foram fornecidos, mas apenas um é permitido.
403 “Media Library Public APIs are not enabled for this company.” O recurso de biblioteca de mídia não está ativado para este espaço de trabalho.

Erros de processamento

Erros de processamento retornam uma resposta diferente, com códigos de erro:

{
  "message": (String) Human-readable error description,
  "error_code": (String) error code,
  "meta": { }
}

Esta tabela lista os possíveis erros de processamento.

Código de erro Status HTTP Descrição
UNSUPPORTED_FILE_TYPE 400 O tipo de arquivo enviado não é suportado. Consulte Tipos de arquivo suportados. O objeto meta inclui o file_type que foi rejeitado.
ASSET_SIZE_EXCEEDS_LIMIT 400 O arquivo excede o tamanho máximo permitido de 5 MB.
MEDIA_LIBRARY_LIMIT_REACHED 400 O espaço de trabalho atingiu o número máximo de ativos (200 por padrão para empresas em teste gratuito; ilimitado nos demais casos). O objeto meta inclui o limit atual.
ASSET_UPLOAD_FAILED 400 O upload do ativo falhou devido a problemas de processamento.
CORRUPT_FILE 400 O arquivo de imagem está corrompido ou não pôde ser decodificado. O objeto meta inclui file_name.
INVALID_ASSET_URL 400 O asset_url está malformado ou não é uma URL HTTP ou HTTPS. O objeto meta inclui asset_url.
FAILED_TO_DOWNLOAD_ASSET 400 A Braze não conseguiu baixar o arquivo em asset_url (por exemplo, o host não pôde ser resolvido, a conexão falhou ou o servidor remoto retornou um erro). O objeto meta inclui asset_url e original_error.
ZIP_UPLOAD_ERROR 400 O arquivo ZIP está corrompido ou não pôde ser aberto. O objeto meta inclui a mensagem original_error.
ZIP_FILE_TOO_LARGE 400 O tamanho total descompactado do arquivo ZIP excede o limite de 50 MB. O objeto meta inclui zip_file_name e zip_file_size.
ZIP_TOO_MANY_ENTRIES 400 O arquivo ZIP contém arquivos demais. Os arquivos ZIP têm um número máximo de entradas permitidas. O objeto meta inclui max_entries.
ZIPPED_ENTITY_HAS_NO_NAME 400 Uma entrada de arquivo dentro do ZIP não tem nome. Confira se o arquivo ZIP não está corrompido e adicione um nome a todas as entradas de arquivo sem nome.
ZIPPED_ENTITY_CANNOT_HAVE_NESTED_DIRECTORY 400 O arquivo ZIP contém diretórios aninhados, que não são suportados. Todos os arquivos devem estar no nível raiz do ZIP.
GENERIC_ERROR 500 Ocorreu um erro inesperado durante o upload. O objeto meta inclui a mensagem original_error para depuração. Tente novamente ou entre em contato com o Suporte.

Resposta

Existem cinco códigos de status de resposta para este endpoint: 200, 400, 403, 429 e 500.

O JSON a seguir mostra o formato esperado da resposta.

{
    "new_assets": [
        {
            "name": (String) the name of the asset,
            "size": (Integer) the byte size of the asset,
            "url": (String) the URL to access the asset,
            "ext": (String) the file extension (e.g., "png", "jpg", "gif")
        }
    ],
    "errors": [
        {
            "name": (String) the name of the asset,
            "size": (Integer) the byte size of the asset,
            "ext": (String) the file extension (e.g., "png", "jpg", "gif"),
            "error": (String) the error that occurred
        }
    ],
    "dashboard_url": (String) the URL to view this asset in the Braze dashboard
}
New Stuff!