Skip to main content

Image Upload and Product Creation

To create a product, you must first upload images. Gency uses the Presigned URL method, in which the client uploads images directly to S3.

Overall Flow​

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

Step 1. Issue Upload URL​

Issue an upload URL for each image. If a product has 3 images, call this API 3 times.

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=..."
  }
}

Important: The uploadUrl is valid only for 1 hour after issuance. You must complete the upload within 1 hour. Uploaded images are retained for 24 hours, and must be used for product creation within 24 hours. If the time is exceeded, the image may be deleted.

Step 2. Upload the Image to S3​

Send a PUT request to the issued uploadUrl to upload the image directly. This request is sent directly to S3, not to the Gency API.

curl -X PUT "{uploadUrl}" \
  -H "Content-Type: image/png" \
  --data-binary @my-product-image.png
  • The Content-Type must match the actual MIME type of the image being uploaded (image/png, image/jpeg, etc.).
  • On success, HTTP 200 OK is returned.

Step 3. Create the Product​

Include the uploaded imageId in the images array of the product creation API and call it.

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": ["드라이클리닝 권장"]
        }
      }
    ]
  }'
  • The first image in the images array is used as the representative image.
  • If you put multiple entries in the metadata array, you can create multiple products in a single request.
  • Credits are deducted when a product is created.

Cautions​

  • A Presigned URL is single-use, and you must upload within 1 hour after issuance.
  • Uploaded images are retained for 24 hours. They must be used for product creation within 24 hours, and may be deleted if exceeded.
  • Supported image formats: png, jpg, jpeg, webp