본문으로 건너뛰기

Seedream 5.5

텍스트와 참조 이미지로 이미지를 생성하고 편집하기

요청 필드와 허용 값, 동기와 비동기 호출의 선택, 참조 이미지와 출력 크기, 레이어 분해 조건과 비용 확인 방법을 설명합니다.

페이지 목차

지원 기능

Seedream 5.5로 할 수 있는 일과 보낼 입력은 다음과 같습니다.

하려는 일입력확인할 절
새 이미지 생성prompt요청 예시
참조 이미지 편집prompt와 image요청 예시
이미지를 투명 레이어로 분해prompt, 이미지 한 장과 layer_decomposition: true레이어 분해하기

새 이미지 생성과 참조 이미지 편집은 동기 호출과 비동기 호출을 모두 지원하고, 레이어 분해는 비동기 호출만 지원합니다. Seedream 5.5는 작업 ID를 반환하는 모델이므로 동기로 호출해도 응답에 작업 ID가 들어 있고, 같은 ID로 결과를 다시 조회할 수 있습니다.

모델 코드와 엔드포인트

항목값
모델 코드seedream-5.5
생성과 편집Image Generations POST /v1/images/generations, JSON 본문
결과 형식이미지 URL과 렛서 작업 ID id

이 모델의 요청 필드와 응답 형식은 같은 엔드포인트를 쓰는 다른 모델과 다르므로, 이 가이드의 요청 필드와 허용 값을 따릅니다. 응답 필드, 비동기 접수 헤더와 웹훅이 동작하는 방식은 Image Generations의 이미지 URL과 작업 ID 응답에 있습니다.

AI 게이트웨이 API 키를 준비하고, 현재 스페이스의 모델 이용 가능 여부와 단가를 확인하세요. 다른 이미지 모델과 영상 모델의 결과 반환 방식은 이미지와 영상 만들기의 동기 호출과 비동기 호출에서 확인합니다.

동기 호출과 비동기 호출

두 방식의 요청 본문은 같고, 비동기는 Prefer: respond-async 헤더로 선택합니다.

구분동기비동기
사용할 때한 장을 생성하고 바로 받을 때요청이 많거나 연결을 오래 유지하기 어려울 때, 레이어를 분해할 때
응답생성이 끝나면 이미지 URL과 작업 ID 반환작업 접수 후 작업 ID 반환
결과 확인응답의 data[].url. 같은 작업 ID로 Jobs에서 다시 조회 가능Jobs 조회 또는 웹훅
레이어 분해지원하지 않음지원
분당 이미지 한도 도달HTTP 429대기열에서 처리 대기. 대기열도 가득 차면 HTTP 429

두 방식의 가격은 같습니다. 동기 호출에서는 생성이 끝날 때까지 연결이 유지됩니다.

동기 호출에서는 클라이언트의 응답 대기 시간을 60초 이상으로 설정하세요

처리 시간은 요청에 따라 달라집니다. 연결을 오래 유지하기 어렵다면 비동기를 선택하세요.

요청 필드와 허용 값

요청 본문은 application/json 형식이며, model과 prompt는 필수입니다. 표에 없는 필드를 보내면 요청이 HTTP 400으로 거절됩니다.

필드타입요구 여부허용 값과 기본값설명
modelstring필수seedream-5.5호출할 모델 코드
promptstring필수비어 있지 않은 텍스트생성 또는 편집 지시
imagestring 또는 array편집과 레이어 분해에서 필수URL 하나 또는 10개 이하의 URL 목록. 레이어 분해에서는 정확히 1장참조 이미지
sizestring선택1K, 1.5K, 2K 또는 WIDTHxHEIGHT. 기본 2K. 레이어 분해에서는 auto(기본)도 지원출력 크기. 범위는 제한과 사용량 참고
output_formatstring선택png(기본), jpeg출력 이미지의 형식
backgroundstring선택auto, transparent, opaque. 생략하면 공급사 기본값배경. 레이어 분해와 함께 보내지 않음
watermarkboolean선택true 또는 false. 생략하면 공급사 기본값워터마크 포함 여부. 워터마크가 필요 없으면 false를 명시
optimize_prompt_options.modestring선택standard만 지원프롬프트 최적화 모드
safety_identifier 또는 userstring선택64자 이하최종 사용자 식별자. 둘 다 보내면 safety_identifier 사용
ninteger선택1만 지원. 기본 1생성할 이미지 수
response_formatstring선택url만 지원. 기본 url. b64_json은 거절결과 반환 형식
layer_decompositionboolean선택true 또는 false(기본)true이면 비동기 레이어 분해. 레이어 분해하기 참고
layer_decomposition_optionsobject선택아래 표 참고레이어 분해 옵션

