미디어 라이브러리에 자산 업로드
/media_library/create
이 엔드포인트를 사용하면 외부에서 호스팅되는 URL(
asset_url) 또는 요청 본문에 담아 보내는 바이너리 파일 데이터(asset_file)를 사용하여 Braze 미디어 라이브러리에 자산을 추가할 수 있습니다. 이 엔드포인트는 이미지, 문서 및 이러한 파일이 포함된 ZIP 파일을 지원합니다. 전체 목록은 지원되는 파일 유형을 참조하세요.
지원되는 파일 유형
이 엔드포인트는 asset_url과 asset_file 중 어느 방식으로 업로드하든 다음 파일 유형을 허용합니다.
| 자산 유형 | 지원되는 파일 유형 | 최대 크기 |
|---|---|---|
| 이미지 | GIF, ICO, JPEG, JPG, PNG, WebP | 5 MB |
| 벡터 이미지 | SVG | 5 MB |
| 문서 | DOC, DOCX, PDF, PPT, PPTX, XLS, XLSX | 5 MB |
| 아카이브 | ZIP | 총 50 MB, ZIP 내 파일당 5 MB |
여기에 나열되지 않은 파일 유형을 업로드하면 엔드포인트가 UNSUPPORTED_FILE_TYPE 오류를 반환합니다.
ZIP 파일의 경우 아카이브 내의 각 파일도 여기에 나열된 지원 파일 유형 중 하나여야 하며, 모든 파일은 ZIP 파일의 루트에 있어야 합니다(하위 디렉토리 불가). 지원되지 않는 파일은 건너뛰고 응답의 errors 배열로 반환되며, 아카이브의 나머지 파일은 그대로 업로드됩니다.

가상 연락처 파일(.vcf)과 비디오 파일도 미디어 라이브러리에 업로드할 수 있지만, 이 API 엔드포인트가 아닌 대시보드 UI(콘텐츠 > 미디어 라이브러리)를 통해서만 가능합니다.

Braze MCP 서버에서 create_media_library_asset 함수를 사용하여 이 엔드포인트를 호출할 수도 있습니다. 이렇게 하면 Claude나 Cursor 같은 인공지능 도구가 자연어 프롬프트만으로 미디어 라이브러리에 자산을 업로드할 수 있습니다.
필수 조건
이 엔드포인트를 사용하려면 media_library.create 권한이 있는 API 키가 필요합니다.
사용량 제한
이 엔드포인트에는 API 사용량 제한에 명시된 대로 시간당 100건의 요청이라는 사용량 제한이 적용됩니다.
요청 본문
asset_url을 포함하면 엔드포인트가 해당 URL에서 파일을 다운로드합니다. asset_file을 포함하면 엔드포인트가 요청 본문의 바이너리 데이터를 사용합니다.
asset_url의 요청 본문 예시:
{
"asset_url": "https://cdn.example.com/assets/cat.jpg",
"name": "Cat Graphic"
}
asset_file의 요청 본문 예시:
{
"asset_file": <BINARY FILE DATA>,
"name": "Cat Graphic"
}
요청 본문에는 다음 매개변수가 포함됩니다.
| 매개변수 | 필수 | 데이터 유형 | 설명 |
|---|---|---|---|
asset_url |
선택 사항 | 문자열 | Braze에 업로드할 자산의 공개적으로 접근 가능한 URL입니다. |
asset_file |
선택 사항 | 바이너리 | 바이너리 파일 데이터입니다. |
name |
선택 사항 | 문자열 | 미디어 라이브러리에서 이 자산에 표시될 이름입니다. |

