Fazer upload de um ativo para a biblioteca de mídia
/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.

Arquivos de contato virtual (.vcf) e arquivos de vídeo podem ser enviados para a biblioteca de mídia, mas apenas pela interface do dashboard (Conteúdo > Biblioteca de mídia), não por este endpoint de API.

Você também pode chamar este endpoint por meio do servidor MCP da Braze usando a função create_media_library_asset. Assim, ferramentas de IA como Claude e Cursor podem fazer upload de ativos para sua biblioteca de mídia com prompts em linguagem natural.
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. |

asset_url e asset_file são mutuamente exclusivos. Inclua apenas um deles na sua solicitação de API.
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
}