Seedream 5.5

Seedream 5.5는 ByteDance의 이미지 모델입니다. 요청 한 번으로 프롬프트 또는 프롬프트와 참조 이미지 최대 10장으로 이미지 한 장을 만들거나, 이미지 한 장을 배경 베이스 이미지와 투명 레이어로 분리하며 선택적으로 각 텍스트 레이어의 글자도 읽어 냅니다. 요청을 보내고 반환된 태스크 ID를 보관한 뒤 완성된 이미지를 태스크에서 읽어 오세요. 참조 이미지는 URL로 전달합니다.

모델 ID

현재 가격은 모델 페이지에서 확인하세요.

간단한 예제

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-5",
    "prompt": "A ceramic teapot shaped like a sleeping fox on a linen tablecloth, soft morning window light, shallow depth of field. No text.",
    "size": "1K"
  }'

엔드포인트

POST https://api.seedrouter.ai/v1/images/generations

응답은 완성된 이미지가 아니라 태스크({"id": "task_...", "status": "processing"})입니다. 결과는 GET /v1/tasks/{task_id}를 폴링해서 받으세요. API 키는 서버 측 코드에 보관하세요. 참조 이미지와 레이어 분리는 같은 요청의 image로 전달합니다. 이 모델에서는 /v1/images/edits를 사용하지 않으며, 호출하면 400을 반환합니다.

파라미터

이 목록에 없는 필드는 요청을 전달하기 전에 삭제되며, 오류를 일으키거나 출력에 영향을 주지 않습니다. n, stream, seed와 response_format은 사용할 수 없습니다. 요청마다 이미지 한 장을 반환하며 layer_decomposition에서는 최대 max_images장까지 반환합니다. callback_url은 사용할 수 없으니 태스크를 폴링하세요.

출력 크기

3K나 4K 해상도 단계도, 화면비 지정 방식도 없습니다. 2K에서 고정된 16:9 프레임을 원하면 2560x1440을 보내세요. 1K와 1.5K는 비용이 같으며 2K와 261만 픽셀을 초과하는 크기는 더 높은 요금입니다(과금에 영향을 주는 요소 참고).

참조 이미지

편집하려면 이미지 한 장, 조합하려면 여러 장을 전달하고 prompt에 유지할 부분과 바꿀 부분을 설명하세요. "이미지 1의 재킷"처럼 순서로 지칭합니다.

{
  "model": "seedream-5-5",
  "prompt": "Turn this scene into a snowy winter night with warm light from the lighthouse windows, keep the composition",
  "image": "https://example.com/lighthouse.jpg",
  "size": "2560x1440"
}

투명 배경

background: "transparent"를 설정하면 프롬프트만으로도, 참조 이미지로도 배경이 투명한 PNG를 받을 수 있습니다:

{
  "model": "seedream-5-5",
  "prompt": "A glossy red enamel pin shaped like a cherry, product cutout",
  "background": "transparent",
  "output_format": "png",
  "size": "1K"
}

레이어 분리

layer_decomposition: true와 함께 이미지 한 장을 보내세요. 태스크는 배경 베이스 이미지를 먼저 반환하고, 이어서 각 레이어를 투명 PNG로 반환합니다.

{
  "model": "seedream-5-5",
  "image": "https://example.com/poster.jpg",
  "layer_decomposition": true,
  "size": "1K",
  "layer_decomposition_options": { "max_images": 4, "text_recognition": true }
}

각 레이어에는 z_index(배경 베이스 이미지는 0이며, 숫자가 클수록 위에 놓임), background가 포함되며, 모델이 제공하는 경우 name, description과 bounding_box도 포함됩니다. bounding_box.absolute는 배경 베이스 이미지의 픽셀 단위로 표시한 [left, top, right, bottom]입니다. bounding_box.normalized는 같은 경계 상자를 0–1000으로 환산한 값입니다. 레이어 파일은 선택한 해상도 단계로 렌더링되므로 픽셀 크기가 경계 상자와 다를 수 있습니다. 이미지를 다시 구성하려면 각 레이어를 경계 상자 크기에 맞추고, z_index 오름차순으로 배경 베이스 이미지 위에 배치하세요.

