상품 이미지 등록

상품 이미지를 올려 목록·상세·장바구니에 보이게 합니다. 상점 플랫폼과 API 두 방법이 있습니다.

준비

• 권한: 소유자·관리자·스태프 또는 product:rw
• 파일: JPG·PNG·WEBP·AVIF·GIF, 장당 10MB, 상품당 10장까지

1. 상점 플랫폼에서 올리기

상점 플랫폼에서 상점 관리 › 상품 › 상품 등록으로 이동합니다(소유자·관리자·스태프). 수정은 상점 관리 › 상품 › 상품 목록에서 상품을 선택합니다.

1. 이미지 섹션에서 **[이미지 추가]**를 누르거나 파일을 점선 영역에 끌어다 놓습니다. 여러 장을 한 번에 고를 수 있습니다.
2. 순서를 정리합니다. 아래 표의 버튼을 씁니다.
3. 상품을 [등록] 또는 **[저장]**합니다. 파일은 고르는 즉시 올라가지만, 저장해야 상품에 연결됩니다.

첫 번째 이미지가 대표 이미지입니다. 목록·장바구니·주문 내역에 쓰이고, 나머지는 상세에서 함께 보입니다.

완료 기준: 상품 목록의 썸네일과 스토어프론트 목록에 올린 이미지가 보입니다.

2. API로 올리기

상품의 images는 이미지 주소 목록입니다. 파일은 두 단계로 올립니다.

1. POST /v1/uploads로 자리를 받습니다. 응답은 공개 주소 url과 업로드 주소 uploadUrl입니다.
2. uploadUrl에 파일 바이트를 PUT합니다. 끝나면 url을 바로 씁니다.
3. url을 상품의 images에 넣습니다.

curl -X POST https://api.sayren.app/v1/uploads \
  -H "Authorization: Bearer {계정 토큰}" -H "X-Store-Id: {storeId}" -H "Content-Type: application/json" \
  -d '{ "filename": "tshirt-white.jpg", "purpose": "product-image", "size": 284913 }'
# → { "url": "https://cdn.avarlabs.com/s/{storeId}/....jpg", "uploadUrl": "https://..." }

curl -X PUT "{uploadUrl}" -H "Content-Type: image/jpeg" --data-binary @tshirt-white.jpg

• uploadUrl은 1시간 동안 유효하고 한 번 올릴 자리 하나입니다.
• 파일 이름은 확장자만 쓰입니다.
• size를 넣으면 올리기 전에 크기 초과를 알 수 있습니다.

MCP로 올리기

AI 도구에 sayren MCP가 연결돼 있으면 upload_image 도구가 위 두 단계를 대신합니다. 이미지 주소(https)나 파일 내용(base64)을 주면 공개 주소 url을 돌려줍니다. 그다음 url을 상품의 images에 넣습니다. MCP 도구 레퍼런스

sayren MCP로 https://example.com/tshirt-white.jpg 를 올려서 「화이트 티셔츠」 상품의 첫 번째 이미지로 넣어 줘.

images에 넣을 수 있는 주소

• https만 받습니다. http·data:는 400 INVALID_IMAGE_URL입니다.
• 경로에 확장자가 있으면 이미지 형식이어야 합니다(.svg·.mp4는 400 UNSUPPORTED_FILE_TYPE). 확장자 없는 주소는 받습니다.
• 직접 운영하는 이미지 호스트의 주소도 받습니다.
• 첫 번째가 대표이고 상품 요약의 thumbnailUrl입니다. 이미지가 없으면 null입니다.

이미지만 바꿀 때는 PATCH /v1/products/{productId}에 { "images": [...] }를 보냅니다. 준 목록으로 통째로 바꾸고 다른 필드는 그대로 둡니다. 항목 형식과 장수(1~10장)는 등록과 같고, 첫 번째가 대표입니다.

이미 저장된 주소는 위 규칙을 다시 검사하지 않습니다.

3. 화면에 맞게 줄여 받기

POST /v1/uploads로 올린 이미지는 쿼리로 줄이거나 형식을 바꿔 받습니다. 직접 운영하는 호스트의 이미지에는 통하지 않습니다.

https://cdn.avarlabs.com/s/{storeId}/....jpg?w=320&f=webp

범위를 벗어난 값은 무시되고 원본이 옵니다. 쿼리를 붙인 주소는 오래 캐시되므로 너비를 몇 가지로 정해 재사용합니다.

자주 막히는 문제

다음 단계

• 상품·옵션·재고 관리
• Store SDK