圖片上傳與商品建立

若要建立商品，須先上傳圖片。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 小時 內上傳。
• 已上傳的圖片會保留 24 小時。須在 24 小時內用於建立商品，逾時的話圖片可能會被刪除。
• 支援的圖片格式：png、jpg、jpeg、webp