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

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 suporta imagens e arquivos ZIP que contêm imagens.

Dica

Você também pode chamar este endpoint por meio do servidor MCP da Braze usando a função create_media_library_asset. Isso permite que ferramentas de IA como Claude e Cursor façam upload de ativos para sua biblioteca de mídia por meio de prompts em linguagem natural.

Pré-requisitos

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

Limite de taxa

Aplicamos o limite de taxa padrão da Braze de 250.000 solicitações por hora a esse endpoint, conforme documentado em Limites de taxa 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 no corpo da solicitação.

Exemplo de corpo da solicitação para asset_url:

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

Exemplo de corpo da solicitação para asset_file:

1
2
3
4
{
  "asset_file": <BINARY FILE DATA>,
  "name": "Cat Graphic"
}

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

Importante

asset_url e asset_file são mutuamente exclusivos. Você deve incluir 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 com base na inclusão ou não do parâmetro name.

Envios de arquivo único

Uploads de arquivos 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 adição de um ativo à biblioteca de mídia usando um asset_url.

1
2
3
4
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 adição de um ativo à biblioteca de mídia usando um asset_file.

1
2
3
4
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 erros potenciais e suas mensagens e descrições correspondentes.

Erros de validação

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

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

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

Erros de processamento

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

1
2
3
4
5
{
  "message": (String) Human-readable error description,
  "error_code": (String) error code,
  "meta": { }
}

Esta tabela lista possíveis erros de processamento.

Resposta

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

O JSON a seguir mostra a forma esperada da resposta.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "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
}