여러 제품 사진을 AI 이미지 한 장으로 합치는 API

Sume API로 여러 제품 사진을 AI 이미지 한 장으로 합치려면, POST /v1/formats/sume/sume-editorial-product-set/runs로 카탈로그 Format sume-editorial-product-set를 실행하면서 제품마다 팩샷을 하나씩 첨부하세요. 모델을 직접 고르고 프롬프트도 직접 쓰려면, 같은 사진을 input_references에 담아 그만큼의 레퍼런스를 받는 모델로 POST /v1/images를 보내세요.

아래 내용은 2026-09-27에 확인한 Sume 문서 Format 카탈로그 (영문), Format 호출하기 (영문), 구조화 출력 (영문), Image API (영문) 페이지에서 가져왔습니다. Format의 설명은 카탈로그 항목에서 그대로 인용했습니다.

여러 제품을 이미지 한 장에 담는 카탈로그 Format은 무엇인가요?

sume-editorial-product-set(카탈로그 제목: Sume Editorial Product Set)은 카탈로그의 제품 세트 이미지 Format입니다. 설명은 다음과 같습니다. "Create a finished editorial product-set image featuring a coordinated collection, graphic arrangement, and premium set design. Use when the user asks for skincare routines, collection launches, bundles, gift sets, and multi-SKU campaigns. Not for: animated or motion deliverables."(조화로운 컬렉션, 그래픽 배치, 프리미엄 세트 디자인을 갖춘 완성된 에디토리얼 제품 세트 이미지를 만듭니다. 스킨케어 루틴, 컬렉션 출시, 번들, 기프트 세트, 다중 SKU 캠페인을 요청받았을 때 쓰며, 애니메이션이나 모션 결과물에는 쓰지 않습니다.)

이 설명은 Format이 내세우는 목표로 읽어야 하며, 개별 이미지에 대한 약속이 아닙니다. 호출하기 전에 GET /v1/formats/sume/sume-editorial-product-set로 설명을 받아 볼 수 있습니다. 레시피 본문은 이 응답에 없습니다. 본문은 호출자가 아니라 에이전트에게 전달되기 때문입니다. formats:write가 있는 키라면 어떤 키로든 이 Format을 실행할 수 있으며, 실행과 그 미디어, 지출은 그 키에 귀속됩니다.

제품마다 사진을 한 장씩 어떻게 보내나요?

각 팩샷을 공개 HTTPS image_url을 담은 input_image로 attachments[]에 추가하세요. 실행 하나에 에이전트가 볼 수 있는 이미지를 최대 30장까지 넣을 수 있습니다. filename은 에이전트가 보는 라벨이므로 제품마다 이름을 붙이세요. Sume는 실행을 만들 때 모든 첨부를 가져와 실제 타입과 크기를 확인합니다. 그래서 깨졌거나 비공개인 이미지는 실행이 아니라 생성 요청을 실패시킵니다.

배치는 instruction에 설명하세요. 어떤 제품을 넣을지, 어느 제품을 앞세울지, 어떤 배경일지를 적으면 됩니다. 이 필드는 8000자까지 받으며, 그중 앞의 약 4000자가 프롬프트 텍스트로 실행에 전달됩니다. 보낸 instruction은 Format 본문 뒤에 조합되므로, 둘이 어긋나면 모델은 여러분이 요청한 쪽을 따릅니다.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-editorial-product-set/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gift-set-winter-v1" \
  -d '{
    "instruction": "One gift-set image of the three attached products. Cleanser in front.",
    "attachments": [
      { "type": "input_image", "image_url": "https://example.com/cleanser.png", "filename": "cleanser.png" },
      { "type": "input_image", "image_url": "https://example.com/toner.png", "filename": "toner.png" },
      { "type": "input_image", "image_url": "https://example.com/cream.png", "filename": "cream.png" }
    ],
    "output_schema": {
      "name": "acme/gift-set/v1",
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["hero_image"],
        "properties": { "hero_image": { "$ref": "SumeMediaFile#" } }
      }
    },
    "primary_output_key": "hero_image",
    "generation_spend_cap_usd": 10
  }'

완성된 이미지는 어떻게 받나요?

생성 요청은 실행 영수증과 함께 202로 응답합니다. 상태가 종료될 때까지 GET /v1/format-runs/{run_id}를 폴링하거나, communication.webhook_url을 보내 서명된 format.run.terminal POST를 한 번 받으세요. 위 스키마는 문서 자체의 예시를 빌려 왔습니다. hero_image는 SumeMediaFile#이고, primary_output_key: "hero_image"가 이 값을 영수증의 primary_output_url로 만듭니다. output에 든 모든 URL은 이 실행이 만든 미디어와 대조됩니다. media.sume.com의 미디어 URL은 만료되지 않으며, URL을 가진 사람이면 누구나 접근할 수 있습니다.

실행이 만든 것 중 스키마를 만족하는 것이 없으면 output은 null이고 output_error가 이유를 알려 주며, API에서는 실행이 failed로 끝납니다. 이때도 artifacts[]에는 실행이 만든 모든 것이 나열됩니다. 스키마 규칙은 Sume Format 구조화 출력에서 다룹니다.

사진을 Image API로 바로 보낼 수도 있나요?

네. POST /v1/images는 model, prompt, 그리고 공개 HTTPS 이미지 URL을 담은 input_references 배열을 받으므로, 모델은 직접 고르고 프롬프트도 직접 씁니다. 요청 자체는 레퍼런스 이미지 기반 이미지 생성 API에서 다룹니다.

번들에서 확인할 숫자는 모델이 받는 레퍼런스 수의 상한입니다. GET /v1/images/models에서 모델의 input_references 디스크립터는 범위로 표시되므로, 최댓값이 세트의 모든 제품을 담을 수 있는 모델을 고르세요. 아래 예시에 쓴 ChatGPT Image 2.5(openai/gpt-image-2.5)는 이미지 레퍼런스를 최대 16개까지 받습니다. sume/auto는 이 카탈로그에 나오지 않으므로 확인할 범위도 없습니다.

curl -X POST "https://api.sume.com/v1/images" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2.5",
    "prompt": "The three referenced products arranged together as one gift set",
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://example.com/cleanser.png" } },
      { "type": "image_url", "image_url": { "url": "https://example.com/toner.png" } },
      { "type": "image_url", "image_url": { "url": "https://example.com/cream.png" } }
    ]
  }'

어느 경로를 써야 하나요?

제작 결정을 Format에 저장된 레시피에 맡기려면 Format을, 모델과 프롬프트를 직접 고르려면 Image API를 쓰세요.

어떤 제한이 있나요?

아래 제한은 같은 문서 페이지에서 가져왔습니다.

• 첨부는 JPEG, PNG, WebP, GIF, AVIF 중 하나이며, 이미지당 30 MB, 실행당 500 MB까지입니다. 항목이 너무 많으면 400 invalid_attachment이고, 너무 큰 이미지나 세트는 413 attachment_too_large입니다.
• 첨부 타입은 input_image뿐이며, 이 Format은 모션이 아니라 스틸을 만듭니다.
• generation_spend_cap_usd는 최대 $500이며, null은 $500으로 실행되고 0은 거부됩니다.
• 같은 Idempotency-Key를 다른 이미지 목록과 함께 다시 보내면 409 idempotency_conflict입니다.
• 상품 카탈로그 전체에서 번들마다 이미지를 한 장씩 만들려면, 대량 실행 요청 한 번으로 이 Format의 실행을 최대 100개까지 큐에 넣을 수 있습니다. Sume Format 대량 실행을 참고하세요.