Text to Image API: 프롬프트 보내고 이미지 URL 받기

Text-to-image API는 HTTPS 요청으로 텍스트 프롬프트를 받아 생성된 이미지를 반환하는 웹 엔드포인트입니다. Sume에서는 model과 prompt를 담아 POST https://api.sume.com/v1/images를 보내고, API 키는 Bearer 토큰으로 보냅니다. 호출은 최대 30초까지 기다렸다가 완성된 이미지 링크와 함께 200을 반환하고, 그보다 오래 걸리면 폴링할 Job과 함께 202를 반환합니다.

아래 내용은 Sume의 Image API (영문), Job과 결과 (영문), 인증 문서에서 가져왔으며, 2026-09-28에 확인했습니다. 같은 호출을 Python으로 하고 파일을 디스크에 저장하는 방법은 Python 이미지 생성 API에 있습니다.

Text-to-image API는 어떻게 호출하나요?

API 키(API keys) 페이지에서 키를 만들어 서버 쪽 환경 변수에 두고, 요청을 하나 보내세요. 아래 요청은 문서에 있는 cURL 예제 그대로입니다.

• model로 모델을 고릅니다. GET /v1/images/models에 나오는 id를 넣거나, Sume가 고르게 하려면 sume/auto를 넣으세요. Sume는 Auto 요청에서 어느 패밀리가 실행됐는지 공개하지 않습니다.
• prompt는 이미지를 설명합니다. 필수 필드는 model과 prompt뿐이며, 그 밖의 생성 파라미터는 모델이 나열한 것이어야 합니다. 그렇지 않으면 호출이 400 unsupported_parameter로 실패합니다. 대신 사진에서 시작하려면 input_references를 추가하세요. 이 방식이 Image to Image AI입니다.
• 키는 Authorization: Bearer나 x-api-key 중 하나로만 보내고, 둘 다 보내지 마세요. 둘 다 실은 요청은 401 unauthorized로 거부됩니다.
• 문서는 프론트엔드 JavaScript나 모바일 앱에 API 키를 넣지 말라고 하므로, API는 백엔드에서 호출하세요.

curl -X POST "https://api.sume.com/v1/images" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance-seed/seedream-4.5",
    "prompt": "a red panda astronaut floating in space, studio lighting"
  }'

API는 무엇을 반환하나요?

완료된 호출은 인라인 base64가 아니라 Sume가 호스팅하는 이미지 URL과 함께 200을 반환하며, 형태는 아래와 같습니다. 문서의 예제에서 청구 금액만 뺀 것입니다.

• data[].url 링크는 서명된 URL이므로 보관할 파일은 다운로드하세요. media_type은 각 파일의 형식을 알려 줍니다.
• usage.cost는 지갑에 청구된 USD 금액입니다. 이미지 모델은 이미지 단위로 계량되므로 토큰 수는 항상 0입니다.
• model은 보낸 id를 그대로 돌려주므로, sume/auto는 sume/auto로 남습니다.

{
  "created": 1748372400,
  "model": "bytedance-seed/seedream-4.5",
  "data": [
    { "url": "https://media.sume.com/img/01J.../0.png", "media_type": "image/png" }
  ],
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "cost": … }
}

이미지 생성이 30초를 넘기면 어떻게 되나요?

그러면 같은 호출이 이미지 대신 Job 봉투와 함께 202를 반환하므로, 본문 형태가 아니라 상태 코드를 확인하세요. Job이 completed, failed, canceled 중 하나가 될 때까지 GET /v1/jobs/{id}/status를 폴링하고, 완료된 Job에서만 GET /v1/jobs/{id}/result를 읽으세요. 이 루프는 Python 이미지 생성 API에 나와 있습니다. 4K, 높은 quality, 큰 n은 202로 끝날 가능성이 가장 큰 설정입니다.

기다리지 않으려면 mode: "async"를 보내세요. 폴링 대신 통보를 받으려면 공개 HTTPS webhook_url과 함께 mode: "webhook"을 보내세요. Sume는 종료 이벤트인 job.completed, job.failed, job.canceled 중 하나를 진행 이벤트 없이 보내고, 받는 쪽에서 검증 (영문)할 수 있도록 서명합니다. 문서는 백업으로 폴링을 유지하라고 안내합니다. 전체 흐름은 다음과 같습니다.

Text-to-image API 비용은 얼마인가요?

Sume에서 이미지 호출은 이미지 단위로 과금됩니다. 모델의 엔드포인트 레코드에는 출력 이미지당 cost_usd를 담은 pricing 항목이 있고, 이 값에는 Sume 마진이 이미 포함되어 있으며, 여기에 기본 5.5% 에이전트 수수료가 더해집니다. ChatGPT Image 2.5에서는 이미지당 가격을 토큰으로 추정하므로, 요청마다 크기와 품질에 따라 가격이 달라집니다. 응답의 usage.cost는 청구된 USD 금액이며, 실패하거나 취소된 생성은 과금되지 않습니다. 모델별 가격은 AI 이미지 생성 API 비용에 있습니다.

Sume의 text-to-image API로 할 수 없는 것은 무엇인가요?

Text-to-image API를 호출할 때 가장 먼저 부딪히는 빈틈은 두 가지입니다. Image API가 아직 제공하지 않는 다른 필드는 레퍼런스 이미지 기반 이미지 생성 API에서 다룹니다.

• 부분 이미지 스트리밍: stream: true는 400 streaming_not_supported를 반환합니다. seed를 보내면 400 unsupported_parameter가 반환됩니다.
• SVG: 현재 output_format 값에 svg를 나열하는 모델이 없으므로, png, jpeg, webp처럼 모델이 나열한 형식을 요청하세요.