점으로 연결한 필드 이름은 중첩 객체 안의 필드를 나타냅니다. 예를 들어 optimize_prompt_options.mode는 "optimize_prompt_options": {"mode": "standard"}로 보냅니다. layer_decomposition_options도 중첩 객체이며, 그 필드는 아래 표에 있습니다.

layer_decomposition_options의 필드타입요구 여부허용 값과 기본값설명
max_imagesinteger선택2~100. 기본 30레이어 수 상한. 실제로 반환되는 레이어 수는 더 적을 수 있음
text_recognitionboolean선택true 또는 false레이어 안의 글자를 인식할지 여부

요청 예시

아래 예제는 환경 변수 LETSUR_API_KEY를 사용해 1K 이미지를 동기로 생성합니다. 키 설정 방법은 첫 API 호출에서 확인하세요.

cURL
curl https://gw.letsur.ai/v1/images/generations \ --max-time 120 \ -H "Authorization: Bearer $LETSUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "seedream-5.5", "prompt": "A red apple on a wooden table, soft morning light", "size": "1K", "watermark": false }'

HTTP 200 응답의 data[].url에서 이미지를 다운로드합니다. 이 URL을 받았다고 해서 렛서가 파일 보관을 마친 것은 아니므로, 필요한 이미지는 다운로드해 보관하세요. 아래는 응답 형식을 보여 주는 예시이며, ID와 URL은 설명용 값입니다.

{ "id": "lst-example-image-job-id", "model": "seedream-5.5", "created": 1794212764, "data": [ { "url": "https://gw.letsur.ai/v1/media/example-media-id?exp=...&sig=...", "size": "1248x832", "output_format": "png", "background": "opaque" } ], "usage": {"input_images": 0, "generated_images": 1, "output_tokens": 4056, "total_tokens": 4056}, "estimated_cost": null }

이 모델의 응답에는 공통 필드 외에 data[].output_format, data[].background와 공급사가 보고한 생성 정보 usage가 들어 있습니다. usage는 차감 비용이 아닙니다. 비용은 제한과 사용량에서 확인합니다.

이미지를 편집하려면 요청 본문을 다음과 같이 바꿉니다. image의 URL은 실제 참조 이미지 주소로 바꾸세요. 참조 이미지의 URL은 프롬프트에 작성하지 않고 image에 지정합니다.

{ "model": "seedream-5.5", "prompt": "Make the apple green, keep everything else the same", "image": "https://example.com/apple.png", "size": "1K" }

고유 기능

레이어 분해하기

Seedream 5.5는 참조 이미지 한 장을 여러 투명 레이어로 분해할 수 있습니다. 요청 예시의 본문을 다음으로 바꾸고 -H "Prefer: respond-async"를 추가합니다. 이 헤더 없이 보내면 요청이 HTTP 400으로 거절됩니다.

{ "model": "seedream-5.5", "prompt": "Split this image into layers", "image": "https://example.com/poster.png", "layer_decomposition": true, "layer_decomposition_options": {"max_images": 30} }
  • 참조 이미지 한 장

    image에 정확히 한 장을 지정하고 background는 보내지 않습니다.

  • 레이어 수와 사용량

    max_images는 출력 레이어 수의 상한입니다. 과금은 실제 반환된 레이어 수를 기준으로 합니다. 분당 이미지 한도는 max_images만큼 미리 사용됩니다.

작업 상태와 파일 준비 상태를 확인한 뒤, Jobs 응답의 data.job.result.media[].metadata에서 레이어 정보를 읽습니다. 웹훅 알림에는 이미지별 metadata가 없으므로 알림을 받은 뒤에도 Jobs를 조회합니다. 레이어는 배열 순서가 아니라 z_index를 기준으로 정렬해 쌓습니다. 공급사가 반환하지 않은 필드는 응답에서 생략될 수 있습니다.

