Cargar un activo en la biblioteca de medios

Utiliza este endpoint para añadir un activo a la biblioteca de medios de Braze utilizando una URL alojada externamente (asset_url) o datos de archivo binario enviados en el cuerpo de la solicitud (asset_file). Este endpoint admite imágenes, documentos y archivos ZIP que los contengan. Para ver la lista completa, consulta Tipos de archivo compatibles.

Tipos de archivo compatibles

Este endpoint admite los siguientes tipos de archivo, tanto si los cargas a través de asset_url como de asset_file.

Si cargas un tipo de archivo que no aparece aquí, el endpoint devuelve un error UNSUPPORTED_FILE_TYPE.

Para archivos ZIP, cada archivo dentro del archivo comprimido también debe ser uno de los tipos de archivo compatibles enumerados aquí, y todos los archivos deben estar en la raíz del archivo ZIP (sin subdirectorios). Cualquier archivo no compatible se omite y se devuelve en el array errors de la respuesta, y el resto del archivo comprimido se carga igualmente.

Nota

Los archivos de contacto virtual (.vcf) y los archivos de video se pueden cargar en la biblioteca de medios, pero solo a través de la interfaz del panel (Contenido > Biblioteca de medios), no a través de este endpoint de API.

Consejo

También puedes llamar a este endpoint a través del servidor MCP de Braze utilizando la función create_media_library_asset. Esto permite que herramientas de IA como Claude y Cursor carguen activos en tu biblioteca de medios mediante indicaciones en lenguaje natural.

Requisitos previos

Para utilizar este endpoint, necesitarás una clave de API con el permiso media_library.create.

Límite de velocidad

Este endpoint tiene un límite de velocidad de 100 solicitudes por hora, como se documenta en Límites de velocidad de la API.

Cuerpo de la solicitud

Cuando incluyes asset_url, el endpoint descarga el archivo desde la URL. Cuando incluyes asset_file, el endpoint utiliza los datos binarios del cuerpo de la solicitud.

Ejemplo de cuerpo de solicitud para asset_url:

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

Ejemplo de cuerpo de solicitud para asset_file:

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

El cuerpo de la solicitud incluye los siguientes parámetros:

Importante

asset_url y asset_file son mutuamente excluyentes; solo debes incluir uno de ellos en tu solicitud de API.

Nombres de los archivos cargados

En esta sección se explica cómo el endpoint asigna nombres a los archivos cargados en función de si incluyes el parámetro name.

Cargas de archivos individuales

Cargas de archivos ZIP

Ejemplo de solicitud

Esta sección incluye dos ejemplos de solicitudes curl, una para añadir un activo utilizando una URL y otra utilizando datos de archivo binario.

Esta solicitud muestra un ejemplo de cómo añadir un activo a la biblioteca de medios utilizando un 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 solicitud muestra un ejemplo de cómo añadir un activo a la biblioteca de medios utilizando un 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"}'

Respuestas de error

En esta sección se enumeran los posibles errores y sus correspondientes mensajes y descripciones.

Errores de validación

Los errores de validación devuelven una estructura como esta:

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

Esta tabla enumera los posibles errores de validación.

Errores de procesamiento

Los errores de procesamiento devuelven una respuesta diferente con códigos de error:

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

Esta tabla enumera los posibles errores de procesamiento.

Respuesta

Hay cinco respuestas de código de estado para este endpoint: 200, 400, 403, 429 y 500.

El siguiente JSON muestra el formato esperado de la respuesta.

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
}