asset_url과 asset_file은 함께 사용할 수 없으므로 API 요청에 둘 중 하나만 포함해야 합니다.
업로드된 파일 이름
이 섹션에서는 name 매개변수 포함 여부에 따라 엔드포인트가 업로드된 파일에 이름을 지정하는 방식을 설명합니다.
단일 파일 업로드
| 시나리오 | 결과 |
|---|---|
name 제공 |
name 값이 미디어 라이브러리의 자산 이름으로 사용됩니다. |
name 제외 |
URL 또는 업로드된 파일의 원래 파일 이름이 사용됩니다. |
ZIP 파일 업로드
| 시나리오 | 결과 |
|---|---|
name 제공 |
name 값이 접두사로 사용되고, 뒤에 증가하는 숫자가 접미사로 붙습니다(예: “My File 1”, “My File 2”, “My File 3”). |
name 제외 |
각 파일은 ZIP 파일 내의 원래 파일 이름을 유지합니다. |
요청 예시
이 섹션에는 URL을 사용하여 자산을 추가하는 요청과 바이너리 파일 데이터를 사용하는 요청, 두 가지 curl 요청 예시가 포함되어 있습니다.
다음은 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"}'
다음은 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"}'
오류 응답
이 섹션에서는 발생할 수 있는 오류와 해당 메시지 및 설명을 안내합니다.
유효성 검사 오류
유효성 검사 오류는 다음과 같은 구조로 반환됩니다.
{
"message": (String) Human-readable error description
}
다음 표에는 발생할 수 있는 유효성 검사 오류가 나와 있습니다.
| HTTP 상태 | 메시지 | 설명 |
|---|---|---|
| 400 | “Either asset_url or asset_file must be provided.” | 요청에 자산 매개변수가 제공되지 않았습니다. |
| 400 | “Both asset_url and asset_file cannot be provided. Please provide only one.” | 두 자산 매개변수가 모두 제공되었습니다. 하나만 허용됩니다. |
| 403 | “Media Library Public APIs are not enabled for this company.” | 이 워크스페이스에서 미디어 라이브러리 기능이 활성화되어 있지 않습니다. |
처리 오류
처리 오류는 오류 코드가 포함된 다른 형식의 응답을 반환합니다.
{
"message": (String) Human-readable error description,
"error_code": (String) error code,
"meta": { }
}
다음 표에는 발생할 수 있는 처리 오류가 나와 있습니다.
| 오류 코드 | HTTP 상태 | 설명 |
|---|---|---|
UNSUPPORTED_FILE_TYPE |
400 | 업로드된 파일 유형이 지원되지 않습니다. 지원되는 파일 유형을 참조하세요. meta 오브젝트에는 거부된 file_type이 포함됩니다. |
ASSET_SIZE_EXCEEDS_LIMIT |
400 | 파일이 허용된 최대 크기인 5 MB를 초과합니다. |
MEDIA_LIBRARY_LIMIT_REACHED |
400 | 워크스페이스가 최대 자산 수에 도달했습니다(무료 평가판 회사는 기본값 200개, 그 외에는 무제한). meta 오브젝트에는 현재 limit이 포함됩니다. |
ASSET_UPLOAD_FAILED |
400 | 처리 문제로 인해 자산 업로드에 실패했습니다. |
CORRUPT_FILE |
400 | 이미지 파일이 손상되었거나 디코딩할 수 없습니다. meta 오브젝트에는 file_name이 포함됩니다. |
INVALID_ASSET_URL |
400 | asset_url의 형식이 잘못되었거나 HTTP 또는 HTTPS URL이 아닙니다. meta 오브젝트에는 asset_url이 포함됩니다. |
FAILED_TO_DOWNLOAD_ASSET |
400 | Braze가 asset_url에서 파일을 다운로드하지 못했습니다(예: 호스트를 확인할 수 없거나, 연결에 실패했거나, 원격 서버가 오류를 반환한 경우). meta 오브젝트에는 asset_url과 original_error가 포함됩니다. |
ZIP_UPLOAD_ERROR |
400 | ZIP 파일이 손상되었거나 열 수 없습니다. meta 오브젝트에는 original_error 메시지가 포함됩니다. |
ZIP_FILE_TOO_LARGE |
400 | ZIP 파일의 압축 해제 후 총 크기가 50 MB 제한을 초과합니다. meta 오브젝트에는 zip_file_name과 zip_file_size가 포함됩니다. |
ZIP_TOO_MANY_ENTRIES |
400 | ZIP 파일에 포함된 파일이 너무 많습니다. ZIP 파일에는 허용되는 최대 항목 수가 정해져 있습니다. meta 오브젝트에는 max_entries가 포함됩니다. |
ZIPPED_ENTITY_HAS_NO_NAME |
400 | ZIP 내부의 파일 항목에 이름이 없습니다. ZIP 파일이 손상되지 않았는지 확인하고, 이름이 없는 파일 항목에 이름을 추가하세요. |
ZIPPED_ENTITY_CANNOT_HAVE_NESTED_DIRECTORY |
400 | ZIP 파일에 지원되지 않는 중첩 디렉토리가 포함되어 있습니다. 모든 파일은 ZIP의 루트 수준에 있어야 합니다. |
GENERIC_ERROR |
500 | 업로드 중 예기치 않은 오류가 발생했습니다. meta 오브젝트에는 디버깅용 original_error 메시지가 포함됩니다. 다시 시도하거나 고객지원에 문의하세요. |
응답
이 엔드포인트의 상태 코드 응답은 200, 400, 403, 429, 500 다섯 가지입니다.
다음 JSON은 예상되는 응답 형식을 보여줍니다.
{
"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
}