Skip to content

Cargar un activo en la biblioteca de medios

post

/media_library/create

Utiliza este punto de conexión 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 punto de conexión admite imágenes y archivos ZIP que contienen imágenes.

Requisitos previos

Para utilizar este punto de conexión, necesitarás una clave de API con el permiso media_library.create.

Límite de velocidad

Aplicamos el límite de velocidad predeterminado de Braze de 250 000 solicitudes por hora a este punto de conexión, como se documenta en Límites de velocidad de la API.

Cuerpo de la solicitud

Cuando incluyes asset_url, el punto de conexión descarga el archivo desde la URL. Cuando incluyes asset_file, el punto de conexión 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:

Parámetro Obligatorio Tipo de datos Descripción
asset_url Opcional Cadena Una URL de acceso público para el activo que se va a cargar en Braze.
asset_file Opcional Binario Datos de archivo binario.
name Opcional Cadena Nombre que aparecerá en la biblioteca de medios para este activo.

Nombres de los archivos cargados

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

Cargas de archivos individuales

Escenario Resultado
name proporcionado El valor de name se utiliza como nombre del activo en la biblioteca de medios.
name excluido Se utiliza el nombre de archivo original de la URL o del archivo cargado.

Cargas de archivos ZIP

Escenario Resultado
name proporcionado El valor de name se utiliza como prefijo, con un número incremental añadido como sufijo (por ejemplo, “Mi archivo 1”, “Mi archivo 2”, “Mi archivo 3”).
name excluido Cada archivo conserva su nombre original dentro del archivo 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.

Estado HTTP Mensaje Descripción
400 “Either asset_url or asset_file must be provided.” No se proporcionó ningún parámetro de activo en la solicitud.
400 “Both asset_url and asset_file cannot be provided. Please provide only one.” Se proporcionaron ambos parámetros de activo; solo se permite uno.
403 “Media Library Public APIs are not enabled for this company.” La característica de biblioteca de medios no está habilitada para este espacio de trabajo.

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.

Código de error Estado HTTP Descripción
UNSUPPORTED_FILE_TYPE 400 El tipo de archivo cargado no es compatible. El objeto meta incluye el file_type que fue rechazado.
ASSET_SIZE_EXCEEDS_LIMIT 400 El archivo supera el tamaño máximo permitido. Las imágenes tienen un límite de 5 MB.
MEDIA_LIBRARY_LIMIT_REACHED 400 El espacio de trabajo ha alcanzado su número máximo de activos (200 de forma predeterminada para las empresas con versión de prueba gratuita, ilimitado en los demás casos). El objeto meta incluye el limit actual.
ASSET_UPLOAD_FAILED 400 El activo no se pudo cargar debido a problemas de procesamiento.
ZIP_UPLOAD_ERROR 400 El archivo ZIP está dañado o no se puede abrir. El objeto meta incluye el mensaje original_error.
ZIP_FILE_TOO_LARGE 400 El tamaño total sin comprimir del archivo ZIP supera el límite de 5 MB. El objeto meta incluye el zip_file_name y el zip_file_size.
ZIPPED_ENTITY_HAS_NO_NAME 400 Una entrada de archivo dentro del ZIP no tiene nombre. Asegúrate de que el archivo ZIP no esté dañado y añade un nombre a cualquier entrada de archivo sin nombre.
ZIPPED_ENTITY_CANNOT_HAVE_NESTED_DIRECTORY 400 El archivo ZIP contiene directorios anidados, que no son compatibles. Todos los archivos deben estar en el nivel raíz del ZIP.
GENERIC_ERROR 500 Se produjo un error inesperado durante la carga. El objeto meta incluye el mensaje original_error para la depuración. Vuelve a intentarlo o ponte en contacto con Soporte.

Respuesta

Hay cinco respuestas de código de estado para este punto de conexión: 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
}
New Stuff!