관리자 API소유자 토큰

이미지 업로드

템플릿 · 상품에 넣을 이미지를 먼저 올리고 file_id 를 받습니다.

업데이트됨 10.26 — 상세설명 · 공통정보 이미지는 가로만 1000 으로 줄입니다

무엇인가요

템플릿 · 상품에 넣을 이미지를 먼저 올리고 file_id 를 받습니다. 받은 file_id 를 이미지 칸에 넣으면 서버가 이 쇼핑몰에 올린 파일 기록에서 저장소 · 경로를 찾아 채웁니다. 관리자 화면의 이미지 올리기와 같습니다(같은 리사이즈 · 같은 저장 한도). 권한은 products:write 입니다.

어디에 넣나	usage	넣는 칸
공통정보 템플릿	`product.template`	`image.file_id`
상품 이미지	`product.image`	`images[].file_id`
주문옵션 이미지	`product.option`	`options[].image.file_id`
카테고리 상단 배너	`category.banner`	`top.banner.pc_image · mobile_image`
상품 배지	`product.decoration`	`image`
상품 아이콘	`product.decoration` + `variant=icon`	`image`
상품정보제공고시 이미지	`product.notice`	`product_info_provided_notice.image.file_id`
상품 상세 설명 속 이미지	`product.detail`	응답의 `url` 을 `detail_content_body` 의 <img src> 에

AI 에이전트는 MCP 도구 upload_images 로도 올립니다 — 로컬 파일의 base64 나 공개 주소를 넣으면 같은 file_id 가 돌아옵니다. → MCP 연결

이미지 업로드

POSThttps://api.mallstory.kr/v1/shop/{shop_unique}/files/images

요청	형식	설명
`files`필수	file	multipart/form-data. 여러 장이면 같은 이름(files)을 반복합니다. 최대 10장 · 장당 50MB
`usage`	string	쿼리 — 무엇에 쓰는가(위 표). 없으면 `product.image`. 크기를 줄이는 기준이 쓰임마다 다릅니다
`variant`	string	쿼리 — `icon` 이면 상품 아이콘 이미지입니다(`usage=product.decoration` 일 때만). 한 장만 받고 SVG 도 받습니다

받는 형식은 JPEG · PNG · GIF · WebP · AVIF · BMP 이고(아이콘은 SVG 도), 쓰임에 맞는 크기로 줄여 저장합니다. 원본보다 키우지는 않습니다.

쓰임	줄이는 기준
`product.option`	가로 · 세로 120 안
`product.decoration`	배지 — 가로 160 을 넘을 때만 가로 160(세로는 비율대로)
`product.decoration` + `variant=icon`	아이콘 — 가로 · 세로 160 안. SVG 는 줄이지 않고 스크립트 · 이벤트 · 바깥 참조를 걷어 내고 저장
`product.detail` · `product.template`	상세설명 · 공통정보 — 가로 1000 을 넘을 때만 가로 1000(세로는 비율대로, 세로로 긴 이미지도 글씨가 뭉개지지 않게)
그 밖	가로 · 세로 1000 안

bash요청

curl -X POST 'https://api.mallstory.kr/v1/shop/{shop_unique}/files/images?usage=product.template' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -F 'files=@notice.png' \
  -F 'files=@banner.jpg'

json201 Created

{
  "items": [
    {
      "file_id": "6acca8a3d6e259e5771dd17b",
      "storage": "1",
      "path": "storages/2026/10/12/58e743fd-099f-40a7-add3-8b2bf0a7259a.png",
      "url": "https://cdn.story.store/storages/2026/10/12/58e743fd-099f-40a7-add3-8b2bf0a7259a.png",
      "name": "notice.png",
      "size": 5758,
      "width": 800,
      "height": 400
    }
  ]
}

응답 필드	형식	설명
`items`	array	올린 차례 그대로
`file_id`	string	이미지 칸에 넣는 값
`url`	string	바로 쓸 수 있는 이미지 주소
`storage`	string	저장소 번호(넣지 않아도 됩니다 — 서버가 채움)
`path`	string	저장소 안 경로(넣지 않아도 됩니다)
`name`	string	원본 파일명
`size`	number	줄인 뒤 크기(바이트)
`width`	number \| null	가로(px)
`height`	number \| null	세로(px)

알아 둘 것

올린 이미지는 템플릿 · 상품에 넣어야 쓰입니다. 어디에도 넣지 않은 이미지는 다음 날 새벽에 지워집니다.
상품 · 템플릿에서 이미지를 빼고 저장하면 그 파일은 바로 지워지고, 상품 · 템플릿을 지우면 그 안의 이미지 파일도 모두 지워집니다.
이미지 칸에는 file_id 만 보냅니다. storage · path 를 보내도 쓰지 않습니다.
다른 쇼핑몰에 올린 file_id 는 넣을 수 없습니다(400).
쇼핑몰 저장 용량을 넘으면 413 입니다. 쓰지 않는 파일을 지운 뒤 다시 올립니다.

상태	code	언제
400	`InvalidParameterValue`	파일이 없거나 이미지가 아님 · 장수 · 크기 초과 · 아이콘이 아닌데 SVG
400	`InvalidImage`	아이콘 SVG 를 읽을 수 없음(걷어 내고 나니 그림이 남지 않음)
413	`StorageQuotaExceeded`	쇼핑몰 저장 용량을 넘음
403	`InsufficientScope`	products:write 가 없음

무엇인가요#

이미지 업로드#

알아 둘 것#

무엇인가요

이미지 업로드

알아 둘 것