필드설명
size출력 크기. WIDTHxHEIGHT
output_format출력 형식. png 또는 jpeg
background배경 정보. 레이어는 transparent
z_index레이어를 쌓는 순서
bounding_box.absolute원본 기준 픽셀 좌표 [x1, y1, x2, y2]
bounding_box.normalized같은 상자를 0~1000 기준으로 표현한 좌표
name, description레이어 이름과 설명
text_recognition글자 인식을 요청했을 때의 인식 결과

제한과 사용량

일반 생성에서 출력 크기와 형식은 다음 조건을 따릅니다.

확인할 항목일반 생성 조건
기본 출력2K, png, 요청당 한 장
크기 선택1K, 1.5K, 2K 또는 픽셀 단위 WIDTHxHEIGHT
직접 지정한 크기의 총 픽셀 수921,600~4,624,220픽셀
직접 지정한 크기의 가로세로 비율1:16~16:1
지원하지 않는 값일반 생성의 size: "auto", sequential_image_generation, tools, stream

예제의 1K와 기본값 2K는 가격 구간이 다를 수 있습니다. 크기를 명시하고 현재 단가를 확인하세요.

  • 입력 비용: 참조 이미지가 비용에 반영됩니다.
  • 출력 비용: 실제 출력 이미지 수를 기준으로 계산합니다. 레이어 분해의 max_images는 수량 상한입니다.
실제 차감 비용은 Jobs에서 확인합니다

동기로 호출해도 실제 차감 비용은 Jobs의 data.job.usage에 있습니다. estimated_cost: null은 예상 비용을 제공하지 않는다는 뜻이며, 무료라는 뜻이 아닙니다.

Jobs의 data.job.usage.items는 이미지 장 수를 세는 다음 항목으로 나뉠 수 있습니다.

items[].unit항목
input_image참조 이미지
output_image출력 이미지
output_image_large큰 크기의 출력 이미지

이때 quantity는 장 수이고 unit_price는 장당 단가입니다. 수량이 0인 항목은 빠집니다. 장 단위로 나눌 수 없으면 unit 없이 항목 하나로 반환될 수 있습니다. 어느 경우든 작업 비용은 amount입니다.

비용을 기록할 값과 식별자는 요청별 비용에서 확인합니다.

결과 받기

비동기 접수를 확인하고, 작업 ID로 상태를 조회해 결과 파일을 받고, 웹훅 알림을 받는 순서는 모델과 관계없이 같습니다. 생성 요청하고 결과 파일 받기를 따르세요. 이 모델의 작업은 약 3초 간격으로 조회합니다. 작업 조회로 받은 다운로드 URL은 약 1시간 동안 유효합니다. 레이어 분해 결과를 받은 뒤에는 레이어 분해하기의 필드를 읽습니다.

문제 해결

HTTP 오류가 나면 응답의 error.code와 error.message를, 접수한 작업이 실패하면 Jobs의 data.job.error.type을 확인합니다. 코드별 뜻과 다음 행동은 Image Generations의 작업 ID를 반환하는 모델의 오류와 작업 실패 사유에 있습니다. 이 모델에서 자주 만나는 경우는 다음과 같습니다.

증상다음 행동
HTTP 400 validation_error요청 필드와 허용 값에 없는 필드나 값을 보냈는지, 레이어 분해에 Prefer: respond-async를 보냈는지 확인합니다
동기 호출에서 HTTP 429 queue_full분당 이미지 한도에 도달했을 수 있습니다. Retry-After초 뒤 다시 보내고, 자주 닿으면 비동기로 호출합니다
작업 오류 urn:letsur:error:vendor_rejected콘텐츠 심사를 포함한 공급사의 거절입니다. 프롬프트나 참조 이미지를 수정합니다
동기 호출에서 게이트웨이의 오류 응답 없이 클라이언트 timeout이 나거나 응답을 받지 못함원래 요청은 처리됐을 수 있고, 다시 보내면 별도 호출로 처리될 수 있습니다. 다시 보낼지는 동기 호출의 재시도 기준에 따라 판단합니다

인증과 한도 등 공통 오류는 오류 처리를 참고하세요.