해상도 단계는 배경 베이스 이미지와 모든 레이어의 크기를 설정합니다. auto는 입력 이미지에 맞추되 1K보다 작으면 올리고 2K보다 크면 줄입니다.

문자 인식

layer_decomposition_options.text_recognition: true이면 일반 인쇄체 글자가 있는 레이어에 text_recognition도 포함됩니다. 전체 text(줄을 \n으로 연결)와 lines가 있으며, 각 줄에는 개별 bounding_box와 스타일이 다른 텍스트 조각인 runs가 있습니다. 각 조각의 style에는 similar_font_family, foreground_color(#RRGGBB)와 bold, italic, underline, strikethrough, shadow, translucent 속성이 있습니다. 글꼴과 속성은 모델의 추정입니다. 장식 글자나 손글씨는 텍스트를 반환하지 않으며, 분리 요청에 prompt를 보내면 문자 인식이 억제될 수도 있으므로 이 필드는 선택 사항으로 취급하세요.

미디어 입력

각 참조 이미지는 공개 HTTP(S) URL로 전달합니다. Base64 data URI는 받지 않습니다. 파일을 자체 스토리지에 업로드하고 그 URL을 전달하세요. JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC와 HEIF를 지원하며 이미지당 최대 30 MB, 총 픽셀 수 최대 36,000,000이어야 합니다. AVIF와 JP2는 지원하지 않습니다. 입력을 읽지 못한 태스크는 실패하며 과금되지 않습니다.

과금에 영향을 주는 요소

현재 요율은 모델 가격 섹션에서 확인하세요. Seedream 5.5는 픽셀 수에 따른 요금 단계에 따라 출력 이미지당 과금되며 모든 참조 이미지 비용이 추가됩니다:

cost = Σ each returned image's price for its own tier + reference images × reference price

• 낮은 요금 단계는 261만 픽셀 이하(1K와 1.5K)입니다. 이를 초과하면 높은 요금 단계가 적용됩니다.
• 첫 장을 포함해 모든 참조 이미지가 과금됩니다. 레이어 분리는 입력 이미지 한 장에 과금합니다.
• 레이어 분리는 배경 베이스 이미지와 각 레이어에 각각의 크기에 따른 요금 단계를 적용해 과금합니다.
• 태스크 접수 시 예약되는 금액은 최대 결과를 기준으로 합니다. 요청한 요금 단계의 이미지 한 장 또는 레이어 분리의 max_images장(생략 시 30장)이며 auto는 높은 요금 단계로 계산합니다. 이후 실제 반환된 이미지에 대해 과금하고 차액은 해제합니다.

최종 과금액은 계정의 사용 내역에서 확인하세요. 실패한 태스크는 과금되지 않습니다.

출력 스키마

제출하면 태스크가 반환됩니다:

{"id": "task_...", "model": "seedream-5-5", "status": "processing", "created_at": 1794323757}

태스크 조회

GET https://api.seedrouter.ai/v1/tasks/{task_id}

status가 completed 또는 failed가 될 때까지 10~20초마다 폴링하세요. 폴링 중 네트워크 타임아웃이 났다고 생성이 실패한 것은 아닙니다. 태스크 ID를 보관하고 다시 확인하세요. 진행 상황을 보려고 태스크를 새로 만들지 마세요.

완료된 태스크

{
  "id": "task_...",
  "model": "seedream-5-5",
  "status": "completed",
  "created_at": 1794323757,
  "finished_at": 1794323804,
  "output": {
    "data": [
      {
        "url": "https://static.seedrouter.ai/media/tasks/task_example/0.png",
        "size": "1248x832",
        "output_format": "png",
        "background": "opaque"
      }
    ]
  }
}

레이어 분리 태스크는 배경 베이스 이미지에 이어 각 레이어를 나열합니다. 다음은 문자 인식을 켜고 실제 포스터를 분리한 결과로, 배경 베이스 이미지와 레이어 세 개 중 첫 번째를 보여 줍니다:

{
  "data": [
    { "url": "https://static.seedrouter.ai/media/tasks/task_example/0.png", "size": "836x1254", "output_format": "png", "background": "opaque", "z_index": 0 },
    {
      "url": "https://static.seedrouter.ai/media/tasks/task_example/1.png",
      "size": "1455x721",
      "output_format": "png",
      "background": "transparent",
      "z_index": 1,
      "name": "Dark blue serif main title text with dash decorations",
      "description": "Dark blue serif main title text reading \"BLUE TIDE SESSIONS\", with short horizontal dash decorations on its left and right sides.",
      "bounding_box": { "absolute": [0, 0, 836, 414], "normalized": [0, 0, 1000, 330] },
      "text_recognition": {
        "text": "BLUE TIDE\nSESSIONS",
        "lines": [
          {
            "bounding_box": { "absolute": [146, 69, 694, 196], "normalized": [175, 55, 830, 156] },
            "runs": [
              {
                "text": "BLUE TIDE",
                "style": { "similar_font_family": "HTF Didot", "foreground_color": "#122C4D", "bold": false, "italic": false, "underline": false, "strikethrough": false, "shadow": false, "translucent": false }
              }
            ]
          },
          {
            "bounding_box": { "absolute": [175, 168, 664, 300], "normalized": [209, 134, 794, 239] },
            "runs": [
              {
                "text": "SESSIONS",
                "style": { "similar_font_family": "HTF Didot", "foreground_color": "#122C4D", "bold": false, "italic": false, "underline": false, "strikethrough": false, "shadow": false, "translucent": false }
              }
            ]
          }
        ]
      }
    }
  ]
}

저희 테스트에서 1K 이미지는 47초, 참조 이미지 한 장을 사용한 2K 편집은 40초, 이미지 네 장을 반환한 1K 레이어 분리는 39초가 걸렸습니다. 많은 레이어로 분리하면 몇 분이 걸릴 수 있습니다.

오류

태스크가 생성되기 전에 거부된 요청은 HTTP 오류와 error 객체를 반환하며 과금되지 않습니다. 접수된 뒤 실패한 태스크는 조회 시 HTTP 200과 함께 status: "failed" 및 error 객체를 반환합니다.

코드, HTTP 상태, 재시도 지침은 공통 오류 카탈로그를 참고하세요.

{
  "id": "task_...",
  "model": "seedream-5-5",
  "status": "failed",
  "error": {
    "code": 60001,
    "message": "The request was rejected by the content policy. Please revise the prompt or input images."
  }
}

제출 자체가 타임아웃된 경우에는 다시 보내기 전에 태스크 목록을 확인하세요. 첫 번째 요청이 이미 접수되었을 수 있습니다.

팁

• 1K 또는 1.5K로 시작해 시안을 만드세요. 1.5K와 1K는 비용이 같습니다.
• 고정된 화면 형태에는 정확한 픽셀 크기를 쓰세요. 예를 들어 2K의 16:9에는 2560x1440을 씁니다.
• 모든 참조 이미지에는 비용이 듭니다. 편집에 필요한 이미지만 보내세요.
• 레이어 분리에서는 예상하는 요소 수에 가깝게 max_images를 설정하세요. 예약 금액도 그에 따릅니다.
• 주로 텍스트를 원한다면 text_recognition을 켠 분리 요청에서 prompt를 생략하세요.

관련 자료

• Seedream 5.5 Playground와 가격
• Seedream 5.0 Pro API
• OpenAPI 다운로드
• 복사 가능한 Markdown