본문으로 건너뛰기

이미지 업로드 및 상품 생성

Gency Open API에서 Presigned URL로 상품 이미지를 S3에 직접 업로드하고, 발급받은 imageId로 상품을 생성하는 3단계 흐름을 예제 요청과 함께 안내합니다.

상품을 생성하려면 먼저 이미지를 업로드해야 합니다. Gency는 Presigned URL 방식을 사용하여 클라이언트가 S3에 직접 이미지를 업로드합니다.

전체 흐름​

1. 업로드 URL 발급  →  2. S3에 이미지 업로드  →  3. 상품 생성 API 호출
   (Gency API)            (S3 직접 업로드)          (imageId 포함)

Step 1. 업로드 URL 발급​

이미지마다 업로드 URL을 발급받습니다. 상품에 이미지가 3장이면 이 API를 3번 호출합니다.

curl -X POST "https://openapi.gency.ai/openapi/v1/images/upload-url" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "01HABC...",
    "extension": "png"
  }'
{
  "data": {
    "imageId": "01HIMG001...",
    "uploadUrl": "https://s3.amazonaws.com/...?X-Amz-Signature=..."
  }
}

중요: uploadUrl은 발급 후 1시간 동안만 유효합니다. 1시간 이내에 업로드를 완료해야 합니다. 업로드된 이미지는 24시간 동안 유지되며, 24시간 이내에 상품 생성에 사용해야 합니다. 시간이 초과되면 이미지가 삭제될 수 있습니다.

Step 2. S3에 이미지 업로드​

발급받은 uploadUrl로 PUT 요청을 보내 이미지를 직접 업로드합니다. 이 요청은 Gency API가 아닌 S3로 직접 보내는 요청입니다.

curl -X PUT "{uploadUrl}" \
  -H "Content-Type: image/png" \
  --data-binary @my-product-image.png
  • Content-Type은 업로드하는 이미지의 실제 MIME 타입과 일치해야 합니다 (image/png, image/jpeg 등).
  • 성공 시 HTTP 200 OK가 반환됩니다.

Step 3. 상품 생성​

업로드 완료된 imageId를 상품 생성 API의 images 배열에 포함하여 호출합니다.

curl -X POST "https://openapi.gency.ai/api/v2/products/fashion" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "masterId": "01HABC...",
    "workspaceId": "01HDEF...",
    "metadata": [
      {
        "category": "OUTER",
        "images": ["01HIMG001...", "01HIMG002..."],
        "projectId": "my-project-01",
        "productName": "겨울 패딩 자켓",
        "colors": ["BLACK", "NAVY"],
        "fabrics": ["POLYESTER", "NYLON"],
        "additionalInfo": {
          "features": ["방풍", "경량"],
          "laundryTips": ["드라이클리닝 권장"]
        }
      }
    ]
  }'
  • images 배열의 첫 번째 이미지가 대표 이미지로 사용됩니다.
  • metadata 배열에 여러 항목을 넣으면 한 번의 요청으로 복수의 상품을 생성할 수 있습니다.
  • 상품 생성 시 크레딧이 차감됩니다.

주의사항​

  • Presigned URL은 1회성이며, 발급 후 1시간 이내에 업로드해야 합니다.
  • 업로드된 이미지는 24시간 동안 유지됩니다. 24시간 이내에 상품 생성에 사용해야 하며, 초과 시 이미지가 삭제될 수 있습니다.
  • 지원 이미지 형식: png, jpg, jpeg, webp