레퍼런스 이미지 기반 이미지 생성 API: POST /v1/images

Sume에서 레퍼런스 이미지로 이미지를 생성하려면 model, prompt, 그리고 공개 HTTPS 이미지 URL을 담은 input_references 배열을 넣어 POST /v1/images를 보내세요. 카탈로그 모델 id로 패밀리를 고르거나, model: "sume/auto"를 보내 Image Router가 고르게 하세요. 호출은 최대 30초까지 기다리며, 대부분의 카탈로그 모델은 그 시간 안에 끝납니다.

아래 내용은 모두 Image API 문서 (영문)에서 가져왔고, Image 1.0 페이지 (영문)의 내용을 일부 덧붙였습니다.

레퍼런스 이미지는 어떻게 보내나요?

각 이미지를 타입이 image_url인 input_references 항목으로 추가하세요. 다음은 문서의 image-to-image 예제를 cURL 호출로 옮긴 것입니다.

• 레퍼런스 URL은 공개 HTTPS여야 합니다. localhost, 사설 네트워크, HTTPS가 아닌 URL은 제출 전에 거부됩니다.
• input_references 디스크립터가 {"min": 0, "max": 0}인 모델은 text-to-image 전용이며 레퍼런스를 거부합니다.
• 편집이나 image-to-image 호출에서는 레퍼런스에 맞추도록 aspect_ratio: "auto"를 쓰는 편이 좋습니다. 필드를 생략하는 것은 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",
    "prompt": "make this scene look like a watercolor painting",
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
    ]
  }'

모델은 레퍼런스 이미지를 몇 장까지 받나요?

모델마다 다르며, 호출하기 전에 카탈로그에서 확인할 수 있습니다. GET /v1/images/models는 모델별 supported_parameters를 나열하고, GET /v1/images/models/{model_id}/endpoints는 확정된 파라미터 집합과 pricing을 반환합니다. 파라미터에는 타입이 있는 디스크립터가 붙습니다. enum(허용 목록), range(최솟값과 최댓값 사이의 정수), boolean입니다. 모델이 나열하지 않은 파라미터를 설정한 요청은 조용히 무시되지 않고 400 unsupported_parameter로 거부됩니다.

문서의 예를 하나 들면, ChatGPT Image 2.5(openai/gpt-image-2.5와 openai/gpt-image-2.5-sunburst)는 text-to-image, 최대 16개의 이미지 레퍼런스, 선택적 mask_url, background: auto|transparent|opaque를 지원합니다. 현재 투명 배경 스틸이 필요하면 문서는 transparency: true를 쓴 Image 1.0을 안내합니다.

어떤 필드를 보낼 수 있나요?

모델을 고정해야 하나요, sume/auto를 보내야 하나요?

sume/auto는 Sume 전용 값입니다. Sume가 패밀리를 고르고, 어느 패밀리가 실행됐는지는 공개하지 않습니다. sume/auto는 GET /v1/images/models에 나오지 않으며, 응답의 model과 job.model 모두 sume/auto로 남습니다. gpt-image-2, nano-banana-2 같은 접두어 없는 Image Router id는 대응하는 org/slug id의 별칭으로 받습니다.

Image 1.0 (영문)은 곧 은퇴하며, 그 URL은 같은 Auto 파이프의 호환 별칭으로 남습니다. Image 1.0에서는 레퍼런스를 image_urls(공개 HTTPS URL 1–10개)에 넣습니다. 옮기는 방법은 Video 1.0·Image 1.0에서 sume/auto로 옮기기에서 다룹니다.

무엇이 반환되고, 오래 걸리면 어떻게 되나요?

완료된 호출은 200과 함께 data[].url과 usage.cost를 반환합니다. data[].url은 인라인 base64가 아니라 Sume가 호스팅하는 서명된 URL이고, usage.cost는 지갑에 청구된 USD 금액입니다. v1에서 토큰 수는 항상 0입니다.

30초 예산이 끝난 시점에 이미지가 아직 생성 중이거나, mode: "async"를 보내거나 webhook_url과 함께 mode: "webhook"을 보내면 Sume는 표준 Job 봉투와 함께 202를 반환합니다. GET /v1/jobs/{id}/status를 폴링한 뒤 GET /v1/jobs/{id}/result를 가져오세요. 본문 형태가 아니라 상태 코드로 분기하세요. 4K, 높은 quality, 큰 n 같은 느린 설정일수록 202를 반환할 가능성이 큽니다.

Image API가 아직 지원하지 않는 것은 무엇인가요?

문서에 나온 v1의 미지원 항목은 다음과 같습니다.

• 스트리밍. stream: true는 400 streaming_not_supported를 반환합니다. 진행 상황이 필요하면 mode: "async"로 제출하고 GET /v1/jobs/:id/events를 읽으세요. mode: "subscribe"는 진행 스트림이 아니라 sync의 별칭입니다.
• seed, output_compression, 명시적 픽셀 size. 스키마에는 있지만 이를 지원한다고 밝힌 모델이 없어 각각 400 unsupported_parameter를 반환합니다.
• 프로바이더 선택. provider.options는 생략하거나 비워야 하고, only와 order는 "sume"만 받으며, 그 밖의 slug는 400 provider_not_available을 반환합니다.

이미지 생성 비용은 어떻게 청구되나요?

과금은 전부 아니면 전무 방식입니다. 완료된 생성은 엔드포인트 요금대로 전액 청구됩니다. 실패하거나 취소된 생성은 청구되지 않으며, 실패한 요청은 502 Bad Gateway를 반환합니다. 클라이언트가 일찍 연결을 끊으면 실패한 생성과 똑같이 과금되며, 이는 전혀 청구되지 않는다는 뜻입니다. 엔드포인트의 pricing 항목에는 이미 Sume 마진이 포함되어 있어 cost_usd × n이 실제로 내는 금액입니다. 현재 요율은 API 요금에 있습니다.